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"
]
}
}
Updated 10 months ago