Inform REST API

While our Inform Streaming API is designed for bulk data transfers, our REST API provides a traditional RESTful API experience delivering full access to wellness data within the user level. The on-demand, Validic REST API is designed specifically for customers who would like to integrate the web & mobile applications with wellness data from Validic.

REST API Resources

The following resources are accessible in the REST API. You can review these resources in detail in the API Resource Section

Name

Description

Measurements

Provides point in time measurements, like height, weight, blood pressure, glucose, etc.

Nutrition

Provides a summary of your daily nutritional intake.

Sleep

Provides a record of your sweet, sweet dreams.

Summaries

A summary of your daily activity, like steps, calories and heart rate.

Workouts

Provides a list of all workout events.

Intraday

Returns a list of time series data for a given user.

Requests

REST API endpoints that support retrieving user's data (i.e. non-administrative endpoints) will leverage the following URI convention:
GET /organizations/:org_id/users/:uid/:object_type?date=:date

Parameter

Description

uid

The customer's user ID.

object_type

A supported Validic REST resource as defined in the list above.

start_date

The start date to retrieve user data for. Format: YYYY-MM-DD. The default is current UTC day. Max date range is 30 days.

end_date

The end date to retrieve user data for. Format: YYYY-MM-DD. The default is current UTC day. Max date range is 30 days.

REST Access Patterns

Request to the API are Data from the REST API are scoped to a specific customer user ID. This user ID, or "uid" is defined by you when the user is provisioned. To ensure your HIPAA compliance, please do not use any identifying information such (but not limited to) as:

  • Social Security Numbers
  • Names
  • Phone Numbers
  • Email Addresses

Endpoints are also scoped to a specific date. You may request up to 30 days of data per request. Unless otherwise discussed with your Validic Account Manager, Validic will store and make available by REST API request, up to one year of data. To ensure HIPAA compliance, we will store all data for seven years. This data can be requested through a support request.

Restrictions

Rate Limits
Customer's ability to access Validic API endpoints is bound by rate limits. The specific limits are defined per customer token. The default rate limit for the REST API is 250 requests per access token, per hour.

Filters

When requesting data using the REST API, you can filter your request by a specific day and data source. For instance, if you wanted all weight records for Jawbone on a specific day, you’d make the following request:

https://api.v2.validic.com/organizations/:org_id/users/demotestuser1/measurements?start_date=2017-03-29&end_date=2017-03-29&source=jawbone&token=SAMPLETOKENbcb4928c72b4

Source

The Source represents the source of the data. You may present multiple sources in a request by presenting them as comma separated values (“...?source=fitbit,garmin”).
The naming convention of the source corresponds to the value found in the type field of an API response:

source: {
type: "jawbone"

The following example shows a sample filtered request and response.

https://api.v2.validic.com/organizations/:org_id/users/demotestuser1/measurements?start_date=2017-03-29&end_date=2017-03-29&source=jawbon&token=abeed1ffSAMPLETOKENbcb4928c72b4
{
  "data": [
    {
      "id": "5fc823cbc5354e0dd2a6ca9077966ebe",
      "type": "measurement",
      "user": {
        "uid": "demotestuser1",
        "user_id": "58dbc866SAMPLE001e6b7c7",
        "organization_id": "58cb5SAMPLEa50001f75db3"
      },
      "log_id": "5ygFj7_aPSR67gdlBffMq9UiylACSbji",
      "source": {
        "type": "jawbone"
      },
      "metrics": [
        {
          "type": "body_weight",
          "unit": "kg",
          "value": 68.0388555571,
          "origin": "unknown"
        }
      ],
      "version": "1.0",
      "checksum": "9e2d1383c8336aada9ae1ec286b21f93",
      "end_time": "2017-03-29T15:59:56Z",
      "created_at": "2017-03-29T16:48:55.370Z",
      "start_time": "2017-03-29T15:59:56Z",
      "utc_offset": -14400,
      "offset_origin": "source"
    }
  ]
}

Errors

Conventional HTTP response codes are used to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, etc.), and codes in the 5xx range indicate a server error.

HTTP Status Code

Value

Definition

200

OK

Request processed successfully.

400

Bad Request

Invalid request. See error messages for details.

401

Unauthorized

Provided customer token is not allowed to access the API.

404

Not Found

The requested item does not exist.

422

Unprocessable Entity

Well-formatted, but semantically erroneous request entity. See error messages for details.

50n

Server Error

Error on the server when processing the request. See error message for details.

{
  "errors": [
    "unable to find customer for requested id."
  ]
}

{
  "errors": {
    "type": [
      "invalid source type"
    ]
  }
}

Did this page help you?