Skip to main content

RAD (RapidSOS Additional Data)2.0.0

IMPORTANT: THIS RAD V2 ENDPOINT WILL BECOME PERMANANTLY UNAVAILABLE AS OF JUNE, 2021. 

RapidSOS Additional Data service provides a RESTful JSON API interface for the retrieval of RapidSOS Additional Data records. RAD records contain emergency personal information pertaining to an individual associated by a given phone number. These records can be read using this service in the RapidSOS v2 standard defined JSON format.

Overview

IMPORTANT: THIS RAD V2 ENDPOINT WILL BECOME PERMANANTLY UNAVAILABLE AS OF JUNE, 2021. 

The RAD (RapidSOS Additional Data) service provides a RESTful JSON API for the retrieval of RapidSOS Additional Data records. RAD records contain emergency personal information pertaining to an individual associated by a given phone number. These records can be read using this service in the RapidSOS v2 standard defined JSON format. While the rest of this page describes the API in some detail, the data models and methods are also fully-defined in the OpenAPI 3.0 (formerly, Swagger) YAML format.

 

Schema

RAD records are retrieved in RAD v2 JSON format. They strictly adhere to the RAD API schema. The schema is comprised of several layers that can be described in the following hierarchical structure:

  • Top-Level Attributes
  • Data Sections
    • Records
      • Fields
        • Values
 

Top-Level Attributes

Top-level attributes in the schema are those attributes which are literal values accessible from the top level of the JSON object structure. These attributes are the only attributes guaranteed to be present in a response from the RAD service where data is present. The available top-level attributes are listed below:

  • caller_id - Phone number associated with the RAD record, numeric digits. Must always include the country code (e.g. 1 for the U.S.). For example, the number 555-555-5555 should be 15555555555
  • format_version - The current version of the RAD schema the response has been formatted with
 

Data Sections

Data sections are JSON objects consisting of one or more records (i.e., a JSON object or an array of JSON objects). Each object contains an integer field id to uniquely identify it. Each data section is available at the top-level of the schema, keyed by the name of the data section which describes the logical category of data that the section represents. All data sections are optionally present and may consist of zero or more records. The following data sections are available:

  • caller - Contains a single record consisting of fields defining personal information about the caller
  • devices - Contains a list of records consisting of fields defining information about different devices belonging to the caller (e.g. mobile phone, wearable devices, vehicles, connected home devices)
  • locations - Contains a list of records consisting of fields defining information about known locations relevant to the caller (not to be confused with real-time caller location which is provisioned through the LEI & LIS service)
  • services - Contains a list of records consisting of fields defining information about the data provider service for the RapidSOS Additional Data records
  • event_info - (forthcoming) Contains a single record consisting of fields containing session data information.
 

Records

Records make up the contents of a data section. They either exist as a single dictionary, of a list of dictionaries. Either way, they are keyed within that record by an integer field id. Having multiple records within a single data section allows us to support unique tracking of multiples of certain things like mobile devices belonging to a single caller.

Records consist of fields that contain data relevant to the data section that particular record is in. All fields within a record are optionally present and a record may consist of zero or more fields. An example of a full record in the device section record like the following:

{
  "id": 1,
  "license_plate": {
    "display_name": "License Plate",
    "type": "string",
    "updated_time": 1507089914493,
    "value": [
      "2FAST2FURIOUS"
    ]
  },
  "hardware_description": {
    "display_name": "Device Description",
    "type": "string",
    "updated_time": 1507089914491,
    "value": [
      "Grey Hyundai Elantra"
    ]
  },
  "device_name": {
    "display_name": "Device Name",
    "type": "string",
    "updated_time": 1507089914488,
    "value": [
      "Nick's car"
    ]
  },
  "crash_pulse": {
    "display_name": "Crash Pulse",
    "type": "image-url",
    "updated_time": 1507089914487,
    "value": [
      {
        "label": "Crash Pulse",
        "note": "Pulse of the crash",
        "url": "https://cdn.rapidsos.com/63949328-ea28-4178-b0e9-3caff01a204a.png"
      }
    ]
  },
  "manufacturer": {
    "display_name": "Device Manufacturer",
    "type": "string",
    "updated_time": 1507089914494,
    "value": [
      "Hyundai"
    ]
  },
  "model": {
    "display_name": "Device Model",
    "type": "string",
    "updated_time": 1507089914495,
    "value": [
      "Elantra"
    ]
  },
  "unique_id": {
    "display_name": "Unique Device ID",
    "type": "device-id",
    "updated_time": 1507089914501,
    "value": [
      {
        "id": "1GBKP37F2V3393221",
        "type": "VIN"
      }
    ]
  },
  "video_feed": {
    "display_name": "Video Feed",
    "type": "video-stream",
    "updated_time": 1507089914503,
    "value": [
      {
        "format": "mjpg",
        "label": "Front Dashcam",
        "latitude": null,
        "longitude": null,
        "note": "Live dashcam footage",
        "url": "https://cdn.rapidsos.com/demo-static-files/dashcam.mp4"
      }
    ]
  },
  "color": {
    "display_name": "Color",
    "type": "string",
    "updated_time": 1507089914485,
    "value": [
      "Red"
    ]
  },
  "classification": {
    "display_name": "Device Classification",
    "type": "string",
    "updated_time": 1507089914484,
    "value": [
      "vehicle"
    ]
  },
  "callback_phone": {
    "display_name": "Callback Number",
    "type": "phone-number",
    "updated_time": 1507089914483,
    "value": [
      {
        "label": "cell",
        "number": "+12345678901"
      }
    ]
  }
}

 

