BodyTrace Measurement Webhook (Push) API

openapi: 3.0.3
info:
  title: BodyTrace RPM Data API
  description: >-
    HTTP API for BodyTrace cellular-connected remote patient monitoring (RPM)
    devices - blood pressure monitors, body-weight scales, and pulse oximeters.
    Devices transmit measurements directly over the cellular network to the
    BodyTrace platform; healthcare organizations then read those readings over
    this API. Authentication is HTTP Basic using credentials issued by BodyTrace.

    Scope and honesty note: BodyTrace does not publish an open, self-serve
    developer portal - device provisioning and API credentials are arranged
    through BodyTrace sales, and the reference docs live behind partner
    onboarding (BodyTrace's own docs plus integrator guides such as Validic).
    The one endpoint publicly and repeatedly documented in the wild is the data
    values pull, `GET /1/device/{imei}/datavalues`, and the device push message
    payload. Those are marked CONFIRMED below. The remaining operations (raw data
    messages, device listing/status, alerts, and provisioning) are HONESTLY
    MODELED from BodyTrace's documented IMEI-centric data model and RPM feature
    set; their exact paths and parameters should be verified against the partner
    documentation you receive with credentials. Modeled operations carry
    `x-endpoint-status: modeled`; confirmed ones carry
    `x-endpoint-status: confirmed`.

    Delivery model: readings can be pulled from the data values endpoint on a
    polling loop, or pushed by BodyTrace to a customer-hosted HTTP endpoint
    (a webhook you host and secure). There is no documented public WebSocket
    surface.
  version: '1.0'
  contact:
    name: BodyTrace
    url: https://www.bodytrace.com
  license:
    name: Proprietary
    url: https://www.bodytrace.com
servers:
  - url: https://us.data.bodytrace.com/1
    description: BodyTrace US data region
  - url: https://eu.data.bodytrace.com/1
    description: BodyTrace EU data region (region assigned by BodyTrace)
security:
  - basicAuth: []
tags:
  - name: Observations
    description: Confirmed pull surface for device readings (data values).
  - name: Data Messages
    description: Modeled surface for raw per-transmission device messages.
  - name: Devices
    description: Modeled device listing and status keyed by IMEI.
  - name: Alerts
    description: Modeled threshold and connectivity alerts.
  - name: Provisioning
    description: Modeled device enrollment and delivery configuration.
paths:
  /device/{imei}/datavalues:
    parameters:
      - $ref: '#/components/parameters/Imei'
    get:
      operationId: getDeviceDataValues
      tags:
        - Observations
      summary: Get device data values (readings)
      description: >-
        Retrieve the latest and historical readings for a device by IMEI. Use the
        `names` query parameter to select which values to return - for example
        `values/weight`, `values/systolic`, `values/diastolic`, `values/pulse`,
        `batteryVoltage`, and `signalStrength` - and optionally bound the results
        with a time range. This is the confirmed, publicly documented BodyTrace
        pull endpoint.
      x-endpoint-status: confirmed
      parameters:
        - name: names
          in: query
          required: false
          description: >-
            Comma-separated list of value names to return, e.g.
            `batteryVoltage,signalStrength,values/weight,values/unit`. For blood
            pressure use `values/systolic,values/diastolic,values/pulse`.
          schema:
            type: string
            example: batteryVoltage,signalStrength,values/weight,values/unit
        - name: from
          in: query
          required: false
          description: Start of the time window, epoch milliseconds (UTC).
          schema:
            type: integer
            format: int64
        - name: to
          in: query
          required: false
          description: End of the time window, epoch milliseconds (UTC).
          schema:
            type: integer
            format: int64
        - name: limit
          in: query
          required: false
          description: Maximum number of readings to return.
          schema:
            type: integer
      responses:
        '200':
          description: The requested device readings.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DataValue'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /device/{imei}/datamessages:
    parameters:
      - $ref: '#/components/parameters/Imei'
    get:
      operationId: getDeviceDataMessages
      tags:
        - Data Messages
      summary: Get raw device data messages
      description: >-
        Retrieve the raw, per-transmission messages a device has sent over the
        cellular network for a given IMEI and time range. Each message mirrors the
        payload BodyTrace devices emit (deviceId, ts, batteryVoltage, rssi, and a
        values object). MODELED - the message payload shape is confirmed from
        BodyTrace's documented device messages, but this read/query surface is
        gated behind partner credentials; verify path and parameters against your
        onboarding docs.
      x-endpoint-status: modeled
      parameters:
        - name: from
          in: query
          required: false
          description: Start of the time window, epoch milliseconds (UTC).
          schema:
            type: integer
            format: int64
        - name: to
          in: query
          required: false
          description: End of the time window, epoch milliseconds (UTC).
          schema:
            type: integer
            format: int64
        - name: limit
          in: query
          required: false
          description: Maximum number of messages to return.
          schema:
            type: integer
      responses:
        '200':
          description: A list of raw device messages.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DeviceMessage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /devices:
    get:
      operationId: listDevices
      tags:
        - Devices
      summary: List devices
      description: >-
        List the cellular devices provisioned in your account, keyed by IMEI.
        MODELED - BodyTrace's model is device/IMEI centric, but an account-scoped
        listing endpoint is gated behind partner credentials; verify against your
        onboarding docs.
      x-endpoint-status: modeled
      responses:
        '200':
          description: A list of devices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Device'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /device/{imei}/status:
    parameters:
      - $ref: '#/components/parameters/Imei'
    get:
      operationId: getDeviceStatus
      tags:
        - Devices
      summary: Get device status
      description: >-
        Read a single device's status by IMEI - last seen timestamp, battery
        voltage, signal strength, and provisioning state. MODELED from BodyTrace's
        device data model; verify against your onboarding docs.
      x-endpoint-status: modeled
      responses:
        '200':
          description: The device status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /device/{imei}/alerts:
    parameters:
      - $ref: '#/components/parameters/Imei'
    get:
      operationId: listDeviceAlerts
      tags:
        - Alerts
      summary: List device alerts
      description: >-
        List threshold and connectivity alerts raised for a device - for example a
        blood-pressure reading outside a configured range, or a low-battery /
        offline condition. MODELED RPM capability; alert configuration is arranged
        with BodyTrace and gated behind credentials.
      x-endpoint-status: modeled
      responses:
        '200':
          description: A list of alerts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Alert'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /device/{imei}/provision:
    parameters:
      - $ref: '#/components/parameters/Imei'
    post:
      operationId: provisionDevice
      tags:
        - Provisioning
      summary: Provision a device
      description: >-
        Associate a device (by IMEI) with an account, patient, or program and
        configure where its measurements are delivered - including an optional
        pushed HTTP endpoint (webhook) that BodyTrace should POST readings to.
        MODELED from BodyTrace's documented onboarding flow; provisioning is
        completed with BodyTrace and gated behind credentials.
      x-endpoint-status: modeled
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProvisionInput'
      responses:
        '200':
          description: The provisioned device.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic authentication using the username and password issued by
        BodyTrace for your account. The same credential model secures the
        customer-hosted push endpoint (you define the username/password BodyTrace
        uses when POSTing measurements to you).
  parameters:
    Imei:
      name: imei
      in: path
      required: true
      description: >-
        The device IMEI (serial). BodyTrace documents this as the IMEI without
        leading zeros and without the final check digit.
      schema:
        type: string
      example: '357872040012345'
  responses:
    Unauthorized:
      description: Missing or invalid HTTP Basic credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The device or resource was not found / not registered.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
    Values:
      type: object
      description: >-
        Measurement payload. The populated fields depend on the device type. A
        scale reports weight/tare; a blood pressure monitor reports
        systolic/diastolic/pulse; a pulse oximeter reports spo2/pulse. An empty
        values object indicates a heartbeat / connectivity message.
      properties:
        unit:
          type: integer
          description: Unit setting for the measurement (device-defined).
        weight:
          type: integer
          description: Body weight in grams (scale).
        tare:
          type: integer
          description: Tare / calibration offset in grams (scale).
        systolic:
          type: integer
          description: Systolic blood pressure in mmHg (BP monitor).
        diastolic:
          type: integer
          description: Diastolic blood pressure in mmHg (BP monitor).
        pulse:
          type: integer
          description: Pulse in beats per minute (BP monitor / pulse oximeter).
        spo2:
          type: integer
          description: Blood oxygen saturation as a percentage (pulse oximeter).
      additionalProperties: true
    DataValue:
      type: object
      description: A single reading returned by the data values endpoint.
      properties:
        ts:
          type: integer
          format: int64
          description: Measurement timestamp, epoch milliseconds (UTC).
        batteryVoltage:
          type: integer
          description: Battery voltage in millivolts.
        signalStrength:
          type: integer
          description: Cellular signal strength.
        rssi:
          type: integer
          description: Signal strength in negative dBm (raw radio metric).
        values:
          $ref: '#/components/schemas/Values'
    DeviceMessage:
      type: object
      description: >-
        A raw per-transmission device message, matching the JSON BodyTrace
        devices emit over cellular.
      properties:
        deviceId:
          type: string
          description: The device IMEI (without leading zeros and final digit).
        ts:
          type: integer
          format: int64
          description: Timestamp, epoch milliseconds (UTC).
        batteryVoltage:
          type: integer
          description: Battery voltage in millivolts (functional range ~4700-6000).
        rssi:
          type: integer
          description: Signal strength in negative dBm.
        values:
          $ref: '#/components/schemas/Values'
    Device:
      type: object
      description: A provisioned cellular device.
      properties:
        imei:
          type: string
        deviceType:
          type: string
          description: Device family, e.g. scale, bloodPressure, pulseOximeter.
          enum:
            - scale
            - bloodPressure
            - pulseOximeter
        lastSeen:
          type: integer
          format: int64
          description: Last transmission timestamp, epoch milliseconds (UTC).
        batteryVoltage:
          type: integer
        signalStrength:
          type: integer
        provisioned:
          type: boolean
    Alert:
      type: object
      description: A threshold or connectivity alert raised for a device.
      properties:
        id:
          type: string
        imei:
          type: string
        type:
          type: string
          description: Alert type, e.g. threshold, lowBattery, offline.
          enum:
            - threshold
            - lowBattery
            - offline
        metric:
          type: string
          description: The measurement that triggered a threshold alert, e.g. systolic.
        value:
          type: number
        ts:
          type: integer
          format: int64
        message:
          type: string
    ProvisionInput:
      type: object
      required:
        - imei
      properties:
        imei:
          type: string
          description: The device IMEI to provision.
        deviceType:
          type: string
          enum:
            - scale
            - bloodPressure
            - pulseOximeter
        externalId:
          type: string
          description: Your patient/program identifier to associate with the device.
        pushUrl:
          type: string
          format: uri
          description: >-
            Optional customer-hosted HTTPS endpoint BodyTrace should POST each
            measurement to (secured with HTTP Basic credentials you provide).