Emergency WorkFlow API

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.

 

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

To learn more about the RapidSOS HTTP-based utility that sends requests to a web-server please contact us at support@rapidsos.com. 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.