Fields

Field attributes make up individual records. All fields contain a value attribute and additional attributes such as display_nametypeupdated_time, and units where applicable. units are optionally present while all other field attributes are guaranteed to be present. The field attributes are defined as follows:

  • display_name - Human-readable description of the field
  • type - Custom RAD datatype of the field values. The available types are described in the Values section below.
  • updated_time - Millisecond-precise UNIX timestamp in UTC of when the field value was last updated
  • units - The units that certain numeric type fields are represented in (e.g. milliseconds)
  • value - A JSON array of the values for this field. The array consists of elements of the datatype defined by type The following fields, separated by data section, are available:
Name Value Type Data Section
address address caller
allergy string caller
birthday timestamp caller
blood_type string caller
comment string caller
disability string caller
email email caller
emergency_contact emergency-contact caller
ethnicity string caller
full_name string caller
gender string caller
height float caller
language language caller
medical_condition string caller
medical_note string caller
medication string caller
occupation string caller
phone_number phone-number caller
photo image-url caller
website web-url caller
weight float caller
airbags_deployed string device
battery_power realtime-metric device
blood_glucose realtime-metric device
blood_oxygen_saturation realtime-metric device
body_temperature realtime-metric device
break_in_detected boolean device
callback_phone phone-number device
carbon_dioxide_detected boolean device
carbon_monoxide_detected boolean device
classification string device
color string device
comment string device
crash_pulse image-url device
crash_severity string device
device_name string device
ekg12 image-url device
ekg4 image-url device
fire_detected boolean device
flooding_detected boolean device
gas_detected boolean device
hardware_description string device
heart_rate realtime-metric device
impact_speed float device
license_plate string device
manufacturer string device
model string device
network_carrier_registration string device
occupant_count integer device
respiratory_rate realtime-metric device
rollover_count integer device
rollover_detected boolean device
seatbelted_occupant_count integer device
steps_taken realtime-metric device
unique_id device-id device
user_agent string device
vehicle_orientation string device
video_feed video-stream device
address address location
animal animal location
comment string location
external_portal web-url location
fixed_video_feed video-stream location
floorplan image-url location
location_contact emergency-contact location
location_name string location
mobile_video_feed video-stream location
comment string service
contact_uri string service
data_provider_contact_address address service
data_provider_contact_email email service
data_provider_contact_phone phone-number service
data_provider_string string service
data_provider_url web-url service
language string service
provider_id string service
provider_id_series string service
service_environment string service
service_mobility string service
service_type string service
type_of_provider string service

An example of the birthday field would look like the following:

{ "display_name": "Birthday", "type": "timestamp", "units": "millisecond", "updated_time": 1473983986778, "value": [749188800000] }
 

Values

The main attribute for a field is the value attribute. All value attributes are JSON arrays, however, the elements of that array may be either simple or complex datatypes. The type attribute of the field will describe the datatype of the elements in the value array. The definitions, as well as full examples, of the all the different RAD value datatypes are described in the section below.

 

Types

The RAD schema consists of several custom datatypes as defined below. All datatypes consist of JSON datatypes (string, number, object, array, boolean, null) but may use a different name to indicate how they should be handled, like using web-url instead of string for URLs to indicate they can be treated as a link, or to indicate a specific schema format they adhere to in the case of object types such as address fields.

