Skip to main content

 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)
      • 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 ] .
  • 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

 

About us

We build APIs that share data with first responders to help protect lives.