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

NameDescription
MeasurementsProvides point in time measurements, like height, weight, blood pressure, glucose, etc.
NutritionProvides a summary of your daily nutritional intake.
SleepProvides a record of your sweet, sweet dreams.
SummariesA summary of your daily activity, like steps, calories and heart rate.
WorkoutsProvides a list of all workout events.
IntradayReturns 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

ParameterDescription
uidThe customer's user ID.
object_typeA supported Validic REST resource as defined in the list above.
start_dateThe start date to retrieve user data for. Format: YYYY-MM-DD. The default is current UTC day. Max date range is 30 days.
end_dateThe 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 CodeValueDefinition
200OKRequest processed successfully.
400Bad RequestInvalid request. See error messages for details.
401UnauthorizedProvided customer token is not allowed to access the API.
404Not FoundThe requested item does not exist.
422Unprocessable EntityWell-formatted, but semantically erroneous request entity. See error messages for details.
50nServer ErrorError 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"
    ]
  }
}