Type Definition Example
address JSON object defining an civic-address location as follows:
  • label (string): (Required) Free text field describing the type of address (e.g. home, work)
  • latitude (float): EPSG:4326 ISO6709 latitude coordinate
  • longitude (float): EPSG:4326 ISO6709 longitude coordinate
  • country_code (string): (Required) ISO ALPHA-2 country code
  • region (string): (Required) State, province, etc. (e.g. New York, Ontario)
  • locality (string): (Required) City, town, etc.
  • street_address (string): (Required) Full street address (Note: preferably validated against MSAG address format whenever feasible)
  • postal_code (string): (Required) Postal code
  • exact_location (string): Exact location (e.g. floor, apartment, office number)
  • note (string): Free text field providing additional information about the address
{ "label": "Work", "latitude": 40.754475, "longitude": -73.989874, "country_code": "US", "region": "New York", "locality" : "New York", "street_address": "234 W 39th St", "postal_code": "10018", "exact_location": "Apartment 412", "note": "Third building on the south side" }
animal JSON object defining an animal as follows:
  • label (string): (Required) Free text field describing the animal (e.g. pet, livestock, service animal)
  • full_name (string): (Required) Full name of the animal
  • species (string): (Required) The animal's species
  • photo (string): A URL to a photo of the animal
  • note (string): Free text field providing additional information about the animal
{ "label": "Service Animal", "full_name": "Fluffy", "species": "Dog", "photo": "https://cdn.rapidsos.com/63949328-ea28-4178-b0e9-3caff01a204a.png", "note": "Barks when blood sugar is low" }
boolean Native JSON boolean type true
device-id JSON object defining a Unique Device ID as follows:
  • type (string): (Required) Device ID type (e.g. IMEI, MAC, WiMAX, etc.)
  • id (string): (Required) Unique mobile device ID
            { "type": "IMEI", "id": "35788104" }
email JSON object defining an email address as follows:
  • label (string): (Required) Free text field describing the type of email (e.g. personal, work)
  • email_address (string): (Required) Valid email address
  • note (float): Free text field providing additional information about the email
{ "label": "Personal", "email_address": "jdoe@rapidsos.com", "note": "I check this email hourly" }
emergency-contact JSON object defining an emergency contact as follows:
  • label (string): (Required) Free text field describing the emergency contact relationship (e.g. mother)
  • full_name (string): (Required) Full name of the contact
  • phone (string): E.164 formatted phone number
  • email (string): Valid email address
  • note (float): Free text field providing additional information about the emergency contact
{ "label": "Mother", "full_name": "Jane Doe", "phone": "+15555555555", "email": "mom@rapidsos.com", "note": "Call first in an emergency" }
geolocation JSON object defining a geodetic location as follows:
  • label (string): (Required) Free text field describing the type of location (e.g. home, work)
  • latitude (float): (Required) EPSG:4326 ISO6709 latitude coordinate
  • longitude (float): (Required) EPSG:4326 ISO6709 longitude coordinate
  • altitude (float): ISO6709 altitude of the location in meters
  • uncertainty_radius (integer): EPSG:9001 circular radius of uncertainty in meters
  • uncertainty_confidence (integer): IETF RFC7459 defined value from 0-100 of the % confidence in the uncertainty radius
 { "label": "Work", "latitude": 40.754475, "longitude": -73.989874, "altitude": 15.5, "uncertainty_radius": 20, "uncertainty_confidence": 85 }
image-url JSON object defining a web URL for an image as follows:
  • label (string): (Required) Free text field describing the image (e.g. floor plan, personal photo)
  • url (string): (Required) Valid web URL to the image
  • note (string): Free text field providing additional information about the image
{ "label": "Floor Plan", "url": "https://cdn.rapidsos.com/63949328-ea28-4178-b0e9-3caff01a204a.png", "note": "East wing renovated in 2012" }
integer Native JSON integer type 41
language JSON object defining a language the individual speaks as follows:
  • language_code (string): (Required) Two character ISO 639-1 language code
  • preference (integer): (Required) Preference rank of the language for the individual
            { "language_code": "en", "preference": 1 }
phone-number JSON object defining a phone number as follows:
  • label (string): (Required) Free text field describing the type of phone number (e.g. home, cell)
  • number (string): (Required) E.164 formatted phone number
  • note (string): Free text field providing additional information about the phone number
            { "label": "Cell", "number": "+15555555555", "note": "This is my work cell phone number" }
