Device Data API

The device data API allows you to manage data obtained from participant wearables and other devices.

Note
Your project’s sensor data settings determine which device/sensor data will be available through the API.

Contents

Device Data Object
- Namespaces
Query Device Data
Persist Device Data

Device Data Object

The basic device data object is common to many of the device APIs. See Device and Sensor Data for an overview of how to use/interpret device data.

Namespaces

Device data is grouped into namespaces, which represent the source frameworks that generate the data. There is also a separate “Project” namespace, where projects can persist their own data. Supported namespaces include:

Project: Data persisted by project sources and SDKs.
Fitbit: Data persisted by a linked Fitbit account.
AppleHealth: Data imported from Apple Health.
GoogleFit: Data imported from Google Fit.
Garmin: Data imported from Garmin devices.
AirNowApi: Air quality index data imported from AirNow.gov.
WeatherBit: Weather forecast data imported from WeatherBit.io.
Omron: Data imported from Omron wellness products.

id guid

Auto-generated, globally-unique identifier for this device data point.

namespace string

Source framework for the device data. See namespaces for details.

deviceDataContextID guid

Identifier for a group of device data points, which share some context. Will be null if the device data point isn’t grouped.

participantIdentifier string

Identifies the participant associated with the data.

insertedDate date

Date when the record was created, in ISO8601 format.

modifiedDate date

Date when the record was last modified, in ISO8601 format.

identifier string

String used to name a device data point.

type string (required)

The general category this device data point belongs in, or what the device data represents. This field is a freeform string controlled by the source system based on its chosen categories.

value string (required)

The value of the recorded data point.

units string

The units, if any, that the data was recorded in.

properties object

An object whose key-value pairs represent metadata associated with this device data point. The metadata will vary depending on the source application.

source deviceDataSource

An object containing identifying information about the device which recorded the data point.

+ Child Fields

source.identifier string

Identifying string for the data source.

source.properties object

An object whose key-value pairs represent properties of the device data source. The specific properties will vary depending on the source application.

startDate date

The date at which this device data point began being recorded (for data that is recorded over time), in ISO8601 format.

observationDate date

The date at which this device data point was completely recorded, in ISO8601 format.

    Sample Device Data 
    
  

    {
  "id": "4f73e5ec-e52b-4651-a8e2-42a6555b6601",
  "namespace": "AppleHealth",
  "deviceDataContextID": "a7a116e7-a90c-4814-b90a-d0825c428cac",
  "insertedDate": "2020-06-16T16:05:54.767Z",
  "modifiedDate": "2020-06-16T16:05:54.767Z",
  "participantID": "58b331cc-50ee-460b-8e7e-871e08867687",
  "participantIdentifier": "PT-123",
  "identifier": "7fc24c0f-fc26-44b1-88f3-22d8750f00b3",
  "type": "DistanceWalkingRunning",
  "value": "7.8970013065263629",
  "units": "m",
  "properties": {
    "PostalCode": "12345"
  },
  "source": {
      "identifier": "6D8C7vR",
      "properties": {
          "SourceIdentifier": "com.apple.health.E9BBF489-8AE9-4D5F-983C-E66ED450FAE6",
          "SourceName": "Jane's iPhone 11",
          "SourceOperatingSystemVersion": "13.5.1",
          "DeviceManufacturer": "Apple Inc.",
          "DeviceModel": "iPhone",
          "UploadingDeviceIdentifier": "07e9524a-2a82-4875-b700-92d7e4024cb5"
      }
  },
  "startDate": "2020-06-16T10:52:11-05:00",
  "observationDate": "2020-06-16T10:52:17-05:00"
}
  {
  "id": "4f73e5ec-e52b-4651-a8e2-42a6555b6601",
  "namespace": "AppleHealth",
  "deviceDataContextID": "a7a116e7-a90c-4814-b90a-d0825c428cac",
  "insertedDate": "2020-06-16T16:05:54.767Z",
  "modifiedDate": "2020-06-16T16:05:54.767Z",
  "participantID": "58b331cc-50ee-460b-8e7e-871e08867687",
  "participantIdentifier": "PT-123",
  "identifier": "7fc24c0f-fc26-44b1-88f3-22d8750f00b3",
  "type": "DistanceWalkingRunning",
  "value": "7.8970013065263629",
  "units": "m",
  "properties": {
    "PostalCode": "12345"
  },
  "source": {
      "identifier": "6D8C7vR",
      "properties": {
          "SourceIdentifier": "com.apple.health.E9BBF489-8AE9-4D5F-983C-E66ED450FAE6",
          "SourceName": "Jane's iPhone 11",
          "SourceOperatingSystemVersion": "13.5.1",
          "DeviceManufacturer": "Apple Inc.",
          "DeviceModel": "iPhone",
          "UploadingDeviceIdentifier": "07e9524a-2a82-4875-b700-92d7e4024cb5"
      }
  },
  "startDate": "2020-06-16T10:52:11-05:00",
  "observationDate": "2020-06-16T10:52:17-05:00"
}

