Integrated RapidSOS Portal (iRP) v.21.0

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.

Integration users should be prompted to log into the iRPv2 integration each time they sign into CAD with their unique username and password used for their RapidSOS portal account.

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.

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:

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

 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

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

• Refer to the Integrated RapidSOS Portal (iRP) v.2 Open API specification.
• Refer to the Writing the Configuration documentation for information on how to Automatically Initiate a Query and Display the Corresponding Data in RapidSOS Portal.
• Refer to the URLs for PSAP network to whitelist for RapidSOS Portal to view a list of known domains that have to be whitelisted in order for RapidSOS Portal and various integrations to work.