Skip to main content

Emergency WorkFlow API Overview

The RapidSOS Emergency WorkFlow API packages our deep expertise on the technical and policy challenges associated with the antiquated, complex 9-1-1 system into a single API call, enabling you to focus on quickly implementing a safe and effective emergency solution for your users. 

A wide variety of use cases, workflows, can be enabled through a simple API trigger from any connected device (or connected device host). Workflows are designed to be modular, and can constitute a straightforward connection initiated between the caller and 9-1-1, or a complex connection including multiple callers and 9-1-1 centers with tunable timing, SMS messaging, text-to-speech, and interactive voice response (IVR) components.

Workflow Diagram

 

Regulatory Standards and Compliance

The Emergency WorkFlow API is compliant with 9-1-1 regulatory standards, including two key requirements:

  1. Calls to 9-1-1 must be initiated by a human
  2. There must be a two-way voice connection open between the caller and the 9-1-1 call operator

 

 

What to Expect During API Development

RapidSOS will assign a Solutions Engineer to work with you to discuss optimal workflows that could be most efficient for your company, it’s users as well as fulfill the needs of the Public Safety Communicators and First Responders.

Once the workflow is agreed upon by all parties, RapidSOS will work with you to determine the data elements that will be provided to the RapidSOS API. Once the data fields are agreed upon, RapidSOS will provide you a development API code snippet containing all information that you will need to trigger the workflow in the RapidSOS Emergency Response Data Portal.

Once the API trigger and workflow have been created by RapidSOS and provided to the client,  the company will need to develop their application to communicate with the RapidSOS API. RapidSOS will continue to provide assistance through the development process.

Upon agreement of contractual terms, the project will be transitioned and led by the RapidSOS Technical Project Management team until go-live date. At this point, formal testing of the applications occurs as well as provisioning of obtaining API credentials for live production deployment.

 

 

RapidSOS Standard Solution Flow Summary

RapidSOS provides a standard API solution that quickly and efficiently enables your company to send the 9-1-1 community pertinent data during the case of an emergency. The standard API solution facilitates the RapidSOS product offerings as provided in the following options:

  • Data Connect (Option 1)
  • DC + Voice (Option 2)
  • DC + Monitoring (Option 3)

Additional information about RapidSOS standard solution options and flows can be found here.

 

 

RapidSOS API Communications

Authenticating Requests

The Emergency API authentication requests use a short-lived OAuth 2.0 access token granted using application client credentials. The token is valid for authenticating requests to the Emergency WorkFlow 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 https://api-sandbox.rapidsos.com/oauth/token

Request

  • Headers
    • Content-Type: x-www-form-urlencoded
  • 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: client_credentials

 

Response

  • Fields
    • access_token: Short-lived OAuth 2.0 access token
    • token_type: Token type descriptor, in this case BearerToken
    • issued_at: UNIX timestamp of 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.

Triggering/Initiating an Emergency Flow

The logical entity triggering the emergency workflow (i.e. a mobile application, service backend, or any connected device) will trigger the emergency flow with a single API call as described below.

POST https://api-sandbox.rapidsos.com/v1/rem/trigger

Request

  • Headers
    • Authorization: Bearer <ACCESS-TOKEN>
      • Content-Type: application/json

 

  • Parameters
    • callflow: The name of the workflow to execute
    • variables: JSON Object defining any variables that you have defined and use in your workflow

Response

  •  Fields
    • code: Status code of the emergency workflow initiation
      • 0: Success
      • -1: Server error
      • -2: Workflow validation error
    • id: Unique identifier of the instance of the emergency workflow execution
    • message: Human-readable descriptor of the emergency workflow status

 

 

Sample Code Snippet

#RapidSOS grants you a nonexclusive copyright license to use this programming code example (subject to your explicit agreement to RapidSOS Terms of Service) from which you can generate similar function tailored to your own specific needs. All sample code is provided by RapidSOS for illustrative purposes only. These examples have not been thoroughly tested under all conditions. RapidSOS, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs.

IMPORTANT: All API calls require user_name, user_phone, and location at a minimum, as highlighted below, and additional information can supplement these calls.

