Overview
The Alert Management API for Tech Partners provides a RESTful interface to create a request emergency dispatch for an ongoing incident.
The Alert Management API for Tech Partners is designed to enable applications in physical security, PERS (Personal Emergency Response Services), and other verticals where a 911 call is not required or can be avoided.
Additionally, existing applications within the physical security ecosystem, particularly where a Central Monitoring Station is currently deployed can utilize this API.
Audience
This document is intended for developers that are familiar with RESTful APIs, authentication processes (i.e. OAuth 2.0), and API integration. Knowledge of the JSON data format can be helpful when reviewing this material.
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.
Refer to the Alerts API Reference documentation for additional details.
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.
Request Structure
Request
- Method: POST
- URL: /v1/alerts/
- Headers
- Content-Type: application/json
- Accept: application/json
- Body
- (See below)
Request Body
Alerts API uses standard POST requests.
Create an Alert
POST
/
Creates a new Alert and pushes it to the system to request emergency dispatch. Note that the examples provided in this document use a sample implementation of the full schema. The RapidSOS Integration Management team can work with you to define a schema that will suit the data fields your integration is capable of providing.
Example cURL
curl --request POST \
--url https://api-sandbox.rapidsos.com/v1/alerts/ \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"blocking":true}'
Body Params and Field Information
A complete reference for Alerts API can be found in the Alerts API Reference documentation. Basic information is provided in this document.
Note: Items with an asterisk (*) are required.
- blocking* - By default set to false (boolean). This is a flag indicating whether or not this should kick off a blocking create job. Always set it to true if you require the response details to know the success/failure of the job or any of the Alert record details such as ID.
- callflow* - This is a required string. callflow refers to the name of the Alert creation flow to execute. An example of this is: CentralStationABCFireAlarmFlow .
- variables* - This is required. Variables contain alert metadata that provides source identifier and session ID for querying for supplemental additional data and updating alert status. Examples in this document refer to CentralStationIntegration .
- event* - This is required. These are the core fields required for creating an Alert record.
- source_id* - Source provided identifier of the owner of this data as a string and is required. Minimum length is 1, and maximum length is 100. (Example: abc123)
- incident_time* - Millisecond=precise UNIX timestamp of when the alert occurred as an integer and is required. Minimum is 0. (Example: 1581110270622 )
- location* - Location of the Alert incident. When creating an alert, the client must provide one of geodetic or civic. This is required.
- geodetic - Geodetic information available for this incident.
- latitude - latitude coordinate of the incident location as a number. Minimum -90, and maximum 90. (Example: 45.123)
- longitude - Longitude coordinate of the alert incident location as a number. Minimum -180, and maximum 180. (Example: -71.321)
- uncertainty_radius - Horizontal uncertainty in meters of the alert incident location provided by the location source device as a number. Minimum: -1 (Example: 7.5)
- civic - Civic location information available from this incident.
- name - Name of the location (i.e. business name) as a string. MinLength: 1, MaxLength: 200. (Example: RapidSOS HQ)
- street _1 - Street address of the nearest civic location to the geolocation as a string. MinLength: 1, MaxLength: 200. (Example: 123 Main Street)
- street_2 - Additional street address information such as apartment number or floor as a string. MinLength: 1, MaxLength: 200. (Example: Apt. 626)
- city - City or locality of the civic location as a string. MinLength: 1, MaxLength: 30. (Example: Los Angeles)
- state - ISO 3166-2 code of state or region of the civic location as a string. MinLength: 2, MaxLength: 2. (Example: CA)
- country - Country of the civic location as a string. MinLength: 1, MaxLength: 30. (Example: USA)
- zip_code - Zip/postal code of the civic location as a string. MinLength: 5, MaxLength: 5. (Example: 11375)
- geodetic - Geodetic information available for this incident.
- emergency_type* - Type of emergency event the alert is for as a string. This includes the following Enum Array: [ BURGLARY, HOLDUP, SILENT_ALARM, CRASH, MEDICAL, FIRE, CO, OTHER ] .
- site_type* - Site type for the given emergency from the supported list as a string. This includes the following Enum Array: [ RESIDENTIAL, COMMERCIAL, VEHICLE, PERSONAL ] .
- event* - This is required. These are the core fields required for creating an Alert record.
- alarm_description - This is a string.
- zone_description - This is a string.
- alarm_permit_number - This is a string.
- visually_verified - This is boolean.
- instructions - This is a string.
- service_provider_name - This is a string.
- site_phone - This is a string.
- emergency_contacts - EmergencyContact is the emergency contact information of an alert’s user. This includes:
- name - Full name of the emergency contact as a string. (Example: John Doe)
- phone - Phone number of the emergency contact in E.164 format as a string. (Example: 15555555555)
- relationship - Relationship of the emergency contact to the alert owner as a string.(Example: Father)
- language - Primary language of the emergency contact as a string. (Example: English)
Example Request Body
{
"blocking": true,
"callflow": "CentralStationABCFireAlarmFlow",
"variables": {
"event": {
"source_id": "abc123",
"incident_time": 1581110270622,
"location": {
"geodetic": {
"latitude": 45.123,
"longitude": -71.321,
"uncertainty_radius": 7.5
},
"civic": {
"name": "RapidSOS HQ",
"street_1": "123 Main Street",
"street_2": "Apt. 626",
"city": "Los Angeles",
"state": "CA",
"country": "USA",
"zip_code": 11375
}
},
"emergency_type": "BURGLARY",
"site_type": "RESIDENTIAL"
},
"alarm_description": "string",
"zone_description": "string",
"alarm_permit_number": "string",
"visually_verified": true,
"instructions": "string",
"service_provider_name": "string",
"site_phone": "string",
"emergency_contacts": [
{
"name": "John Doe",
"phone": 15555555555,
"relationship": "Father",
"language": "English"
}
]
}
}
Example Response Value
The Alerts API will always return a JSON response in the standard format unless an error or bad request is issued.
{
"source_id": "abc123",
"incident_time": 1581110270622,
"location": {
"geodetic": {
"latitude": 45.123,
"longitude": -71.321,
"uncertainty_radius": 7.5
},
"civic": {
"name": "RapidSOS HQ",
"street_1": "123 Main Street",
"street_2": "Apt. 626",
"city": "Los Angeles",
"state": "CA",
"country": "USA",
"zip_code": 11375
}
},
"status": {
"name": "RECEIVED",
"display_name": "Received"
},
"disposition": {
"name": "DISPATCHED",
"display_name": "Dispatched"
},
"last_updated_time": 1581110270622,
"alert_id": "6e58d630-d28f-4623-ba01-3207b497a9ba",
"sla_expiration_time": 1581110270922,
"emergency_type": {
"name": "BURGLARY",
"display_name": "Burglary"
},
"site_type": {
"name": "RESIDENTIAL",
"display_name": "Residential"
},
"covering_psap": {
"id": "NY_123",
"name": "New York Police Department",
"phone": 15555555555
},
"authorized_entity": {
"id": "CS_123",
"name": "Central Station ABC",
"phone": 15555555555
},
"followers": [
"41",
"23"
]
}
Response Codes and Errors
A response provided from the request will indicate a code value. Requests that are bad will result in a failure with an error code response. Response Codes include:
Code |
Description |
201 |
OK |
216 |
Unsupported Location - Returned if there is no PSAP active with RapidSOS Alerts for this Alert location |
217 | Supplemental Support Only - Returned if the location of the Alert incident falls within the jurisdiction of an Alerts enabled PSAP but is used as supplemental data only, i.e. the PSAP cannot update the status of the alert or chat back. If this is the response, a traditional 10-digit administrative number call is required to service this emergency. |
400 |
Bad Request |
401 |
Unauthorized |
429 |
Too Many Requests |
Standard Fields
Standard fields are required on all alerts and include basic critical information such as the location, time and type of incident.
Location
Civic or geodetic address information should be provided. If providing a geodetic address, all required fields in the Geodetic table must be provided. If providing civic address, the fields marked as required in the Civic table must be provided at minimum.
Note: In the event that both civic and geodetic information are provided, the geodetic address information will take precedence, and replaces civic address data.
Geodetic
Field (* Required) |
Value |
Description |
Latitude* |
number |
|
Longitude* |
number |
|
Uncertainty radius |
number |
Horizontal uncertainty radius |
Civic
Field (* Required) |
Value |
Description |
Name |
string |
Business name. Include only if it helps identify the location. Do not include other information such as the homeowner’s name as this can cause errors with the geo-coding lookup process. |
Street 1* |
string |
|
Street 2 |
string |
Apartment, suite |
City* |
string |
|
State* |
string |
ISO 3166-2 code for state |
Country* |
string |
ISO 3166-2 code for country |
Zip code* |
string |
5-digit Zip/postal code |
Core Fields
The following fields are required on all alerts regardless of the type.
Source ID* |
string |
The alarm/event ID assigned by the monitoring center or ingress partner. This would be a wholesale monitoring center’s own internal ID for the dealer. |
Source |
string |
Customer-facing service provider or brand known by end-users. For wholesale monitoring stations this would be the dealer’s name |
Incident time* |
integer |
UNIX timestamp of when the incident occurred in milliseconds |
dispatch_requested_time | integer | Millisecond-precise UNIX timestamp of when authorized entity (i.e. Central Station) requested dispatch from the covering PSAP |
Emergency type* |
BURGLARY HOLDUP SILENT_ALARM CRASH MEDICAL FIRE CO OTHER |
A set selection of high-level emergency types/categories.
More detailed descriptions such as “Glass break” or “Low oxygen” can be provided in the recommended schemas.
Alerts will be routed to the discipline (fire/EMS/Law enforcement) based on this emergency type field |
Site type* |
RESIDENTIAL COMMERCIAL PERSONAL VEHICLE |
A set selection. Residential and Commercial are expected as fixed (civic) locations, while Personal and Vehicle expect GPS (geodetic) locations. |
Emergency Contacts
An array of emergency contacts can be added to any emergency type. It is recommended to include a maximum of 3 contacts in addition to the primary homeowner, keyholder (premises-based alerts) or user (PERS, panic etc.).
Field (* Required) |
Value |
Description |
Name* |
string |
The emergency contact’s full name |
Phone* |
string |
The emergency contact’s phone number |
Relationship |
string |
Their relationship to the individual or premises. The first emergency contact will be assumed the primary user or keyholder, however, including this information here is helpful. |
Language |
string |
Preferred language for this emergency contact. Leave blank for English (default). |
Schema Recommendations and Examples
The following are a set of recommended schemas for various emergency types. Available data outside the recommended fields can be potentially added with approval from RapidSOS.
RapidSOS works closely with public safety to ensure all data is optimized for usability by public safety telecommunicators.
Security and Fire
None of the following fields are required, however, they are listed in order of importance and should be provided where available.
Field |
Value |
Description |
Description |
string |
A short, human-readable and informative overview of the alarm ie: “Glass Break Detected” |
Visually Verified |
boolean |
Someone has visually confirmed the alarm as not false. |
Zone/Sensor |
string |
The name assigned to the zone such as “Back door”. If this is not informational, such as “Zone 3”, it is preferred that it is not included. |
Alarm Permit Number |
string |
Required for some jurisdictions who reject alarms from repeat false alarm offenders |
Instructions |
string |
Special note such as pets, gate key/code, directions, cross streets |
Site Phone |
string |
If there is a land-line. |
Emergency contacts |
array |
See emergency contacts section for details |
mPERS (Medical, non-base station)
The following is a recommended list for mobile/GPS based medical devices. Medical profile information may differ depending on the application.
Field |
Value |
Description |
Description |
string |
A short, human-readable and informative overview of the emergency ie: “Low blood oxygen detected” or “Fall detection” |
Zone/Sensor |
string |
The name assigned to the sensor/device such as “Medical pendant”. If this is not informational, such as “Zone 3”, it is preferred that it is not included. |
Patient Name |
string |
Name/Preferred name |
Gender |
string |
Male, Female, non-binary, prefer not to say |
Date of birth |
string |
Used to determine age of patient |
Medical conditions |
string |
List of conditions |
Medications |
string |
List of medications |
Allergies |
string |
List of allergies |
Emergency contacts |
array |
See emergency contacts section for details |
PERS (Medical, base station)
The following is a recommended list for medical devices that have a base station or fixed location (such as a bed-side monitoring device with a fixed address). Medical profile information may differ depending on the application.
Field |
Value |
Description |
Description |
string |
A short, human-readable and informative overview of the emergency (i.e.: “Low blood oxygen detected” or “Fall detection”). |
Zone/Sensor |
string |
The name assigned to the sensor/device such as “Medical pendant”. If this is not informational, such as “Zone 3”, it is preferred that it is not included. |
Instructions |
string |
Special note such as pets, gate key/code, directions, cross streets |
Patient Name |
string |
Name/Preferred name |
Gender |
string |
Male, Female, non-binary, prefer not to say |
Date of birth |
string |
Used to determine age of patient |
Medical conditions |
string |
List of conditions |
Medications |
string |
List of medications |
Allergies |
string |
List of allergies |
Site Phone |
string |
If there is a land-line. |
Emergency contacts |
array |
See emergency contacts section for details |
Response Structure
The response creates information about the newly created alert.
The Alerts API will always return a JSON AlertMetaDataResponse in the standard format (example values below) unless an error or bad request is issued.
AlertMetaDataResponse
Refer to the open API specification Alert Management API for Tech Partners Reference for complete information.
Additional Considerations
Review the following additional information when considering use of the Alerts Management API:
- Bi-directional between Central Station and ECC
- Data is available for 12 hours
- Additional data is provisioned, and therefore available, at the time of alert creation
- Recommend an audible/toast notification for UX/UI design
- A partner cannot subscribe to an alert
- As part of the implementation, you can first GET an alert_id before requesting additional data via RAD-Enhanced
Additional Reference
- Alert Management API for Tech Partners Reference – The open API specification for the Alerts API.
- Alert Management API for Public Safety Integration Partners – The open API documentation for the Alerts API For Public Safety Integrations.