realtime-metric (forthcoming) JSON object defining a URL for retrieving live data from a device as follows:
  • label (string): (Required) Type of data stream (e.g. heart-rate sensor)
  • data_feed (string): (Required) Web URL for retrieving the data in real-time
  • protocol (string): (Required) Protocol for accessing the feed. Will include `http`, `ws`, `tcp`.
  • note (string): Free text field providing additional information about the real-time metric feed
            { "label": "Smartwatch", "data_feed": "https://live.rapidsos.com/9eab6a993f294252a5ea3ffca6cf886b", “protocol”: “http”, “action”: “GET”, "note": "Feed contains heart-rate data" }
string Native JSON string type "Hello World"
timestamp Integer value representing a millisecond-precise UNIX timestamp in UTC 1473983986778
video-stream JSON object defining a URL for a video stream as follows:
  • label (string): (Required) Free text field describing the video stream (e.g. Main security camera)
  • url (string): (Required) Valid web URL of the stream
  • format (string): (Required) File format of the stream (e.g. mp4)
  • latitude (float): EPSG:4326 ISO6709 latitude coordinate
  • longitude (float): EPSG:4326 ISO6709 longitude coordinate
  • note (string): Free text field providing additional information about the video stream
            { "label": "cafeteria", "url": "https://video.rapidsos.com/63949328-ea28-4178-b0e9-3caff01a204a.png.mjpg", "format": "mjpg", "latitude": 40.754475, "longitude": -73.989874, "note": "Faces main entrance" }
web-url JSON object defining a website address URL as follows:
  • label (string): (Required) Free text field describing the type of web address (e.g. blog, professional)
  • url (string): (Required) Valid website address URL
  • note (string): Free text field providing additional information about the website URL
            { "label": "blog", "url": "https://info.rapidsos.com", "note": "My personal blog journal" }
 

Example

