Doc Maintainer <biancas@aura.services> v1.01, 15-04-2020 :favicon: ./images/favicon/favicon.ico

This doc serves as a guide to setting up an integration with AURA from scratch. It should cover everything from gaining access to the API to guidelines around consuming the API in such a way that AURA will be able to best assist your client.

NDA

Before requesting access an AURA NDA signed by both parties needs to be in place. Without this nothing can move further on any potential integration. If you want to reach out for a potential integration or just need to get the NDA sorted please contact ryan@aura.services or warren@aura.services.

Obtaining API Access

Once you have a signed NDA in place, reach out to our developer team (developers@aura.services) and they will add you to the AURA slack. From there they will create credentials and authorize you for API access to the staging environment.

They will send you the following via Dead-Drop:

  • ClientId (GUID)

  • ClientSecret (secret)

  • RequestTypes (Eg: INTEGRATION & INTEGRATION_TEST)

Once these have been received and the developers confirm that API access is enabled, your integration will be up and running on our staging environment (https://staging-panic.aura.service).

All testing during development should be done against the staging envirnonment. Once development is complete you can request Demo access on the production environment. The Demo access shall be used as the final testing stage and for any necessary demonstrations needed on the integrator’s side before going live.

Differentiating Token Types

There are two types of tokens in the AURA ecosystem: Server and user tokens. If you are having issues determining whether a token belongs to a server or a user, https://jwt.io has a great tool for inspecting token contents.

Server Tokens

A server token is used to manage users. This includes everything from user creation to subscription querying and deactivation. A valid clientId and secret with AURA API access is required to obtain a server token.

In special cases a server token can be used to create a panic however this feature is not turned on by default. If you think your use case requires the ability to panic with a server token please contact the development team via email (developers@aura.services).

Server tokens are extremely long lived and be cached indefinitely on your backend.

User Tokens

A user token serves to uniquely identify a customer to the AURA backend. Primarily a user token is used to create and update panics for an individual customer.

In order to obtain a user token, the user will first need to be registered via a POST to the /oauth/user endpoint with an email and password as required fields.

The email used does not necessarily need to be the customers email and can instead be a unique identifier for the user on your system eg: guid_1234@mycompany.com. AURA does not have access to the password used to register/authenticate a user. The dev team is able to initiate a password reset request if the password is lost.

User tokens are valid from approximately 500 years from issue. This allows them to be effectively cached on mobile devices and servers for re-use without requiring an additional call to fetch a new token.

Generally we recommend that the user token is obtained on registration and kept available in some persistent store.

Creating and Managing Callouts

Creating a Callout

To create a callout you will need to send a request with all the required information to the /callouts endpoint:

Every callout created has a single response type. The response type is used to distinguish the type of response vehicles to ring. There are currently three different response types on the Aura network, namely: Security, Medical and Demo.

The responseTypeId on the callout object is optional. The system will default the responseTypeId to security if no responseTypeId is specified. Please communicate with the Aura team at developers@aura.services if you think your integration should default to a response type other than security (armed response).

If your integration requires numerous response types, for example a request security response button and a request medical response button, the responseTypeId on the specific callouts must change accordingly. Adding additional response types does, however come at additional cost, please contact the Aura team via developers@aura.services for more information.

Here the calloutClassificationId is optional. There are currently two types of classifications available: REAL and TEST. Passing in a calloutClassificationId allows you to provide additional contextual information to the AURA controllers so that they can better service your clients.

By passing in the TEST classificationId when executing a test flow, you will be able to prevent a responder from being auto-dispatched unless a controller verifies that response is required.

These classificationIds change infrequently and can be persisted for the most part. You can fetch all the classificationIds available by making a request to:

GET /callout-classifications

From there a callout can be created with the following request:

POST /callouts

Body:
{
    "calloutClassificationId": 2,
    "customer": {
        "name": "Test",
        "surname": "Test",
        "email": "test@mail.com",
        "mobile": "+27761234567",
        "gender": "Neutral",
        "vehicleMake": "Alfa Romeo",
        "vehicleModel": "4c",
        "vehicleColour": "Red",
        "vehicleLicensePlate": "TEST GP"
    },
    "calloutLocation": {
        "latitude": -26.109054,
        "longitude": 28.083,
        "accuracy": 50.0
    },
    responseTypeId: 1
}

Once created you will receive a response object with callout.id present. This id will be used to update locations and retrieve information for a specific callout.

Maintaining Callout State

Once a user has initiated a callout, that callout should be active for the user (after closing, re-opening the app etc) until one of the following conditions is satisfied.

  • The callout status is updated to one of the following: ['Responder Cancelled', 'Responder Completed', 'closed'].

  • The user soft cancels the panic via a POST to the callouts/{calloutId}/dismiss endpoint. NB: Soft cancel has a side effect related to location updates. More info at Callout Location Updates

Callout Polling

When a user has an active callout they should be polling for updates for the callout at set intervals until the callout reaches a closed status. This is to ensure that the user receives frequent updates about the responder moving to assist them. Recommended polling interval is between 10 and 20 seconds.

Poll a callout for update by sending a GET request to /callouts/{calloutId}.

When polling for a callout you can optionally retrieve the route the responder is being navigated via google maps. This is done by adding the shouldIncludeRoute=true query parameter onto your request i.e

GET /callouts/{calloutId}?shouldIncludeRoute=true

This will return the route polygons in the response object when a responder is attached to the callout.

Callout Location Updates

On successfully creating a panic, a user should be sending location updates every 10 seconds via a POST to /callouts/{calloutId}/location.

More often than not, a user is mobile during a situation requiring armed response and frequent location updates will best enable the responder to locate and assist the user.

Accuracy of location updates is also incredibly important. If a GPS module is reporting a accuracy metric of 1000m, the responder will struggle to locate the user reliably. Generally only locations with an accuracy metric of less than 50m should be sent through to the AURA API.

During stressful situations, users are also prone to minimizing or closing apps in order to make phone calls, use WhatsApp etc. Making sure that background location services are available in your app will further improve the chances of the responder getting to and assisting the user.

Cancelling a Callout

Currently AURA only exposes a soft cancel via the API. This means that even when a soft cancel is received (via the callouts/{calloutId}/dismiss), response will still proceed until the controllers have contacted the client and confirmed that no response is required.

If you intend to make use of the soft cancel, we recommend that your UI reflects the cancel (i.e the callout info disappears) but location updates are still sent and the callout is still polled until the closed status is received.

This is to cater for situations where response is still required but a forced cancel has happened on the users app. So a responder will still be able to locate the user if they do not confirm the cancel with the AURA controllers.

Callout Status Flow

There are several statuses that a callout may move through on the AURA API depending on the situation at hand. For example if a callout location is in an area where AURA does not have coverage, a manual dispatch may be used to get assistance to the user.

The AURA API currently has the following statuses:

  • created

  • Responder Dispatched

  • Responder Cancelled

  • Responder Arrived

  • Responder Completed

  • closed

The flow between these statuses can be seen below:

callout status flow

For development purposes, you can find examples of the API responses for the different statuses below.

Created API Example Response

{
    "id": 570,
    "calloutClassificationId: 2,
    "cancelledByCustomer": false,
    "status": "created",
    "verified": null,
    "verifiedBy": null,
    "verifiedAt": null,
    "resolvedAt": null,
    "loggedAt": "2019-06-26T08:26:34.148Z",
    "createdAt": "2019-06-26T08:26:34.150Z",
    "updatedAt": "2019-06-26T08:26:49.451Z",
    "lastUpdatedBy": null,
    "lastUpdatedByClientId": null,
    "source": null,
    "dispatchRequired": true,
    "acknowledged": true,
    "firstAcknowledgedBy": "grantm@aura-app.io",
    "firstAcknowledgedAt": "2019-06-26T08:26:49.451Z",
    "owned": false,
    "ownedBy": null,
    "ownedAt": null,
    "messageId": null,
    "customerId": 141,
    "responseTypeId" : 1,
    "calloutResponderInRanges": [
        {
            "id": 80,
            "calloutId": 570,
            "responderId": 8,
            "requested": false,
            "declined": false,
            "distance": 1213,
            "duration": 195,
            "durationText": "3 mins",
            "acknowledged": false,
            "retractedAt": null,
            "createdAt": "2019-06-26T08:26:49.616Z",
            "updatedAt": "2019-06-26T08:27:50.002Z"
        }
    ],
    "calloutincidentdetail": {
        "id": 570,
        "incidentDetails": null,
        "responderCompany": null,
        "responderDispatched": false,
        "calloutId": 570,
        "responderDispatchedAt": null,
        "responderArrivedAt": null,
        "responderCompletedAt": null,
        "createdAt": "2019-06-26T08:26:34.313Z",
        "situationNeutral": null,
        "anyInjuries": null,
        "customerHappy": null,
        "followUpRequired": null,
        "updatedAt": "2019-06-26T08:26:34.313Z",
        "lastUpdatedBy": null,
        "responderId": null,
        "supplierId": null,
        "typeOfEmergencyId": null,
        "incidentCategoryId": null,
        "incidentcategory": null,
        "supplier": null,
        "responder": null
    },
    "customer": {
        "id": 141,
        "name": "Testy",
        "surname": "McTestFace",
        "mobile": "+27831234567",
        "gender": "Male",
        "email": "subtest@test.com",
        "vehicleMake": "Box",
        "vehicleModel": "WithWheels",
        "vehicleColour": "Purple",
        "vehicleLicensePlate": "TESTY GP",
        "customerSourceId": 8,
        "dateOfBirth": null,
        "auth0UserId": "auth0|5cdd512da336360eb85bc175",
        "createdAt": "2019-05-16T12:01:49.835Z",
        "updatedAt": "2019-06-26T08:26:34.048Z"
    },
    "customerNumberPhoneds": [],
    "calloutlocations": [
        {
            "id": 951,
            "latitude": "-26.1090954",
            "longitude": "28.0830046",
            "formattedAddress": "33 4th St, Wynberg, Sandton, 2090, South Africa",
            "region": "Gauteng",
            "city": "Sandton",
            "country": "South Africa",
            "description": null,
            "placeId": null,
            "calloutId": 570,
            "createdAt": "2019-06-26T08:26:35.011Z",
            "updatedAt": "2019-06-26T08:26:35.011Z",
            "source": "PANIC_APP"
        }
    ],
    "calloutResponseEta": [],
    "location": {
        "id": 951,
        "latitude": "-26.1090954",
        "longitude": "28.0830046",
        "formattedAddress": "33 4th St, Wynberg, Sandton, 2090, South Africa",
        "region": "Gauteng",
        "city": "Sandton",
        "country": "South Africa",
        "description": null,
        "placeId": null,
        "calloutId": 570,
        "createdAt": "2019-06-26T08:26:35.011Z",
        "updatedAt": "2019-06-26T08:26:35.011Z",
        "source": "PANIC_APP"
    },
    "distance": {
        "distance": {},
        "duration": {}
    },
    "uniqueSuppliersInRange": [
        109
    ]
}

Responder Dispatched (Tech) API Example Response

{
    "id": 570,
    "calloutClassificationId: 2,
    "cancelledByCustomer": false,
    "status": "Responder Dispatched",
    "verified": true,
    "verifiedBy": "grantm@aura-app.io",
    "verifiedAt": "2019-06-26T08:29:03.340Z",
    "resolvedAt": null,
    "loggedAt": "2019-06-26T08:26:34.148Z",
    "createdAt": "2019-06-26T08:26:34.150Z",
    "updatedAt": "2019-06-26T08:29:22.142Z",
    "lastUpdatedBy": "grantm@aura-app.io",
    "lastUpdatedByClientId": null,
    "source": null,
    "dispatchRequired": true,
    "acknowledged": true,
    "firstAcknowledgedBy": "grantm@aura-app.io",
    "firstAcknowledgedAt": "2019-06-26T08:26:49.451Z",
    "owned": true,
    "ownedBy": "grantm@aura-app.io",
    "ownedAt": "2019-06-26T08:28:57.630Z",
    "messageId": null,
    "customerId": 141,
    "responseTypeId" : 1,
    "calloutResponderInRanges": [
        {
            "id": 80,
            "calloutId": 570,
            "responderId": 8,
            "requested": true,
            "declined": false,
            "distance": 1213,
            "duration": 195,
            "durationText": "3 mins",
            "acknowledged": true,
            "retractedAt": null,
            "createdAt": "2019-06-26T08:26:49.616Z",
            "updatedAt": "2019-06-26T08:29:22.169Z"
        }
    ],
    "calloutincidentdetail": {
        "id": 570,
        "incidentDetails": null,
        "responderCompany": "Suppy Liar",
        "responderDispatched": true,
        "calloutId": 570,
        "responderDispatchedAt": "2019-06-26T08:29:22.141Z",
        "responderArrivedAt": null,
        "responderCompletedAt": null,
        "createdAt": "2019-06-26T08:26:34.313Z",
        "situationNeutral": null,
        "anyInjuries": null,
        "customerHappy": null,
        "followUpRequired": null,
        "updatedAt": "2019-06-26T08:29:22.150Z",
        "lastUpdatedBy": null,
        "responderId": 8,
        "supplierId": 109,
        "typeOfEmergencyId": null,
        "incidentCategoryId": null,
        "incidentcategory": null,
        "supplier": {
            "id": 109,
            "name": "Suppy Liar",
            "contactNumber": "+27761684187",
            "email": "grantm+localsupplier@aura-app.io",
            "contactPerson": "Grant Macwilliam",
            "address": "16 4th Street Wynberg",
            "region": "Gauteng",
            "createdAt": "2019-01-14T06:38:26.523Z",
            "updatedAt": "2019-01-14T06:38:26.523Z",
            "lastUpdatedBy": null,
            "calloutRequiresDispatchApproval": false,
            "supplierLogoUrl": null,
            "deleted": false
        },
        "responder": {
            "id": 8,
            "name": "Testy",
            "surname": "McTestFace",
            "callsign": "testy",
            "reference": "testy",
            "mobile": "grantm+localresponder@aura.services",
            "vehicleMake": "Boxcart",
            "vehicleModel": "Cardboard",
            "vehicleColour": "Purple",
            "vehicleLicensePlate": "derp",
            "active": false,
            "currentlyOnCall": true,
            "createdAt": "2019-03-20T09:00:27.045Z",
            "updatedAt": "2019-06-26T08:29:13.662Z",
            "operationTimeId": 1,
            "typeId": 1,
            "deleted": false,
            "latestResponderLocationId": 600,
            "supplierId": 109,
            "responderlocations": [
                {
                    "id": 600,
                    "latitude": "-26.113298333333333",
                    "longitude": "28.084800000000005",
                    "accuracy": 20,
                    "provider": "gps",
                    "activityStatus": "",
                    "formattedAddress": null,
                    "region": null,
                    "city": null,
                    "country": null,
                    "createdAt": "2019-06-26T08:29:13.655Z",
                    "updatedAt": "2019-06-26T08:29:13.655Z",
                    "responderId": 8
                }
            ]
        }
    },
    "customer": {
        "id": 141,
        "name": "Testy",
        "surname": "McTestFace",
        "mobile": "+27831234567",
        "gender": "Male",
        "email": "subtest@test.com",
        "vehicleMake": "Box",
        "vehicleModel": "WithWheels",
        "vehicleColour": "Purple",
        "vehicleLicensePlate": "TESTY GP",
        "customerSourceId": 8,
        "dateOfBirth": null,
        "auth0UserId": "auth0|5cdd512da336360eb85bc175",
        "createdAt": "2019-05-16T12:01:49.835Z",
        "updatedAt": "2019-06-26T08:26:34.048Z"
    },
    "customerNumberPhoneds": [],
    "calloutResponseEta": [
        {
            "id": 277,
            "calloutId": 570,
            "responderId": 8,
            "durationText": "3 mins",
            "durationValue": 195,
            "distanceText": "1.2 km",
            "distanceValue": 1213,
            "createdAt": "2019-06-26T08:29:22.541Z",
            "updatedAt": "2019-06-26T08:29:22.541Z"
        }
    ],
    "calloutlocations": [
        {
            "id": 951,
            "latitude": "-26.1090954",
            "longitude": "28.0830046",
            "formattedAddress": "33 4th St, Wynberg, Sandton, 2090, South Africa",
            "region": "Gauteng",
            "city": "Sandton",
            "country": "South Africa",
            "description": null,
            "placeId": null,
            "calloutId": 570,
            "createdAt": "2019-06-26T08:26:35.011Z",
            "updatedAt": "2019-06-26T08:26:35.011Z",
            "source": "PANIC_APP",
            "durationText": "3 mins"
        }
    ],
    "location": {
        "id": 951,
        "latitude": "-26.1090954",
        "longitude": "28.0830046",
        "formattedAddress": "33 4th St, Wynberg, Sandton, 2090, South Africa",
        "region": "Gauteng",
        "city": "Sandton",
        "country": "South Africa",
        "description": null,
        "placeId": null,
        "calloutId": 570,
        "createdAt": "2019-06-26T08:26:35.011Z",
        "updatedAt": "2019-06-26T08:26:35.011Z",
        "source": "PANIC_APP",
        "durationText": "3 mins"
    },
    "distance": {
        "distance": {
            "text": "1.2 km",
            "value": 1213
        },
        "duration": {
            "text": "3 mins",
            "value": 195
        }
    },
    "uniqueSuppliersInRange": [
        109
    ]
}

Responder Dispatched (Manual) API Example Response

Note that a supplier object is present here. So the user has access to which response company is proceeding but not the specific responder details.

{
    "id": 21671,
    "calloutClassificationId: 2,
    "cancelledByCustomer": false,
    "status": "Responder Dispatched",
    "verified": true,
    "verifiedBy": null,
    "verifiedAt": "2019-10-21T08:27:18.985Z",
    "resolvedAt": null,
    "loggedAt": "2019-10-21T08:27:18.559Z",
    "createdAt": "2019-10-21T08:27:18.560Z",
    "updatedAt": "2019-10-21T08:27:33.201Z",
    "lastUpdatedBy": "grantm@aura-app.io",
    "lastUpdatedByClientId": null,
    "source": null,
    "dispatchRequired": true,
    "acknowledged": true,
    "firstAcknowledgedBy": "grantm@aura-app.io",
    "firstAcknowledgedAt": "2019-10-21T08:27:25.092Z",
    "owned": true,
    "ownedBy": "grantm@aura-app.io",
    "ownedAt": "2019-10-21T08:27:27.240Z",
    "messageId": null,
    "customerId": 538,
    "responseTypeId" : 1,
    "calloutResponderInRanges": [
        {
            "id": 9574,
            "calloutId": 21671,
            "responderId": 122,
            "requested": true,
            "declined": true,
            "distance": 112,
            "duration": 17,
            "durationText": "1 min",
            "acknowledged": false,
            "retractedAt": null,
            "createdAt": "2019-10-21T08:27:19.208Z",
            "updatedAt": "2019-10-21T08:27:33.945Z"
        }
    ],
    "calloutincidentdetail": {
        "id": 21622,
        "incidentDetails": null,
        "responderCompany": null,
        "responderDispatched": true,
        "calloutId": 21671,
        "responderDispatchedAt": "2019-10-21T08:27:29.483Z",
        "responderArrivedAt": null,
        "responderCompletedAt": null,
        "createdAt": "2019-10-21T08:27:18.579Z",
        "situationNeutral": null,
        "anyInjuries": null,
        "customerHappy": null,
        "followUpRequired": null,
        "updatedAt": "2019-10-21T08:27:33.194Z",
        "lastUpdatedBy": "grantm@aura-app.io",
        "responderId": null,
        "supplierId": 14,
        "typeOfEmergencyId": null,
        "incidentCategoryId": null,
        "incidentcategory": null,
        "supplier": {
            "id": 14,
            "name": "Alpha Security",
            "contactNumber": "0834855419",
            "email": "john@alphasecurity.co.za",
            "contactPerson": "John Kieser",
            "address": "",
            "region": "Gauteng",
            "createdAt": "2017-05-22T14:01:00.065Z",
            "updatedAt": "2017-05-22T14:01:00.065Z",
            "lastUpdatedBy": null,
            "calloutRequiresDispatchApproval": false,
            "supplierLogoUrl": null,
            "deleted": false
        },
        "responder": null
    },
    "customer": {
        "id": 538,
        "name": "Keenan ",
        "surname": "George",
        "mobile": "0835851927",
        "gender": "",
        "email": "keenangrg@gmail.com",
        "vehicleMake": "",
        "vehicleModel": "",
        "vehicleColour": "",
        "vehicleLicensePlate": "",
        "customerSourceId": 42,
        "dateOfBirth": null,
        "auth0UserId": "auth0|5c7508db86cc3d2ece20fae1",
        "imageId": null,
        "createdAt": "2019-02-26T10:14:02.745Z",
        "updatedAt": "2019-10-21T08:10:43.775Z"
    },
    "customerNumberPhoneds": [],
    "calloutResponseEta": [],
    "calloutlocations": [
        {
            "id": 165222,
            "latitude": "-33.8633854",
            "longitude": "18.6414994",
            "formattedAddress": "29 Bella Rosa St, Rosenpark, Cape Town, 7550, South Africa",
            "region": "Western Cape",
            "city": "Cape Town",
            "country": "South Africa",
            "description": null,
            "placeId": null,
            "calloutId": 21671,
            "createdAt": "2019-10-21T08:27:18.778Z",
            "updatedAt": "2019-10-21T08:27:18.778Z",
            "source": "PANIC_APP"
        }
    ],
    "location": {
        "id": 165222,
        "latitude": "-33.8633854",
        "longitude": "18.6414994",
        "formattedAddress": "29 Bella Rosa St, Rosenpark, Cape Town, 7550, South Africa",
        "region": "Western Cape",
        "city": "Cape Town",
        "country": "South Africa",
        "description": null,
        "placeId": null,
        "calloutId": 21671,
        "createdAt": "2019-10-21T08:27:18.778Z",
        "updatedAt": "2019-10-21T08:27:18.778Z",
        "source": "PANIC_APP"
    },
    "distance": {
        "distance": {},
        "duration": {}
    },
    "uniqueSuppliersInRange": [
        46
    ]
}

Responder Cancelled API Example Response

{
    "id": 9301,
    "calloutClassificationId: 2,
    "cancelledByCustomer": false,
    "status": "Responder Cancelled",
    "verified": true,
    "verifiedBy": "grantm@aura-app.io",
    "verifiedAt": "2019-07-11T08:04:00.604Z",
    "resolvedAt": null,
    "loggedAt": "2019-07-11T08:03:13.873Z",
    "createdAt": "2019-07-11T08:03:13.874Z",
    "updatedAt": "2019-07-11T08:04:11.648Z",
    "lastUpdatedBy": "grantm@aura-app.io",
    "lastUpdatedByClientId": null,
    "source": null,
    "dispatchRequired": true,
    "acknowledged": true,
    "firstAcknowledgedBy": "grantm@aura-app.io",
    "firstAcknowledgedAt": "2019-07-11T08:03:44.900Z",
    "owned": true,
    "ownedBy": "grantm@aura-app.io",
    "ownedAt": "2019-07-11T08:03:47.837Z",
    "messageId": null,
    "customerId": 686,
    "responseTypeId" : 1,
    "calloutResponderInRanges": [
        {
            "id": 40790,
            "calloutId": 9301,
            "responderId": 112,
            "requested": true,
            "declined": false,
            "distance": 1113,
            "duration": 176,
            "durationText": "3 mins",
            "acknowledged": true,
            "retractedAt": "2019-07-11T08:04:11.632Z",
            "createdAt": "2019-07-11T08:03:39.110Z",
            "updatedAt": "2019-07-11T08:04:11.632Z"
        }
    ],
    "calloutincidentdetail": {
        "id": 9267,
        "incidentDetails": null,
        "responderCompany": null,
        "responderDispatched": false,
        "calloutId": 9301,
        "responderDispatchedAt": null,
        "responderArrivedAt": null,
        "responderCompletedAt": null,
        "createdAt": "2019-07-11T08:03:13.893Z",
        "situationNeutral": null,
        "anyInjuries": null,
        "customerHappy": null,
        "followUpRequired": null,
        "updatedAt": "2019-07-11T08:04:11.654Z",
        "lastUpdatedBy": null,
        "responderId": null,
        "supplierId": null,
        "typeOfEmergencyId": null,
        "incidentCategoryId": null,
        "incidentcategory": null,
        "supplier": null,
        "responder": null
    },
    "customer": {
        "id": 686,
        "name": "Testy",
        "surname": "McTestFace",
        "mobile": "+27831234567",
        "gender": "Male",
        "email": "subtest@test.com",
        "vehicleMake": "Box",
        "vehicleModel": "WithWheels",
        "vehicleColour": "Purple",
        "vehicleLicensePlate": "TESTY GP",
        "customerSourceId": 38,
        "dateOfBirth": null,
        "auth0UserId": "auth0|5cdd512da336360eb85bc175",
        "createdAt": "2019-05-28T09:08:29.034Z",
        "updatedAt": "2019-07-03T14:49:46.534Z"
    },
    "customerNumberPhoneds": [],
    "calloutlocations": [
        {
            "id": 79847,
            "latitude": "-25.8382",
            "longitude": "28.19032",
            "formattedAddress": "237 Glover Ave, Die Hoewes, Centurion, 0163, South Africa",
            "region": "Gauteng",
            "city": "Centurion",
            "country": "South Africa",
            "description": null,
            "placeId": null,
            "calloutId": 9301,
            "createdAt": "2019-07-11T08:03:14.096Z",
            "updatedAt": "2019-07-11T08:03:14.096Z",
            "source": "PANIC_APP",
            "durationText": "3 mins"
        }
    ],
    "calloutResponseEta": [
        {
            "id": 5523,
            "calloutId": 9301,
            "responderId": 112,
            "durationText": "3 mins",
            "durationValue": 175,
            "distanceText": "1.1 km",
            "distanceValue": 1113,
            "createdAt": "2019-07-11T08:04:06.583Z",
            "updatedAt": "2019-07-11T08:04:06.583Z"
        }
    ],
    "location": {
        "id": 79847,
        "latitude": "-25.8382",
        "longitude": "28.19032",
        "formattedAddress": "237 Glover Ave, Die Hoewes, Centurion, 0163, South Africa",
        "region": "Gauteng",
        "city": "Centurion",
        "country": "South Africa",
        "description": null,
        "placeId": null,
        "calloutId": 9301,
        "createdAt": "2019-07-11T08:03:14.096Z",
        "updatedAt": "2019-07-11T08:03:14.096Z",
        "source": "PANIC_APP",
        "durationText": "3 mins"
    },
    "distance": {
        "distance": {
            "text": "1.1 km",
            "value": 1113
        },
        "duration": {
            "text": "3 mins",
            "value": 175
        }
    },
    "uniqueSuppliersInRange": []
}

Responder Arrived API Example Response

{
    "id": 570,
    "calloutClassificationId: 2,
    "cancelledByCustomer": false,
    "status": "Responder Arrived",
    "verified": true,
    "verifiedBy": "grantm@aura-app.io",
    "verifiedAt": "2019-06-26T08:29:03.340Z",
    "resolvedAt": null,
    "loggedAt": "2019-06-26T08:26:34.148Z",
    "createdAt": "2019-06-26T08:26:34.150Z",
    "updatedAt": "2019-06-26T08:31:08.848Z",
    "lastUpdatedBy": "grantm@aura-app.io",
    "lastUpdatedByClientId": null,
    "source": null,
    "dispatchRequired": true,
    "acknowledged": true,
    "firstAcknowledgedBy": "grantm@aura-app.io",
    "firstAcknowledgedAt": "2019-06-26T08:26:49.451Z",
    "owned": true,
    "ownedBy": "grantm@aura-app.io",
    "ownedAt": "2019-06-26T08:28:57.630Z",
    "messageId": null,
    "customerId": 141,
    "responseTypeId" : 1,
    "calloutResponderInRanges": [
        {
            "id": 80,
            "calloutId": 570,
            "responderId": 8,
            "requested": true,
            "declined": false,
            "distance": 1213,
            "duration": 195,
            "durationText": "3 mins",
            "acknowledged": true,
            "retractedAt": null,
            "createdAt": "2019-06-26T08:26:49.616Z",
            "updatedAt": "2019-06-26T08:29:22.169Z"
        }
    ],
    "calloutincidentdetail": {
        "id": 570,
        "incidentDetails": null,
        "responderCompany": "Suppy Liar",
        "responderDispatched": true,
        "calloutId": 570,
        "responderDispatchedAt": "2019-06-26T08:29:22.141Z",
        "responderArrivedAt": "2019-06-26T08:31:08.847Z",
        "responderCompletedAt": null,
        "createdAt": "2019-06-26T08:26:34.313Z",
        "situationNeutral": null,
        "anyInjuries": null,
        "customerHappy": null,
        "followUpRequired": null,
        "updatedAt": "2019-06-26T08:31:08.857Z",
        "lastUpdatedBy": null,
        "responderId": 8,
        "supplierId": 109,
        "typeOfEmergencyId": null,
        "incidentCategoryId": null,
        "incidentcategory": null,
        "supplier": {
            "id": 109,
            "name": "Suppy Liar",
            "contactNumber": "+27761684187",
            "email": "grantm+localsupplier@aura-app.io",
            "contactPerson": "Grant Macwilliam",
            "address": "16 4th Street Wynberg",
            "region": "Gauteng",
            "createdAt": "2019-01-14T06:38:26.523Z",
            "updatedAt": "2019-01-14T06:38:26.523Z",
            "lastUpdatedBy": null,
            "calloutRequiresDispatchApproval": false,
            "supplierLogoUrl": null,
            "deleted": false
        },
        "responder": {
            "id": 8,
            "name": "Testy",
            "surname": "McTestFace",
            "callsign": "testy",
            "reference": "testy",
            "mobile": "grantm+localresponder@aura.services",
            "vehicleMake": "Boxcart",
            "vehicleModel": "Cardboard",
            "vehicleColour": "Purple",
            "vehicleLicensePlate": "derp",
            "active": false,
            "currentlyOnCall": true,
            "createdAt": "2019-03-20T09:00:27.045Z",
            "updatedAt": "2019-06-26T08:31:08.763Z",
            "operationTimeId": 1,
            "typeId": 1,
            "deleted": false,
            "latestResponderLocationId": 601,
            "supplierId": 109,
            "responderlocations": [
                {
                    "id": 601,
                    "latitude": "-26.109095000000003",
                    "longitude": "28.083003333333334",
                    "accuracy": 20,
                    "provider": "gps",
                    "activityStatus": "",
                    "formattedAddress": null,
                    "region": null,
                    "city": null,
                    "country": null,
                    "createdAt": "2019-06-26T08:31:08.744Z",
                    "updatedAt": "2019-06-26T08:31:08.744Z",
                    "responderId": 8
                }
            ]
        }
    },
    "customer": {
        "id": 141,
        "name": "Testy",
        "surname": "McTestFace",
        "mobile": "+27831234567",
        "gender": "Male",
        "email": "subtest@test.com",
        "vehicleMake": "Box",
        "vehicleModel": "WithWheels",
        "vehicleColour": "Purple",
        "vehicleLicensePlate": "TESTY GP",
        "customerSourceId": 8,
        "dateOfBirth": null,
        "auth0UserId": "auth0|5cdd512da336360eb85bc175",
        "createdAt": "2019-05-16T12:01:49.835Z",
        "updatedAt": "2019-06-26T08:26:34.048Z"
    },
    "customerNumberPhoneds": [],
    "calloutlocations": [
        {
            "id": 951,
            "latitude": "-26.1090954",
            "longitude": "28.0830046",
            "formattedAddress": "33 4th St, Wynberg, Sandton, 2090, South Africa",
            "region": "Gauteng",
            "city": "Sandton",
            "country": "South Africa",
            "description": null,
            "placeId": null,
            "calloutId": 570,
            "createdAt": "2019-06-26T08:26:35.011Z",
            "updatedAt": "2019-06-26T08:26:35.011Z",
            "source": "PANIC_APP",
            "durationText": "1 min"
        }
    ],
    "calloutResponseEta": [
        {
            "id": 278,
            "calloutId": 570,
            "responderId": 8,
            "durationText": "1 min",
            "durationValue": 0,
            "distanceText": "1 m",
            "distanceValue": 0,
            "createdAt": "2019-06-26T08:31:09.216Z",
            "updatedAt": "2019-06-26T08:31:09.216Z"
        }
    ],
    "location": {
        "id": 951,
        "latitude": "-26.1090954",
        "longitude": "28.0830046",
        "formattedAddress": "33 4th St, Wynberg, Sandton, 2090, South Africa",
        "region": "Gauteng",
        "city": "Sandton",
        "country": "South Africa",
        "description": null,
        "placeId": null,
        "calloutId": 570,
        "createdAt": "2019-06-26T08:26:35.011Z",
        "updatedAt": "2019-06-26T08:26:35.011Z",
        "source": "PANIC_APP",
        "durationText": "1 min"
    },
    "distance": {
        "distance": {
            "text": "1 m",
            "value": 0
        },
        "duration": {
            "text": "1 min",
            "value": 0
        }
    },
    "uniqueSuppliersInRange": [
        109
    ]
}

Responder Completed API Example Response

{
    "id": 570,
    "calloutClassificationId: 2,
    "cancelledByCustomer": false,
    "status": "Responder Completed",
    "verified": true,
    "verifiedBy": "grantm@aura-app.io",
    "verifiedAt": "2019-06-26T08:29:03.340Z",
    "resolvedAt": null,
    "loggedAt": "2019-06-26T08:26:34.148Z",
    "createdAt": "2019-06-26T08:26:34.150Z",
    "updatedAt": "2019-06-26T08:32:09.389Z",
    "lastUpdatedBy": "grantm@aura-app.io",
    "lastUpdatedByClientId": null,
    "source": null,
    "dispatchRequired": true,
    "acknowledged": true,
    "firstAcknowledgedBy": "grantm@aura-app.io",
    "firstAcknowledgedAt": "2019-06-26T08:26:49.451Z",
    "owned": true,
    "ownedBy": "grantm@aura-app.io",
    "ownedAt": "2019-06-26T08:28:57.630Z",
    "messageId": null,
    "customerId": 141,
    "responseTypeId" : 1,
    "calloutResponderInRanges": [
        {
            "id": 80,
            "calloutId": 570,
            "responderId": 8,
            "requested": true,
            "declined": false,
            "distance": 1213,
            "duration": 195,
            "durationText": "3 mins",
            "acknowledged": true,
            "retractedAt": null,
            "createdAt": "2019-06-26T08:26:49.616Z",
            "updatedAt": "2019-06-26T08:29:22.169Z"
        }
    ],
    "calloutincidentdetail": {
        "id": 570,
        "incidentDetails": null,
        "responderCompany": "Suppy Liar",
        "responderDispatched": true,
        "calloutId": 570,
        "responderDispatchedAt": "2019-06-26T08:29:22.141Z",
        "responderArrivedAt": "2019-06-26T08:31:08.847Z",
        "responderCompletedAt": "2019-06-26T08:32:09.371Z",
        "createdAt": "2019-06-26T08:26:34.313Z",
        "situationNeutral": null,
        "anyInjuries": false,
        "customerHappy": false,
        "followUpRequired": false,
        "updatedAt": "2019-06-26T08:32:09.405Z",
        "lastUpdatedBy": null,
        "responderId": 8,
        "supplierId": 109,
        "typeOfEmergencyId": 5,
        "incidentCategoryId": 24,
        "incidentcategory": {
            "id": 24,
            "description": "Test Callout",
            "createdAt": "2017-08-15T10:38:00.000Z",
            "updatedAt": "2017-08-15T10:38:00.000Z",
            "typeOfEmergencyId": 5,
            "typeofemergency": {
                "id": 5,
                "descript": "Test Callout",
                "createdA": "2017-08-15T10:37:00.000Z",
                "updatedA": "2017-08-15T10:37:00.000Z"
            }
        },
        "supplier": {
            "id": 109,
            "name": "Suppy Liar",
            "contactNumber": "+27761684187",
            "email": "grantm+localsupplier@aura-app.io",
            "contactPerson": "Grant Macwilliam",
            "address": "16 4th Street Wynberg",
            "region": "Gauteng",
            "createdAt": "2019-01-14T06:38:26.523Z",
            "updatedAt": "2019-01-14T06:38:26.523Z",
            "lastUpdatedBy": null,
            "calloutRequiresDispatchApproval": false,
            "supplierLogoUrl": null,
            "deleted": false
        },
        "responder": {
            "id": 8,
            "name": "Testy",
            "surname": "McTestFace",
            "callsign": "testy",
            "reference": "testy",
            "mobile": "grantm+localresponder@aura.services",
            "vehicleMake": "Boxcart",
            "vehicleModel": "Cardboard",
            "vehicleColour": "Purple",
            "vehicleLicensePlate": "derp",
            "active": false,
            "currentlyOnCall": false,
            "createdAt": "2019-03-20T09:00:27.045Z",
            "updatedAt": "2019-06-26T08:32:09.376Z",
            "operationTimeId": 1,
            "typeId": 1,
            "deleted": false,
            "latestResponderLocationId": 601,
            "supplierId": 109,
            "responderlocations": [
                {
                    "id": 601,
                    "latitude": "-26.109095000000003",
                    "longitude": "28.083003333333334",
                    "accuracy": 20,
                    "provider": "gps",
                    "activityStatus": "",
                    "formattedAddress": null,
                    "region": null,
                    "city": null,
                    "country": null,
                    "createdAt": "2019-06-26T08:31:08.744Z",
                    "updatedAt": "2019-06-26T08:31:08.744Z",
                    "responderId": 8
                }
            ]
        }
    },
    "customer": {
        "id": 141,
        "name": "Testy",
        "surname": "McTestFace",
        "mobile": "+27831234567",
        "gender": "Male",
        "email": "subtest@test.com",
        "vehicleMake": "Box",
        "vehicleModel": "WithWheels",
        "vehicleColour": "Purple",
        "vehicleLicensePlate": "TESTY GP",
        "customerSourceId": 8,
        "dateOfBirth": null,
        "auth0UserId": "auth0|5cdd512da336360eb85bc175",
        "createdAt": "2019-05-16T12:01:49.835Z",
        "updatedAt": "2019-06-26T08:26:34.048Z"
    },
    "customerNumberPhoneds": [],
    "calloutlocations": [
        {
            "id": 951,
            "latitude": "-26.1090954",
            "longitude": "28.0830046",
            "formattedAddress": "33 4th St, Wynberg, Sandton, 2090, South Africa",
            "region": "Gauteng",
            "city": "Sandton",
            "country": "South Africa",
            "description": null,
            "placeId": null,
            "calloutId": 570,
            "createdAt": "2019-06-26T08:26:35.011Z",
            "updatedAt": "2019-06-26T08:26:35.011Z",
            "source": "PANIC_APP",
            "durationText": "1 min"
        }
    ],
    "calloutResponseEta": [
        {
            "id": 278,
            "calloutId": 570,
            "responderId": 8,
            "durationText": "1 min",
            "durationValue": 0,
            "distanceText": "1 m",
            "distanceValue": 0,
            "createdAt": "2019-06-26T08:31:09.216Z",
            "updatedAt": "2019-06-26T08:31:09.216Z"
        }
    ],
    "location": {
        "id": 951,
        "latitude": "-26.1090954",
        "longitude": "28.0830046",
        "formattedAddress": "33 4th St, Wynberg, Sandton, 2090, South Africa",
        "region": "Gauteng",
        "city": "Sandton",
        "country": "South Africa",
        "description": null,
        "placeId": null,
        "calloutId": 570,
        "createdAt": "2019-06-26T08:26:35.011Z",
        "updatedAt": "2019-06-26T08:26:35.011Z",
        "source": "PANIC_APP",
        "durationText": "1 min"
    },
    "distance": {
        "distance": {
            "text": "1 m",
            "value": 0
        },
        "duration": {
            "text": "1 min",
            "value": 0
        }
    },
    "uniqueSuppliersInRange": [
        109
    ]
}

Closed API Example Response

{
    "id": 570,
    "calloutClassificationId: 2,
    "cancelledByCustomer": false,
    "status": "closed",
    "verified": true,
    "verifiedBy": "grantm@aura-app.io",
    "verifiedAt": "2019-06-26T08:29:03.340Z",
    "resolvedAt": "2019-06-26T08:32:44.000Z",
    "loggedAt": "2019-06-26T08:26:34.148Z",
    "createdAt": "2019-06-26T08:26:34.150Z",
    "updatedAt": "2019-06-26T08:32:44.257Z",
    "lastUpdatedBy": "grantm@aura-app.io",
    "lastUpdatedByClientId": null,
    "source": null,
    "dispatchRequired": true,
    "acknowledged": true,
    "firstAcknowledgedBy": "grantm@aura-app.io",
    "firstAcknowledgedAt": "2019-06-26T08:26:49.451Z",
    "owned": true,
    "ownedBy": "grantm@aura-app.io",
    "ownedAt": "2019-06-26T08:28:57.630Z",
    "messageId": null,
    "customerId": 141,
    "responseTypeId" : 1,
    "calloutResponderInRanges": [
        {
            "id": 80,
            "calloutId": 570,
            "responderId": 8,
            "requested": true,
            "declined": false,
            "distance": 1213,
            "duration": 195,
            "durationText": "3 mins",
            "acknowledged": true,
            "retractedAt": null,
            "createdAt": "2019-06-26T08:26:49.616Z",
            "updatedAt": "2019-06-26T08:29:22.169Z"
        }
    ],
    "calloutincidentdetail": {
        "id": 570,
        "incidentDetails": "test",
        "responderCompany": "Suppy Liar",
        "responderDispatched": true,
        "calloutId": 570,
        "responderDispatchedAt": "2019-06-26T08:29:22.000Z",
        "responderArrivedAt": "2019-06-26T08:31:08.000Z",
        "responderCompletedAt": "2019-06-26T08:32:09.371Z",
        "createdAt": "2019-06-26T08:26:34.313Z",
        "situationNeutral": null,
        "anyInjuries": false,
        "customerHappy": false,
        "followUpRequired": false,
        "updatedAt": "2019-06-26T08:32:44.238Z",
        "lastUpdatedBy": "grantm@aura-app.io",
        "responderId": 8,
        "supplierId": 109,
        "typeOfEmergencyId": 5,
        "incidentCategoryId": 24,
        "incidentcategory": {
            "id": 24,
            "description": "Test Callout",
            "createdAt": "2017-08-15T10:38:00.000Z",
            "updatedAt": "2017-08-15T10:38:00.000Z",
            "typeOfEmergencyId": 5,
            "typeofemergency": {
                "id": 5,
                "descript": "Test Callout",
                "createdA": "2017-08-15T10:37:00.000Z",
                "updatedA": "2017-08-15T10:37:00.000Z"
            }
        },
        "supplier": {
            "id": 109,
            "name": "Suppy Liar",
            "contactNumber": "+27761684187",
            "email": "grantm+localsupplier@aura-app.io",
            "contactPerson": "Grant Macwilliam",
            "address": "16 4th Street Wynberg",
            "region": "Gauteng",
            "createdAt": "2019-01-14T06:38:26.523Z",
            "updatedAt": "2019-01-14T06:38:26.523Z",
            "lastUpdatedBy": null,
            "calloutRequiresDispatchApproval": false,
            "supplierLogoUrl": null,
            "deleted": false
        },
        "responder": {
            "id": 8,
            "name": "Testy",
            "surname": "McTestFace",
            "callsign": "testy",
            "reference": "testy",
            "mobile": "grantm+localresponder@aura.services",
            "vehicleMake": "Boxcart",
            "vehicleModel": "Cardboard",
            "vehicleColour": "Purple",
            "vehicleLicensePlate": "derp",
            "active": false,
            "currentlyOnCall": false,
            "createdAt": "2019-03-20T09:00:27.045Z",
            "updatedAt": "2019-06-26T08:32:09.376Z",
            "operationTimeId": 1,
            "typeId": 1,
            "deleted": false,
            "latestResponderLocationId": 601,
            "supplierId": 109,
            "responderlocations": [
                {
                    "id": 601,
                    "latitude": "-26.109095000000003",
                    "longitude": "28.083003333333334",
                    "accuracy": 20,
                    "provider": "gps",
                    "activityStatus": "",
                    "formattedAddress": null,
                    "region": null,
                    "city": null,
                    "country": null,
                    "createdAt": "2019-06-26T08:31:08.744Z",
                    "updatedAt": "2019-06-26T08:31:08.744Z",
                    "responderId": 8
                }
            ]
        }
    },
    "customer": {
        "id": 141,
        "name": "Testy",
        "surname": "McTestFace",
        "mobile": "+27831234567",
        "gender": "Male",
        "email": "subtest@test.com",
        "vehicleMake": "Box",
        "vehicleModel": "WithWheels",
        "vehicleColour": "Purple",
        "vehicleLicensePlate": "TESTY GP",
        "customerSourceId": 8,
        "dateOfBirth": null,
        "auth0UserId": "auth0|5cdd512da336360eb85bc175",
        "createdAt": "2019-05-16T12:01:49.835Z",
        "updatedAt": "2019-06-26T08:26:34.048Z"
    },
    "customerNumberPhoneds": [],
    "calloutResponseEta": [
        {
            "id": 278,
            "calloutId": 570,
            "responderId": 8,
            "durationText": "1 min",
            "durationValue": 0,
            "distanceText": "1 m",
            "distanceValue": 0,
            "createdAt": "2019-06-26T08:31:09.216Z",
            "updatedAt": "2019-06-26T08:31:09.216Z"
        }
    ],
    "calloutlocations": [
        {
            "id": 951,
            "latitude": "-26.1090954",
            "longitude": "28.0830046",
            "formattedAddress": "33 4th St, Wynberg, Sandton, 2090, South Africa",
            "region": "Gauteng",
            "city": "Sandton",
            "country": "South Africa",
            "description": null,
            "placeId": null,
            "calloutId": 570,
            "createdAt": "2019-06-26T08:26:35.011Z",
            "updatedAt": "2019-06-26T08:26:35.011Z",
            "source": "PANIC_APP",
            "durationText": "1 min"
        }
    ],
    "location": {
        "id": 951,
        "latitude": "-26.1090954",
        "longitude": "28.0830046",
        "formattedAddress": "33 4th St, Wynberg, Sandton, 2090, South Africa",
        "region": "Gauteng",
        "city": "Sandton",
        "country": "South Africa",
        "description": null,
        "placeId": null,
        "calloutId": 570,
        "createdAt": "2019-06-26T08:26:35.011Z",
        "updatedAt": "2019-06-26T08:26:35.011Z",
        "source": "PANIC_APP",
        "durationText": "1 min"
    },
    "distance": {
        "distance": {
            "text": "1 m",
            "value": 0
        },
        "duration": {
            "text": "1 min",
            "value": 0
        }
    },
    "uniqueSuppliersInRange": [
        109
    ]
}

Adding and Polling Callout Events

You can add a message to a callout which can be seen by our control center. The message passed in is added to the event stream for the callout.

```
POST /callout/{calloutId}/comments
Body:
{
   "message": "This is an example message"
}
```

In order to receive replies from our controllers, you will need to add the shouldIncludeEvents=true query parameter to the callout polling. I.e

 GET /callouts/{calloutId}?shouldIncludeRoute=true

This will add a calloutEvents object to the response - see example below:

"calloutEvents": [
     {
         "id": 103,
         "calloutId": 1060,
         "calloutEventTypeId": 2,
         "event": {
             "body": "Another example message to add",
             "role": "User"
         },
         "createdBy": "Testy McTestFace",
         "createdAt": "2020-02-07T08:39:30.721Z",
         "updatedAt": "2020-02-07T08:39:30.721Z"
     },
     {
         "id": 104,
         "calloutId": 1060,
         "calloutEventTypeId": 2,
         "event": {
             "body": "Welcome",
             "role": "Admin"
     },
         "createdBy": "Grant",
         "createdAt": "2020-02-07T08:46:36.167Z",
     "updatedAt": "2020-02-07T08:46:36.171Z"
     }
 ]

Demo on Production Environment

Once all development and testing has been completed on the staging environment, Demo access on the production environment can be obtained. The Demo access can be used as a final testing stage and for any system demonstrations needed for the new integration. The Create Callout Section above mentioned that each callout has to have a response type. There is a demo responseTypeId that will need to be added to the callout. In addition to the responseTypeId, the internalTest flag should be set to true. The integrator will then be given details to log into the demo control centre, where the integrator will act as a controller and be able to manage the their own demo callouts. Demo response vehicles can be created and placed in an area of your choice and will ring on specific callouts just as they would on the live production environment.

Back to the Integration Portal