access_token=$(curl --request POST \
            --url 'HTTPS://API-SANDBOX.RAPIDSOS.COM/OAUTH/TOKEN' \
            --header 'content-type: application/x-www-form-urlencoded' \
            --data 'client_id=<KEY>client_secret=<SECRET>grant_type=client_credentials' | jq '.access_token' | tr -d '"')

curl --request POST \
            --url 'HTTPS://API-SANDBOX.RAPIDSOS.COM/V1/REM/TRIGGER' \
            --header "authorization: Bearer $access_token" \
            --header 'content-type: application/json' \
            --data '{"callflow":"company_dataconnect_v1","variables":{"caller_info":{"full_name":"Joe User","phone_number":"6615555555"},"location":{"latitude":"39.285270","longitude":"-76.61247","uncertainty":"7"},"vehicle_info":{"make":"Ford","model":"Fiesta","color":"Red","license_plate":"ABC","license_plate_state":"MN"}}}'

 

 

RapidSOS Emergency API Customizations

The following actions have been integrated into a wide variety of deployed calling flows and can be added as custom ingredients. We are continually adding to this list.

Note: Fields with an asterisk (*) are required fields. These include: Phone Number, Location. Data Connect

 

DESCRIPTION

INPUT

OUTPUT

Phone Number *

Phone number associated with emergency call

DID Number

In most cases, this is the primary key to correlate a 9-1-1 phone call with the location and data connect information

Location *

Provide device based location

Latitude, Longitude, Uncertainty

Provides real-time location of the emergency to the RapidSOS Portal or to integrated 3rd party Public Safety Software

Data
Connect *

Provide pertinent data points

Data varies based on vertical and the requirements of Public Safety entities

Provides real-time profile (name, age, gender), emergency contact, health-profiles (hearing/speech-disabled, blind, autistic-spectrum, allergies, DNR (Do Not Resuscitate), O2 Dependent, Mental Health) or other pertinent data based on client vertical

Create Emergency Bridge/Call

Create Emergency Bridge/call

None

None

Call User

Call a phone number and connect to an Emergency Bridge

User's phone number

User answers or not

Play Pre-Recorded Message

 

Play an audio file (pre-recorded message) for the caller or to all participants on the Emergency Bridge

Name of the stored audio file

None

Play TTS Message

Read an audio file for the caller; play a dynamic text-to-speech message to a user or participants on the Emergency Bridge

Text of the message to be converted to audio

None

Custom Test Server TTS (text to speech)

Play a customizable test message via dynamic text-to-speech to the user at the time of a test call

 

Text of the message to be converted to audio and played by the test server

None

Send SMS Message

Send a SMS message to a user or group of users

- Text of message

- Phone number(s) to send message to

None

Timeout

Add a timeout for a desired event

Number of seconds (1 - 30 seconds)

None

API Request/HTTP Request

Execute an API call/HTTP POST to Customer service/backend to provide status and alert notifications regarding the current emergency, i.e. "911 call has been completed".

Refer to this link for additional information.

- URL - Parameters (named parameters to be included in HTTP post)

Success or failure

Find Next Available Contact

Loops through a list of emergency contacts calling one-by-one in sequence, plays an audio message to them, and waits for confirmation of assistance before determining whether to call next contact; contact confirms readiness to speak to 9-1-1 by pressing "1" (configurable)

* Could be used to confirm any other action

List of emergency contacts, including phone numbers and names

Emergency contact picks up or not

Interactive Call/IVR

Calls a phone number and plays an audio message, waits for confirmation of answer; user confirms readiness to speak to 9-1-1 by pressing "1" (configurable)

* Could be used to confirm any other action

- User's name and phone number

- Audio message to play

None

Connect to Phone Number

Connect to any 10-digit phone number, i.e. Customer Service or Call Center

10-digit phone number to be connected

 

Connected to 10-digit phone number or not

Connect to 9-1-1

Connect to 9-1-1

- Emergency location:

* latitude

* longitude

* Uncertainty radius (in meters)

- User's name

- User's mobile phone number

- Additional Data as defined

Connected to 9-1-1 or not

 

Additional Reference

API Request/HTTP Request 

Learn more about the RapidSOS HTTP-based utility that sends requests to a web-server. This utility provides a mechanism for triggering external services, feedback/logging, error notification, and more. The HTTP utility supports both a POST and GET method that can be leveraged at any point throughout an emergency response flow.

About us

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

RapidSOS logo

Contact