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 6 months 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 2,000 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"
    ]
  }
}