Device Data API

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

Device Data Object

The basic device data object is common to many of the device APIs.

Device data is grouped into namespaces, which represent the source frameworks that generate the data. They may be:

  • “Project”: Data persisted by project sources and SDKs.
  • “Fitbit”: Data persisted by a linked Fitbit account.
  • “AppleHealth”: Data imported from AppleHealth.
  • “GoogleFit”: Data imported from GoogleFit.
id guid

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

namespace string

Source framework for the device data.

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.

insertedDate date

Date when the record was created, in ISO8601 format.

modifiedData 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.

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.

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"
}
               
    

Query Device Data

GET api/v1/administration/projects/{projectID}/devicedatapoints?type=HeartRate&pageSize=10

Query Parameters

namespace string (required)

Source framework for the device data.

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

Filters device data points to those observed before this date, in ISO8601 format.

observedAfter date

Filters device data points to those observed 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.

deviceDataPoints[n].id guid

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

deviceDataPoints[n].namespace string

Source framework for the device data.

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].insertedDate date

Date when the record was created, in ISO8601 format.

deviceDataPoints[n].modifiedData 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.

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.

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"
}
               
    
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. 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.

Body Parameters

models collection

List of data point models.

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.

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.

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 Response
[
  {
    "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.

Back to API