{
  "caller_id": "15555555555",
  "format_version": "2.0",
  "caller": {
    "medical_note": {
      "display_name": "Medical Notes",
      "type": "string",
      "updated_time": 1505917528037,
      "value": [
        "Suffers from anxiety"
      ]
    },
    "medical_condition": {
      "display_name": "Medical Conditions",
      "type": "string",
      "updated_time": 1505917528036,
      "value": [
        "Heart murmur",
        "Asthma"
      ]
    },
    "language": {
      "display_name": "Languages",
      "type": "language",
      "updated_time": 1505917528036,
      "value": [
        {
          "language_code": "en",
          "preference": 1
        },
        {
          "language_code": "de",
          "preference": 2
        }
      ]
    },
    "height": {
      "display_name": "Height",
      "type": "float",
      "units": "inches",
      "updated_time": 1505917528035,
      "value": [
        65
      ]
    },
    "gender": {
      "display_name": "Gender",
      "type": "string",
      "updated_time": 1505917528034,
      "value": [
        "Male"
      ]
    },
    "email": {
      "display_name": "Emails",
      "type": "email",
      "updated_time": 1505917528014,
      "value": [
        {
          "email_address": "mmartin@RapidSOS.com",
          "label": "work"
        }
      ]
    },
    "emergency_contact": {
      "display_name": "Emergency Contacts",
      "type": "emergency-contact",
      "updated_time": 1505917528032,
      "value": [
        {
          "email": "mom@rapidsos.com",
          "full_name": "Jane Doe",
          "label": "Mother",
          "note": "Call first in an emergency",
          "phone": "+15555555555"
        }
      ]
    },
    "medication": {
      "display_name": "Medications",
      "type": "string",
      "updated_time": 1505917528037,
      "value": [
        "Prozac"
      ]
    },
    "occupation": {
      "display_name": "Occupation",
      "type": "string",
      "updated_time": 1505917528038,
      "value": [
        "Lawyer"
      ]
    },
    "phone_number": {
      "display_name": "Known Phone Numbers",
      "type": "phone-number",
      "updated_time": 1505917528039,
      "value": [
        {
          "label": "cell",
          "number": "+15555555555"
        }
      ]
    },
    "photo": {
      "display_name": "Profile Picture",
      "type": "image-url",
      "updated_time": 1505917528040,
      "value": [
        {
          "label": "Profile",
          "note": "Taken in 2014",
          "url": "https://cdn.rapidsos.com/img/IMG_4635.png"
        }
      ]
    },
    "website": {
      "display_name": "Websites",
      "type": "web-url",
      "updated_time": 1505917528041,
      "value": [
        {
          "label": "work",
          "url": "https://rapidsos.com"
        }
      ]
    },
    "weight": {
      "display_name": "Weight",
      "type": "float",
      "units": "lbs",
      "updated_time": 1505917528041,
      "value": [
        175.5
      ]
    },
    "disability": {
      "display_name": "Disabilities",
      "type": "string",
      "updated_time": 1505917528011,
      "value": [
        "Deaf"
      ]
    },
    "comment": {
      "display_name": "Comments",
      "type": "string",
      "updated_time": 1505917528011,
      "value": [
        "These are generic comments about me."
      ]
    },
    "blood_type": {
      "display_name": "Blood Type",
      "type": "string",
      "updated_time": 1505917528010,
      "value": [
        "AB-"
      ]
    },
    "birthday": {
      "display_name": "Birthday",
      "type": "timestamp",
      "units": "millisecond",
      "updated_time": 1505917528010,
      "value": [
        1500661591992
      ]
    },
    "allergy": {
      "display_name": "Allergies",
      "type": "string",
      "updated_time": 1505917528009,
      "value": [
        "Peanuts",
        "Shellfish"
      ]
    },
    "address": {
      "display_name": "Known Addresses",
      "type": "address",
      "updated_time": 1505917528008,
      "value": [
        {
          "country_code": "US",
          "label": "work",
          "locality": "New York",
          "postal_code": "10018",
          "region": "New York",
          "street_address": "234 W 39th St"
        }
      ]
    },
    "ethnicity": {
      "display_name": "Ethnicity",
      "type": "string",
      "updated_time": 1505917528033,
      "value": [
        "White"
      ]
    },
    "full_name": {
      "display_name": "Name",
      "type": "string",
      "updated_time": 1505917528034,
      "value": [
        "Michael Martin"
      ]
    }
  },
  "devices": [
    {
      "license_plate": {
        "display_name": "License Plate",
        "type": "string",
        "updated_time": 1507089914493,
        "value": [
          "2FAST2FURIOUS"
        ]
      },
      "id": 1,
      "heart_rate": {
        "display_name": "Heart Rate (bpm)",
        "type": "realtime-metric",
        "units": "bpm",
        "updated_time": 1507089914492,
        "value": [
          {
            "data_feed": "https://cdn.rapidsos.com/63949328-ea28-4178-b0e9-3caff01a204a.png",
            "label": "Smartphone",
            "note": "Heartrate estimates from smartphone",
            "protocol": "https"
          }
        ]
      },
      "hardware_description": {
        "display_name": "Device Description",
        "type": "string",
        "updated_time": 1507089914491,
        "value": [
          "DDR3 RAM"
        ]
      },
      "ekg4": {
        "display_name": "EKG 4-lead",
        "type": "image-url",
        "updated_time": 1507089914491,
        "value": [
          {
            "label": "EKG4",
            "note": "EKG reading",
            "url": "https://cdn.rapidsos.com/63949328-ea28-4178-b0e9-3caff01a204a.png"
          }
        ]
      },
      "ekg12": {
        "display_name": "EKG 12-lead",
        "type": "image-url",
        "updated_time": 1507089914489,
        "value": [
          {
            "label": "EKG12",
            "note": "EKG reading",
            "url": "https://cdn.rapidsos.com/63949328-ea28-4178-b0e9-3caff01a204a.png"
          }
        ]
      },
      "device_name": {
        "display_name": "Device Name",
        "type": "string",
        "updated_time": 1507089914488,
        "value": [
          "John Doe's iPhone"
        ]
      },
      "crash_pulse": {
        "display_name": "Crash Pulse",
        "type": "image-url",
        "updated_time": 1507089914487,
        "value": [
          {
            "label": "Crash Pulse",
            "note": "Pulse of the crash",
            "url": "https://cdn.rapidsos.com/63949328-ea28-4178-b0e9-3caff01a204a.png"
          }
        ]
      },
      "manufacturer": {
        "display_name": "Device Manufacturer",
        "type": "string",
        "updated_time": 1507089914494,
        "value": [
          "Nokia"
        ]
      },
      "model": {
        "display_name": "Device Model",
        "type": "string",
        "updated_time": 1507089914495,
        "value": [
          "Lumia 800"
        ]
      },
      "network_carrier_registration": {
        "display_name": "Network Carrier",
        "type": "string",
        "updated_time": 1507089914497,
        "value": [
          "Verizon"
        ]
      },
      "respiratory_rate": {
        "display_name": "Respiratory Rate (bpm)",
        "type": "realtime-metric",
        "updated_time": 1507089914498,
        "value": [
          {
            "data_feed": "https://cdn.rapidsos.com/63949328-ea28-4178-b0e9-3caff01a204a.png",
            "label": "Smartphone",
            "note": "Transmittedd from smart device",
            "protocol": "https"
          }
        ]
      },
      "steps_taken": {
        "display_name": "Steps Taken",
        "type": "realtime-metric",
        "updated_time": 1507089914499,
        "value": [
          {
            "data_feed": "https://cdn.rapidsos.com/63949328-ea28-4178-b0e9-3caff01a204a.png",
            "label": "Fitbit",
            "note": "Average 10,000 a day",
            "protocol": "https"
          }
        ]
      },
      "unique_id": {
        "display_name": "Unique Device ID",
        "type": "device-id",
        "updated_time": 1507089914501,
        "value": [
          {
            "id": "35788104",
            "type": "IMEI"
          }
        ]
      },
      "user_agent": {
        "display_name": "User Agent",
        "type": "string",
        "updated_time": 1507089914502,
        "value": [
          "Mozilla"
        ]
      },
      "video_feed": {
        "display_name": "Video Feed",
        "type": "video-stream",
        "updated_time": 1507089914503,
        "value": [
          {
            "format": "mjpg",
            "label": "cafeteria",
            "latitude": 40.754475,
            "longitude": -73.989874,
            "note": "Live dashcam footage",
            "url": "https://cdn.rapidsos.com/demo-static-files/dashcam.mp4"
          }
        ]
      },
      "comment": {
        "display_name": "Comments",
        "type": "string",
        "updated_time": 1507089914486,
        "value": [
          "I have a smartwatch and smartphone"
        ]
      },
      "color": {
        "display_name": "Color",
        "type": "string",
        "updated_time": 1507089914485,
        "value": [
          "Red"
        ]
      },
      "classification": {
        "display_name": "Device Classification",
        "type": "string",
        "updated_time": 1507089914484,
        "value": [
          "smart-phone-app"
        ]
      },
      "callback_phone": {
        "display_name": "Callback Number",
        "type": "phone-number",
        "updated_time": 1507089914483,
        "value": [
          {
            "label": "cell",
            "number": "+12345678901"
          }
        ]
      },
      "body_temperature": {
        "display_name": "Body Temperature (F)",
        "type": "realtime-metric",
        "units": "F",
        "updated_time": 1507089914482,
        "value": [
          {
            "data_feed": "https://live.rapidsos.com/9eab6a993f294252a5ea3ffca6cf886b",
            "label": "Smartwatch",
            "note": "Fahrenheit body temp readings",
            "protocol": "https"
          }
        ]
      },
      "blood_oxygen_saturation": {
        "display_name": "Oxygen Saturation (% SpO2)",
        "type": "realtime-metric",
        "units": "%spO2",
        "updated_time": 1507089914481,
        "value": [
          {
            "data_feed": "https://live.rapidsos.com/9eab6a993f294252a5ea3ffca6cf886b",
            "label": "Smartwatch",
            "note": "Blood oxygen saturation from smartwatch",
            "protocol": "https"
          }
        ]
      },
      "blood_glucose": {
        "display_name": "Glucose (mg/DL)",
        "type": "realtime-metric",
        "units": "mg/DL",
        "updated_time": 1507089914479,
        "value": [
          {
            "data_feed": "https://live.rapidsos.com/9eab6a993f294252a5ea3ffca6cf886b",
            "label": "Smartwatch",
            "note": "Glucose readings from smartwatch",
            "protocol": "https"
          }
        ]
      },
      "battery_power": {
        "display_name": "Battery Level",
        "type": "realtime-metric",
        "units": "percentage",
        "updated_time": 1507089914479,
        "value": [
          {
            "data_feed": "https://live.rapidsos.com/9eab6a993f294252a5ea3ffca6cf886b",
            "label": "Smartwatch",
            "note": "Long lasting battery",
            "protocol": "https"
          }
        ]
      }
    }
  ],
  "locations": [
    {
      "location_contact": {
        "display_name": "Emergency Contacts",
        "type": "emergency-contact",
        "updated_time": 1507089618157,
        "value": [
          {
            "email": "foreman@rapidsos.com",
            "full_name": "Jim Doe",
            "label": "Foreman",
            "note": "Call first in an emergency",
            "phone": "+15555555555"
          }
        ]
      },
      "id": 1,
      "mobile_video_feed": {
        "display_name": "Video Feed",
        "type": "video-stream",
        "updated_time": 1507089618158,
        "value": [
          {
            "format": "mjpg",
            "label": "Cell Phone Back Camera",
            "latitude": 40.754475,
            "longitude": -73.989874,
            "note": "Personal phone",
            "url": "https://cdn.rapidsos.com/demo-static-files/homecam.mp4"
          }
        ]
      },
      "location_name": {
        "display_name": "Location Names",
        "type": "string",
        "updated_time": 1507089618158,
        "value": [
          "RapidSOS Factory"
        ]
      },
      "address": {
        "display_name": "Known Addresses",
        "type": "address",
        "updated_time": 1507089618111,
        "value": [
          {
            "country_code": "US",
            "label": "work",
            "locality": "New York",
            "postal_code": "10018",
            "region": "New York",
            "street_address": "234 W 39th St"
          }
        ]
      },
      "animal": {
        "display_name": "Animals",
        "type": "animal",
        "updated_time": 1507089618112,
        "value": [
          {
            "full_name": "Fluffy",
            "label": "Service Animal",
            "note": "Barks when blood sugar is low",
            "photo": "https://cdn.rapidsos.com/63949328-ea28-4178-b0e9-3caff01a204a.png",
            "species": "Dog"
          }
        ]
      },
      "comment": {
        "display_name": "Comments",
        "type": "string",
        "updated_time": 1507089618112,
        "value": [
          "These are comments about this location."
        ]
      },
      "external_data_portal": {
        "display_name": "Additional Location Information",
        "type": "web-url",
        "updated_time": 1507089618113,
        "value": [
          {
            "label": "Plant Management Site",
            "note": "Use to see security system status",
            "url": "https://fakefactory.com/admin"
          }
        ]
      },
      "fixed_video_feed": {
        "display_name": "Video Feed",
        "type": "video-stream",
        "updated_time": 1507089618114,
        "value": [
          {
            "format": "mjpg",
            "label": "Entryway Security Camera",
            "latitude": 40.754475,
            "longitude": -73.989874,
            "note": "Faces driveway",
            "url": "https://cdn.rapidsos.com/demo-static-files/homecam.mp4"
          }
        ]
      },
      "floorplan": {
        "display_name": "Floor Plans",
        "type": "image-url",
        "updated_time": 1507089618114,
        "value": [
          {
            "label": "3rd Floor",
            "note": "Last updated in 2016",
            "url": "https://cdn.rapidsos.com/63949328-ea28-4178-b0e9-3caff01a204a.png"
          }
        ]
      }
    }
  ]

 

Authentication

This interface is authenticated only 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.

 

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. A full example using curl on the command line is below.

#!/bin/sh

# NOTE: this script requires jq for json parsing: https://stedolan.github.io/jq/

server='https://api-sandbox.rapidsos.com'
client_id='gduJO17EfMDTx588wNybmRbWTGBEV735'
client_secret='8F44X6hdSHBjzkFp'
caller_id='15555555555'

echo '########### 1 - GET AUTH TOKEN'
endpoint=$server/oauth/token
method='POST'
payload="client_id=$client_id&client_secret=$client_secret&grant_type=client_credentials"
response=$(curl -s -X $method $endpoint -d "$payload" | jq '.')
token=$(echo $response | jq -r '.access_token')
auth_header="Authorization: Bearer $token"
echo ENDPOINT: $endpoint
echo METHOD: $method
echo PAYLOAD: '<client credentials>'
echo RESPONSE:
echo $response | jq .
echo AUTH TOKEN: $token
echo

echo '########### 2 - GET RAD DATA'
endpoint="$server/v2/emergency-data/?caller_id=$caller_id"
method='GET'
response=$(curl -vvv -s -X $method $endpoint -H "$auth_header" | jq '.')
echo ENDPOINT: $endpoint
echo METHOD: $method
echo RESPONSE:
echo $response | jq .
echo

Methods

Further details on the particular interface of the GET HTTP method can be found in our Reference Documentation section of this API article.

 

 

 

About us

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