Skip to main content

Integrated RapidSOS Portal (iRP) v.21.0

REST API used to generate and return a secure Integrated RapidSOS Portal deeplink.

Overview

RapidSOS offers this API endpoint for partners interested in embedding RapidSOS Portal directly into their pre-existing solution. This solution allows the ability to embed the full portal with the map, or can simply provide additional data cards (without the map) depending on your integration requirements. 

This is a multi-step process that involves requesting an authentication token, passing the token in a request for a unique URL, and launching the RapidSOS Portal (RSP).

Using your integration’s client credentials combined with a valid login for RapidSOS Portal (RSP), you can use our Deeplink API to generate a secure URL that can be opened in a browser to automatically populate the user’s session and search for a specific phone number or Alert ID. This allows for a seamless automatic display of rich data as rendered by the Portal natively inside your application.

This solution requires that the CAD/CPE/Automation integration have access to RSP user credentials and RapidSOS Integration credentials in order to authenticate to iRP v.2. Additionally, auto-open browser solutions require that CAD/CPE/Automation integrations have the capability to open a web browser within or alongside their solution to a given URL on the open internet.

 

 

Authentication

It is necessary to verify the user credentials and issue a user access token for generating the session in iRP v.2. It is also required that a Deeplink is generated to the secure URL that will be used by integration partners for loading iRP.

Access Token Creation

Credentials of users with both administrator roles and non-administrator roles can be used to generate auth tokens for use with requesting a RapidSOS Portal Deeplink URL.

The following is used to authenticate to the RapidSOS Portal. This URL is the first required step needed for RapidSOS Portal authentication and Deeplink generation for loading iRP v.2:

OAuth2 Server URL

https://api-sandbox.rapidsos.com/oauth/v2/token

Here is some important information when working with this endpoint:

  • POST Requests

The endpoint accepts POST requests in application/x-www-form-urlencoded format. The header should be Content-Type: application/x-www-form-urlencoded.

  • Body of a Request

The request body should contain:

  - grant_type

  - Client_id

  - Client_secret

  - username

  - password

The body of the request should consist of the client id and client secret of the integration credentials, and the User name and password of the Rapidsos Portal account that is being leveraged in the integration. It should also contain the grant type set to “password”.

Example Request shown using cURL:

curl --location --request POST 'https://api-sandbox.rapidsos.com/oauth/v2/token' \

--header 'Content-Type: application/x-www-form-urlencoded' \

--data-urlencode 'grant_type=password' \

--data-urlencode 'client_id=XXXXXX' \

--data-urlencode 'client_secret=XXXXXXX' \

--data-urlencode 'username=XXXXXXX@enteremail.com' \

--data-urlencode 'password=XXXXXXXX'

  • Response of a Request

The response of the request will contain an access token. This token should be used as a bearer token in the authorization header of the request to create the RapidSOS Portal Deeplink URL.

Example Response: 

{

   "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJSYXBpZFNPUyIsInN1YiI6Njk2LCJ1c2VybmFtZSI6Im1yb2RyaWd1ZXpAcmFwaWRzb3MuY29tIiwiZXhwIjoxNjA4MTMzNzMxLCJ0eXBlIjoiYWNjZXNzIn0.zSkzMCEw4cP2WgOSV76Ll38exn1lRijDOLIcg-ZmShE",

   "token_type": "Bearer",

   "issued_at": "1608130131260",

   "expires_in": "3599",

   "refresh_token": "ksTHyG1AGiOap9AitXgz2ygJgOKR9rfn",

   "refresh_token_issued_at": "1608130131260",

   "refresh_token_expires_in": "0"

}

 

 

Deeplink URL Creation

Once a token has been obtained, the following Deeplink URL is used to generate your unique URI to open the iRP.

DEEPLINK URL

https://api-sandbox.rapidsos.com/v1/deeplink/integrations/irp

 

Here is some important information when working with this endpoint:

  • POST Requests

The endpoint accepts POST requests in application/json format. The header should be Content-Type: application/json.

  • Body of a Request

The body of the request should consist of the query attribute in URI format for the desired alert_id or caller_id that the Deeplink will open.

  • Response of a Request

The response of the request will contain a Deeplink URL. This URL will automatically populate the user’s session and search for the 9-1-1 call or Alert specified in the query attribute of the request when opened in a browser.

Note: Integrated solutions can use this URL in an embedded web widget, but are recommended to use an OS system call to pop open the system’s default web browser for display (details of usage are up to the maintainers of each integrated solution).

IMPORTANT: The login session of this URL will be valid for 1 hour.

 

 

Requests

The following POST request should be used to generate a secure Deeplink to RapidSOS Portal that will automate populating a user’s session and searching for a given phone number or other identifier.

Request Type Input Description Parameters Schema
POST /integrations/irp Generate and return a secure Integrated RapidSOS Portal Deeplink. None

