Data Share API

Overview

This Open API specification is used to design the handler for the Data Share Handler, and needs to be implemented when Data Share Partners need to receive data shared by RapidSOS Portal users. This API allows implementation of a HTTP request handler capable of receiving these requests.

Data Share Open API Specification

openapi: 3.0.0
servers:
  - url: https://partner.example.com
    description: Example Data Share Handler
info:
  version: '1.0'
  title: Example Partner Data Share Handler
  contact:
    email: support@rapidsos.com
  description: |
    API Spec for a RapidSOS Data Share
paths:
  /data_share_handler:
    post:
      tags:
        - Example Handler
      description: |
        The handler should accept the JSON payload, and optionally
        validate the 'X-RapidSOS-Signature' signature to ensure that
        the payload is coming from RapidSOS
      parameters:
        - in: header
          name: X-RapidSOS-Signature
          description: |
            This contains a HMAC-SHA1 signature of the payload,
            using the shared secret provided by the data partner
            to RapidSOS.
          schema:
            type: string
          required: true
          example: '2b89b6f4f2fc63af6fcfd59df255c0d8b6987e8a'
      responses:
        '200':
          description: Secure token was successfully decrypted & decoded
        '400':
          description: Bad Request
        '401':
          description: Invalid Signature
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataSharePayload'

components:
  schemas:
    DataSharePayload:
      type: object
      description: Payload to the Data Share Handler
      required:
        - access_token
        - query
        - bounding_box
      properties:
        access_token:
          type: string
          description: Access token that can be used to Query LEI API for
            location data
          example: fNheXbQnF7iIXEandAu1
        query:
          type: string
          description: Identifier to be auto queried by iRP in URI format
          example: tel://15555555555
        bounding_box:
          type: object
          description: Coordinate bounding box of the agency's jurisdiction
          required:
            - top_left
            - bottom_right
          properties:
            top_left:
              $ref: '#/components/schemas/Coordinate'
            bottom_right:
              $ref: '#/components/schemas/Coordinate'
        ecc_account_id:
          type: string
          description: |
            RapidSOS unique identifier for the ECC launching the application.
          example:
            CA_954
        incident_location:
          $ref: '#/components/schemas/Location'
    Coordinate:
      type: object
      description: WGS84 Coordinate
      required:
        - latitude
        - longitude
      properties:
        latitude:
          type: number
          description: WGS84 coordinate latitude
          example: 71.234
        longitude:
          type: number
          description: WGSf84 coordinate longitude
          example: -123.34
    Location:
      type: object
      description: 911 Caller Location
      required:
        - latitude
        - longitude
        - uncertainty_radius
      properties:
        latitude:
          type: number
          description: WGS84 coordinate latitude
          example: 71.234
        longitude:
          type: number
          description: WGSf84 coordinate longitude
          example: -123.34
        uncertainty_radius:
          type: number
          description: Uncertainty radius of the location in meters
          example: 10.0
        location_time:
          type: number
          description: |
            UTC Millisecond timestamp of when the location was determined
          example: 1627001542000