Query Device Data

GET api/v1/administration/projects/:projectID/devicedatapoints?namespace=Project&pageSize=10

The device data query supports two different date queries: modifiedBefore/After and observedBefore/After. Due to variations and limitations in device data synchronization, it is possible for older data points to turn up in the system unpredictably. Using the “observed” query parameters will search based on the date the data was observed or recorded by the device, while the “modified” parameters will search based on the date it arrived in the system. Use the modifiedAfter query to search for data that has arrived since a prior query.

Note
If your project has enabled an end date for sensor collection, you must specify a participantID or participantIdentifier when querying for device data.

Query Parameters

namespace string (required)

Source framework for the device data. See namespaces for details.

participantID guid

Search for device data for a participant based on the participant’s internal ID field.

participantIdentifier string

Search for device data for a participant based on the project-specific participant identifier.

type string

Comma-separated list of types of device data, e.g. HeartRate.

observedBefore date

Search device data points observed before this date, in ISO8601 format.

observedAfter date

Search device data points observed after this date, in ISO8601 format.

modifiedBefore date

Search device data points updated in the system before this date, in ISO8601 format.

modifiedAfter date

Search device data points updated in the system after this date, in ISO8601 format.

limit int

How many entries to include in each page of results. Default and maximum is 100.

pageID guid

Each page of results will return a nextPageID if there are additional pages that can be queried. Supply that to pageID to query the next page. When excluded, retrieves the first page.

Response Fields

deviceDataPoints collection

A list of the device data points.

+ Element Fields

deviceDataPoints[n].id guid

Auto-generated, globally-unique identifier for this device data point.

deviceDataPoints[n].namespace string

Source framework for the device data. See namespaces for details.

deviceDataPoints[n].deviceDataContextID guid

Identifier for a group of device data points, which share some context. Will be null if the device data point isn’t grouped.

deviceDataPoints[n].participantIdentifier string

Identifies the participant associated with the data.

deviceDataPoints[n].insertedDate date

Date when the record was created, in ISO8601 format.

deviceDataPoints[n].modifiedDate date

Date when the record was last modified, in ISO8601 format.

deviceDataPoints[n].identifier string

String used to name a device data point.

deviceDataPoints[n].type string (required)

The general category this device data point belongs in, or what the device data represents. This field is a freeform string controlled by the source system based on its chosen categories.

deviceDataPoints[n].value string (required)

The value of the recorded data point.

deviceDataPoints[n].units string

The units, if any, that the data was recorded in.

deviceDataPoints[n].properties object

An object whose key-value pairs represent metadata associated with this device data point. The metadata will vary depending on the source application.

deviceDataPoints[n].source deviceDataSource

An object containing identifying information about the device which recorded the data point.

+ Child Fields

deviceDataPoints[n].source.identifier string

Identifying string for the data source.

deviceDataPoints[n].source.properties object

An object whose key-value pairs represent properties of the device data source. The specific properties will vary depending on the source application.

deviceDataPoints[n].startDate date

The date at which this device data point began being recorded (for data that is recorded over time), in ISO8601 format.

deviceDataPoints[n].observationDate date

