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:

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.