{

description:

Integrated RapidSOS Portal Request Schema

query* string
example: tel://15555555555

Query identifier (typically phone number or alert ID) of the emergency you would like to generate an iRP Deeplink for in URI format

}

 

Example Values

Example values are shown in standard JSON format.

The following is an example value for:

/integrations/irp

{
  "query": "tel://15555555555"
}

 

 

 

Responses and Error Codes

POST requests for /integrations/irp can generate the following responses:

Code

Description with Example and Schema

200

Deeplink was successfully retrieved.

MEDIA TYPE: application/json
CONTROLS ACCEPT HEADER.

{
  "url": "https://rapidsosportal.com?irp_token=eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4R0NNIn0..McILMB3dYsNJSuhcDzQshA.OfX9H_mcUpHDeRM4IA.CcnTWqaqxNsjT4eCaUABSg"
}

iRPDeepLinkResponse:

{

description:

iRP Deeplink Response Schema

url* string
example: https://rapidsosportal.com?irp_token=eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4R0…

Deeplink to use to open Integrated RapidSOS Portal window.

}

400

Bad Request

401

Invalid authentication

403

Unauthorized

415

Unsupported Media-Type

429

Too Many Requests

 

 

 

 Code Sample

The following code sample is written in Python as a post request for /integrations/irp to generate a secure Deeplink to RapidSOS Portal.

Sample Request:

import requests

url = "https://api-sandbox.rapidsos.com/v1/deeplink/integrations/irp"

payload = {
  'query': 'tel://15555555555'
}

headers = {
  'Authorization': 'Bearer [Insert Token]',
  'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, json = payload)

print(response.json())

 

Sample Response:

{
   "url": "https://sandbox.rapidsosportal.com?irp_token=eyJhbGciOiJBMjU2R0NNS1ciLCJlbmMiOiJBMjU2R0NNIiwiaXYiOiJ5SFRJMm5rcExSaVVfaFlZIiwidGFnIjoia1VpSFRZckotLWFmMnphSDgwVzNMQSJ9.VHQJbRbU1SHKIFrJ0L1n8R0yt3sb3nj_dkhPnIFy_ZA.-XYIn2xjyHSAEIJ9.KghatINPB2aPSIkBV9Fw2uvLL3z4F5j4SCLPkcNXuHctgp_1MphqkIsOxtzPPwGp_LdgJngZ19B9Hl2noOwEpDdfgAoGycWMRHLooO_dwjj1F3wfVLyV62yHs_6aGJCAs5DyCQSfNINEA-ZK_cqyUPv-u65lQeLmnECTvIyig4EYjxFdt2omAaLNMDzW1b1ZODRvR0X7WHBFvEOCwnrPZtSjPPlW2gN0hvAtuiGDiH3pON4WOuLrJ5BOFS0IL_S3ibQcV-_t9Zz6vktcvNpMV234doepXpe8npOJLAPND3Yhn7PCTkLmlbfp13W4PkMFaxcZN_LwqHjjcAafniOCAiVljJaD9XzO5T_Zq4Zzp72D0foc--tCquh3_scZKh6chqViDvF_XbGAjzsDaHM_0u_EbeYI5WZUpqjo12vT6e035wmgfMfuCKaAM6mvA-AHJ_VERpZHCxeRtqv_ugrBw60YKIca2Lhqckl1dcLE3ayZUGjIyvEFwtbapkYik2ZMkE1YLleocACmihm09Bh2idyfY3sk8KtOKuhgxkTMdDXlrvuBGYMIsPZbjZOAWuOFRq23YEtH6Ae2lS9Lw3Hi2ZWgHjgsnkr9aFDCQJfNEXaHwtuMmGXjYaa5trGCnxM.VzDPjPEocxxMBaX8VYV8ig"
}

 

 

 

Implementation Flow

The following diagram depicts an integration flow when implementing a web browser/widget.

 

 

 

 

Create a RapidSOS Portal User

RapidSOS Portal user credentials are required to generate an access token to query the iRP Deeplink endpoint within production, these user accounts are created by the PSAP administrators. When building and testing your integration with our Sandbox environment, you can create RapidSOS Portal users for testing within your provided RapidSOS Portal Sandbox account.

This can be created through the admin panel using the add user feature:

  1. Enter the email address and Password > Press Login
  2. Select > Admin
  3. Select > Users tab
  4. Select > Add User
  5. Fill out the required information (first name, last name, email, role) and press > SAVE

Add User

 

 

 

Additional Considerations

Review the following additional information when considering development with the Integrated RapidSOS Portal (iRP) v2:

  • Uses OAuth2.0 only
    • Has a separate URL endpoint from other egress APIs to retrieve the token
  • RSOS Portal is kept up to date with browser updates
  • If interested in using iRP through VPN, contact: PARTNERENABLEMENT@RAPIDSOS.COM

 

Additional Reference

 

 

 

About us

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

RapidSOS logo

Contact