The date at which this device data point was completely recorded, in ISO8601 format.

nextPageID guid

Identifier that you can use to retrieve the next page of results.

    Sample Response 
    
  

    {
  "deviceDataPoints": [
    {
      "id": "4f73e5ec-e52b-4651-a8e2-42a6555b6601",
      "namespace": "AppleHealth",    
      "type": "HeartRate",
      ...
    },
    {
      "id": "f716b2c5-980d-484f-a4b4-8663e9acc506",
      "namespace": "AppleHealth",
      "type": "HeartRate",
      ...
    },
    ...
  ],
  "nextPageID": "660874e9-ae7d-40e3-a7d2-b4ef0e5e465b"
}
  {
  "deviceDataPoints": [
    {
      "id": "4f73e5ec-e52b-4651-a8e2-42a6555b6601",
      "namespace": "AppleHealth",    
      "type": "HeartRate",
      ...
    },
    {
      "id": "f716b2c5-980d-484f-a4b4-8663e9acc506",
      "namespace": "AppleHealth",
      "type": "HeartRate",
      ...
    },
    ...
  ],
  "nextPageID": "660874e9-ae7d-40e3-a7d2-b4ef0e5e465b"
}

See Device Data Object for all device fields.

Persist Device Data

POST api/v1/administration/projects/:projectID/devicedatapoints

Persist device data can be used to add new or update existing points.

Note
This API operates within the Project namespace. You cannot alter or add data in other namespaces.

Each device data point is uniquely identified by a combination of the following properties:

identifier
type
startDate
observationDate

If all four of these properties exactly match the existing data point in a persist action, the other data will be updated. Otherwise, a new data point will be created.

Tip
Recommended properties include identifier, type and observationDate; these can be made into a unique combination for most device data points.

Body Parameters

models collection

List of data point models.

+ Element Fields

models[n].participantIdentifier string

Identifies the participant associated with the data.

models[n].identifier string

String used to name a device data point.

models[n].type string (required)

The general category this device data point belongs in, or what the device data represents. This field is a freeform string controlled by the source system based on its chosen categories.

models[n].value string (required)

The value of the recorded data point.

models[n].units string

The units, if any, that the data was recorded in.

models[n].properties object

An object whose key-value pairs represent metadata associated with this device data point. The metadata will vary depending on the source application.

models[n].source deviceDataSource

An object containing identifying information about the device which recorded the data point.

+ Child Fields

models[n].source.identifier string

Identifying string for the data source.

models[n].source.properties object

An object whose key-value pairs represent properties of the device data source. The specific properties will vary depending on the source application.

models[n].startDate date

The date at which this device data point began being recorded (for data that is recorded over time), in ISO8601 format.

models[n].observationDate date

The date at which this device data point was completely recorded, in ISO8601 format.

Response Fields

None

    Sample Body Parameters 
    
  

    [
  {
    "identifier": "0b425f95-7c43-42f6-b069-60cbb11dce1d",
    "observationDate": "2020-06-16T10:52:17-05:00",
    "type": "SBP",
    "value": "120",
    "units": "mmHg",
    "participantIdentifier": "PT-123",
    ...
  },
  {
    "identifier": "0b425f95-7c43-42f6-b069-60cbb11dce1d",
    "observationDate": "2020-06-17T11:50:10-05:00",
    "type": "SBP",
    "value": "120",
    "units": "mmHg",
    "participantIdentifier": "PT-123",
    ...
  },
  ...
]
  [
  {
    "identifier": "0b425f95-7c43-42f6-b069-60cbb11dce1d",
    "observationDate": "2020-06-16T10:52:17-05:00",
    "type": "SBP",
    "value": "120",
    "units": "mmHg",
    "participantIdentifier": "PT-123",
    ...
  },
  {
    "identifier": "0b425f95-7c43-42f6-b069-60cbb11dce1d",
    "observationDate": "2020-06-17T11:50:10-05:00",
    "type": "SBP",
    "value": "120",
    "units": "mmHg",
    "participantIdentifier": "PT-123",
    ...
  },
  ...
]

See Device Data Object for all device fields.