Overview
The RAD (RapidSOS Additional Data) Enhanced API provides a RESTful interface for querying additional data from various sources. Data from these sources is queried by phone number. It can also be queried by unique identifiers associated with the owner of the data, such as their phone number or MedicAlert ID.
IMPORTANT: It is strongly recommended that when integrating this API, fields should not be hard-coded. This is because it assumes that information which should be flexible is actually fixed and unchanging. It is best practice to develop a UI renderer based on our auto-rendering schema language to allow for generating UI components native to your software for any data fields that might be added, updated, etc. for any source.
Additional Data
All available sources of additional data provided to RapidSOS that your integration has been approved to receive will be made available using the RAD Enhanced endpoint.
Requesting Data
Authentication
This interface is authenticated via Two-legged Oauth2 (2LO). This entails retrieving a short-lived OAuth 2.0 access token granted using application client credentials. The token is valid for authenticating requests to the API for one hour, after which a new token for future requests will need to be fetched. Details for retrieving and using one of these tokens are described below.
Getting an Authentication Token
POST /oauth/token
Request
- Headers
- Content-Type: application/x-www-form-urlencoded
- Body Parameters
- client_id: Client ID of an application authorized to use the service
- client_secret: Client secret of an application authorized to use the service
- grant_type: This parameter should be hardcoded to
client_credentials
Response
- access_token: Short-lived OAuth 2.0 access token
- token_type: Token type descriptor, in this case
BearerToken
- issued_at: UNIX timestamp in UTC of the time when the token was issued
- expires_in: Number of seconds after the
issued_at
time that the access token will expire (defaults to 3600 seconds)
Using an Authentication Token
To authenticate requests using an access token, requests must include an Authorization
header set to the value Bearer <ACCESS-TOKEN>
where <ACCESS-TOKEN>
is substituted for the retrieved access token.
Test Credentials
Please contact support@rapidsos.com for test credentials.
RAD Session Request
Requests for RAD Session Data are made using POST requests. The request body specifies the search criteria for the query.
Request Structure
Request
- Method: POST
- URL: /v2/emergency-data/session
- Headers
- Content-Type: application/json
- Accept: application/json
- Body
- (See Below)
- (See Below)
Request Body
The request body consists of a JSON dictionary containing the key, query
.
The value of query
must be a URI specifying the query type and value. Optionally, a meta request can be made for additional metadata (boolean: default False) . Send this flag in your request to include the display schema for the data returned which can be used for implementing auto-renderer UI parsers for the data.
Set to True as shown in the below example body to make this type of request.
Request Query URI
Query URIs are specified using the format topic-type://topic-value.
Some currently supported topic-types
include:
* tel
: Query by caller ID
* xxxxxx-id
: Query by Specific ID
For example, maf-id for a medicalert ID can get queried with xxxxxx-id
Request with Metadata
Set to True as shown in the below example body to make this type of request.
Request by Caller ID (with the “meta”) :
POST /v2/emergency-data/session |
Body: |
Examples
Request body for request by Caller ID:
{
"query": "tel://19999999999"
}
Request body for request by Specific ID:
{
"query": "xxxx-id://999999"
}
Response Structure
The response from RAD is a json dictionary, keyed by each data source.
Data Sources
The available data sources allow a pre-defined "display" schema for data received by RapidSOS Portal. This dynamic schema allows it to automatically infer how these elements should be rendered.
Data Sources Available
The following list contains reference links for each available Data Source. Select the Data Source name from the list to view additional details about that source.
(In alphabetical order)
- 911 Inform
- 911Secure
- Chick-fil-A App
- Brave
- Cove
- Emergency Health Profile Association
- Farmers Insurance (TrueMotion)
- Kazoo
- MedicAlert
- Safe Zone
- SiriusXM
- Uber
- URSafe
- Vitals
- ZeroEyes
Rendering Schema and Data
The schema is defined per data source and dictates field ordering, labeling, formatting, etc. allowing for the automatic processing and rendering of the many new data types without the need for new UI development work every time a new data set is added.
Auto Generate Components from Data and Schema
The library takes a data object and a display schema as its input and return UI components representing those data points as defined by the display schema.
Text, Link, and Timestamp Support
The library can support rendering data as either text, a URL link, a human readable timestamp, hidden, dates and images. The criteria for rendering based on the schema is as follows:
type: string
format: web-url
Recommended UI Element Type: clickable link (optional)
Sample web-url:
{
“link_example”: {
“type”: “string”,
“format”: “web-url”
}
}
type: integer
format: timestamp
UI: ISO80 Datestring
Sample timestamp:
{
“timestamp_example”: {
“type”: “integer”,
“format”: “timestamp”
}
}
type: integer, number, or string
format: None specified. This can optionally be text.
UI: text
Sample plain text:
{
“plain_text_example”: {
“type”: “string”
}
}
Object Rendering
The library supports rendering fields with nested objects. The display schema defines these fields as an object and defines a display schema for each nested field within it. These nested fields cannot be objects or arrays. They must be strings or numbers.
Sample nested object data and display schema:
Data
{
“object_field_example”: {
“nested_simple_field”: 55
}
}
Display Schema
{
“object_field_example”: {
“type”: “object”,
“properties”: {
“nested_simple_field”: {
“type”: “integer”
}
}
}
}
Array Rendering
The library can support rendering a field whose value is a list of values. These values can be any strings, numbers, or objects.
Generated UI components should provide a visual indicator separating each element of the list from one another.
Sample array data and display schema:
Data
{
“array_field_example”: [1, 2, 3]
}
Display Schema
{
“array_field_example”: {
“type”: “array”,
“items”: {
“type”: “integer”
}
}
}
Ordered Components
The display schema defines a propertiesOrder attribute that defines the expected order in which each property is meant to be rendered. Your renderer should use this ordered list defined in the attribute to determine the order in which to render all properties within any object in the schema.
Example Schema
The following is an illustrative example of a fictitious ABC Corporation schema defining all required top-level attributes as well as at least one field of each of the types supported:
{
"$schema": "http://json-schema.org/example-01/schema#",
"type": "object",
"title": "ABC Corporation Crash Detection",
"propertiesOrder": ["id", "datetime", "location", "vehicle", "impacts", "airbags", "seats", "contacts"],
"properties": {
"id": {
"type": "string",
"title": "Crash ID"
},
"datetime": {
"type": "integer",
"format": "timestamp",
"title": "Crash Time"
},
"location": {
"type": "object",
"title": "Crash Location",
"propertiesOrder": ["latitude", "longitude", "timestamp", "speed", "bearing"],
"properties": {
"timestamp": {
"type": "integer",
"format": "timestamp",
"title": "Location Time"
},
"latitude": {
"type": "number",
"title": "Latitude"
},
"longitude": {
"type": "number",
"title": "Longitude"
},
"bearing": {
"type": "number",
"title": "Bearing (In Degrees)"
},
"speed": {
"type": "number",
"title": "Speed (In M/S)"
}
}
},
"vehicle": {
"type": "object",
"title": "Vehicle Information",
"propertiesOrder": ["make", "model", "color", "year", "vin"],
"properties": {
"vin": {
"type": "string",
"title": "Vin #"
},
"make": {
"type": "string",
"title": "Manufacturer"
},
"model": {
"type": "string",
"title": "Model"
},
"year": {
"type": "string",
"title": "Year"
},
"color": {
"type": "string",
"title": "Color"
}
}
},
"seats": {
"type": "array",
"title": "Seat Occupancy",
"items": {
"type": "object",
"propertiesOrder": ["occupancy", "belt", "side", "row"],
"properties": {
"row": {
"type": "integer",
"title": "Seat Row"
},
"side": {
"type": "string",
"title": "Seat Side"
},
"occupancy": {
"type": "string",
"title": "Occupancy"
},
"belt": {
"type": "string",
"title": "Seatbelt Status"
}
}
}
},
"airbags": {
"type": "array",
"title": "Airbag Statuses",
"items": {
"type": "object",
"propertiesOrder": ["name", "deployed"],
"properties": {
"name": {
"type": "string",
"title": "Airbag Name"
},
"deployed": {
"type": "string",
"title": "Deployment Status"
}
}
}
},
"impacts": {
"type": "array",
"title": "Vehicle Impacts",
"items": {
"type": "object",
"propertiesOrder": ["front_crash", "driver_side_crash", "pass_side_crash", "rear_crash", "rollover", "sequence"],
"properties": {
"sequence": {
"type": "integer",
"title": "Impact Sequence"
},
"front_crash": {
"type": "string",
"title": "Front Crash Detected"
},
"driver_side_crash": {
"type": "string",
"title": "Driver Side Crash Detected"
},
"pass_side_crash": {
"type": "string",
"title": "Passenger Side Crash Detected"
},
"rear_crash": {
"type": "string",
"title": "Rear Crash Detected"
},
"rollover": {
"type": "string",
"title": "Rollover Detected"
}
}
}
},
"contacts": {
"type": "array",
"title": "Emergency Contacts",
"items": {
"type": "object",
"propertiesOrder": ["name", "phone_number", "note"],
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"phone_number": {
"type": "string",
"title": "Phone",
"format": "phone-number"
},
"note": {
"type": "string",
"title": "Note"
}
}
}
}
}
}
Code Sample
A full example using curl on the command line is below. You will need to replace [CLIENT ID] and [CLIENT SECRET] in the script with valid credentials for the RapidSOS Sandbox environment.
#!/bin/sh
NOTE: This script requires jq for json parsing: https://stedolan.github.io/jq/
server='https://api-sandbox.rapidsos.com'
client_id='[CLIENT ID]'
client_secret='[CLIENT SECRET]'
caller_id='19999999999'
maf_id='999999'echo '########### 1 - GET AUTH TOKEN'
endpoint=$server/oauth/token
method='POST'
payload="client_id=$client_id&client_secret=$client_secret&grant_type=client_credentials"
response=$(curl -s -X $method $endpoint -d "$payload" | jq '.')
token=$(echo $response | jq -r '.access_token')
auth_header="Authorization: Bearer $token"
echo ENDPOINT: $endpoint
echo METHOD: $method
echo PAYLOAD: '<client credentials>'
echo RESPONSE:
echo $response | jq .
echo AUTH TOKEN: $token
echoecho '########### 2 - GET DATA BY CALLER ID'
endpoint="$server/v2/emergency-data/session"
method='POST'
content_type="application/json"
payload="{\"query\": \"tel://$caller_id\"}"
response=$(curl -s -X $method $endpoint -H "accept: $content_type" -H "Content-Type: $content_type" -H "$auth_header" -d "$payload" | jq '.')
echo ENDPOINT: $endpoint
echo METHOD: $method
echo RESPONSE:
echo $response | jq .
echoecho '########### 3 - GET DATA BY MAF ID'
endpoint="$server/v2/emergency-data/session"
method='POST'
content_type="application/json"
payload="{\"query\": \"maf-id://$maf_id\"}"
response=$(curl -s -X $method $endpoint -H "accept: $content_type" -H "Content-Type: $content_type" -H "$auth_header" -d "$payload" | jq '.')
echo ENDPOINT: $endpoint
echo METHOD: $method
echo RESPONSE:
echo $response | jq .
echo
Additional Considerations
The following considerations should be reviewed before implementing the RapidSOS Additional Data (RAD-E) solution:
- Uber data: we do not receive differentiation regarding if the driver or rider triggered the alarm
- There is not always additional data available for a call
- Regarding data retention and privacy, the data we provide is all voluntarily
- The partner must have the caller ID to query the API
- Additional Data is available for 10 minutes from the first push by the data partner
- Partners should make use of keyerror handling and utilize loops through the API response
Additional Reference
Refer to the RAD-E (RapidSOS Additional Data) Enhanced reference documentation for the Open API Specification, and schema details on actions for PSAP clients to access user and emergency data during an emergency.