Introduction

Validic collects de-identified patient data from wearables, clinical devices and patient healthcare applications. Validic is a behind the scenes IT infrastructure solution where with one simple RESTful API connection to Validic, you have access to the standardized, secure data you need to accelerate your strategic business initiatives, reduce costs and improve patient outcomes.

The information contained in this section of the documentation will enable you to quickly and efficiently integrate with the Validic API.

  • Validic API Overview
  • Validic Organizations
  • Frequently Asked Questions
#

Overview

Validic REST API Overview

The Validic API is designed to enable a simple, standardized connection between healthcare companies and mobile health and wellness apps and devices. Validic captures a user’s fitness activities and health measurements over time. Each activity and measurement contains a timestamp and a note about which integration was used to track the activity.

The Validic REST API uses token-based authentication to manage and automate the creation of user accounts. All communication with the API is performed through HTTPS, and errors are communicated through HTTP response codes. All requests return JSON data.

A core aspect of the Validic API is to vastly increase the speed of integration between mHealth app developers and healthcare businesses. Additionally, Validic provides critical enterprise features needed by healthcare companies that are not usually provided as a core service by app developers. These features include:

HIPAA/SafeHarbor/PHI Compliance
Validic eliminates concerns regarding the transfer of protected health information (PHI), as all data stored in and transferred through Validic follows the “Safe Harbor” de-identification standard and complies with all HIPAA regulations.

Standardized Endpoints
App developers and healthcare companies rarely speak the same language. The Validic REST API translates to something both sides can understand.

Full 3rd Party API Access
In addition to standardized endpoints, Validic offers the ability to access endpoints that fall outside our standards. For example, Nike+ fuel is not a standard Validic endpoint, but there is a way to expose that data.

Reduced Workload
Healthcare companies are focused on increasing engagement and improving population health. App developers are focused on building compelling apps. Validic allows both parties to remain focused on their core competency by building and maintaining app connections, aggregating data, and managing system updates.

Easy connectivity
The Validic health app marketplace allows for a simple, one-to-many connection for healthcare businesses and app developers alike. If your company is wishing to connect with 100+ mHealth apps and devices Validic makes it simple. Get started below, and if you have any questions, contact us.

#

Validic Organizations

An Organization is a collection of Validic users. An Organization typically represents a company that delivers the Validic marketplace through its web portal or mobile application. After entering into an agreement with Validic, we will issue you Organization Credentials. Each Organization has its own unique authentication credentials consisting of an Organization ID and Organization Access Token.

Validic Enterprise customers have the ability to also create “Child” Organizations, which are Organizations that “belong” to the primary or “Parent” Organization. This allows for companies that deliver Validic to multiple customers through a web portal or mobile application to segment users and provide a unique branding experience.

#

FAQ’s

What types of data do you collect from your multiple device and app vendors?
The primary categories are Fitness, Routine, Nutrition, Sleep, Weight, Diabetes and Biometric data.

How do you get the data from the devices?
Gathering data from each of the device/app manufacturers is one of the key values we deliver to our customers. For most apps/devices we maintain connections directly through their open API. In some cases, we connect directly to the device/system or they write directly to us. Validic also has a proprietary mobile application and SDK that captures data from non-networked bluetooth LE enabled devices. Once your users allow your application access to these apps/devices in the marketplace, we will pull their de-identified data into our system.

Do we need to set up a direct deal with each of these apps or devices or is that all done through you?
It’s all done through us. You simply need to work with our API and it is our job to manage each app and device.

How does the data get to us? Does the data push to us or do we have to pull from you?
You can pull data from us anytime with no call limits. Our Enterprise customers may also register push notification URL’s with us in order to receive pub-sub notifications when new data is available for your end users so you can initiate a fetch to pull data.

How often is the data updated? How long until someone sees their data appear?

 
We have a bountiful Knowledge Base containing many articles to help our customers have information such as this at their finger tips. Please view the Data Sync Time by Source article for details regarding this topic.

When the data comes to me, what form is it in?
Data delivered from the Validic API comes as clean, complete and actionable JSON data that has been standardized and normalized to allow you to put that data to use much more quickly and efficiently.

Are units of metrics published? Is everything standardized?
Yes, a major part of our value is that we give you clean, complete and actionable data that is both standardized and normalized. We standardize all nomenclature so steps are always steps, not steps taken or strides, for example.We normalize all units so distances are always in meters,not yards or miles, and time is in seconds for example. This is all explained in detail in the data objects section of our API Documentation.

How long does it take to deploy?
This depends on how deeply you want to integrate in our system and your current stage of development. One of the many values Validic provides is an easy to work with, scalable API that can quickly be integrated with your system. We’ve had some clients begin making calls within a matter of hours. However, a typical implementation will last 2-10 weeks. We are very hands on during the implementation process including a technical kickoff call, a discussion of potential trouble spots, best practices, ongoing support and resources pre and post go live.

How does the Validic Marketplace fit into our app/portal?
There are two ways of implementing the Validic Marketplace.
1. Deploying the Validic Standard HTML5 Marketplace.
2. Building your own marketplace/user experience via one simple API call providing all the
needed data end points and URL’s to do so.

More information on deploying the Validic Marketplace can be found in the Sync Apps & Devices section of our API Documentation.

Can you customize which apps/devices are displayed in the Marketplace?
Yes, you can curate which apps and devices you would like users to have access to.

Do I need to load Validic on my servers?
No, we are a remotely managed API so there is nothing to install.

Can we get developer data to get started?
Yes, once you’ve signed an NDA we can discuss next steps in providing you with all of the information you need to test the Validic system and determine that it is a viable solution for your needs.

What is the difference between Sandbox and Production credentials?
Both sets of organization credentials provide full access to partners, apps, devices and data. However, the Sandbox credentials, primarily used during testing, do not allow customer branding of the Marketplace. Thus, in the Sandbox environment, all end (test) users will see Validic branding when asked to authenticate.

What is the user provisioning and authentication process?
The user provisioning and authentication process, as Validic refers to it, is a series of two ID (token) exchange mechanisms, or handshakes, that ultimately enables your end user data to remain completely safe, secure and de-identified. This means, through this process, Validic adheres to US-EU-Swiss Safeharbor certification requirements and is fully HIPAA compliant. For technical details regarding this topic, please refer to the Users section of our API Documentation.

How long do you keep the data?
In compliance with HIPAA standards Validic persists deidentified data for a minimum of 7 years.

Can we see which device the data came from?
Yes, all data records returned from Validic are sourced. More information regarding data sources and filters can be found in the Filters section of our API Documentation.

Do you have any SDKs (software development kits) or libraries?
Since we have a straightforward api which is easy to deploy we do not offer an SDK for API integrations. Enterprise customers may discuss mobile app SDK availability with their sales person. We do offer/recommend certain OAuth2 libraries for Ruby and C# which can be found in the resources section of our API Documentation.

Can the standard/default marketplace be used in an iframe?
The standard marketplace is built in HTML5 and can, therefore, be used in an iframe. However, it is important to note, that some of the device vendors’ OAuth pages do not render properly in an iframe. Therefore, Validic does not recommend the use of an iframe as a means to display the standard marketplace.

Is it possible for it to say that our company is requesting access to the data not Validic?
Yes, that is our standard practice. That said, this is only available with Production credentials and not available with Sandbox credentials.

When we authenticate a user through the marketplace, does the Validic server store the OAuth token on behalf of our client app or are the client credentials created in a totally different mechanism between individual cloud server and Validic?
Validic stores and maintains the OAuth client credentials for each of the integrated partners (Fitbit, Withings, Jawbone, etc.) and our customers only have to be concerned with managing the one connection with Validic.

Does the OAuth token expire?
No, but we offer an OAuth refresh if desired.

Can the verbiage of the UI be customized?
The standard marketplace has limited customization; however, our Enterprise customers have the option to deploy the custom marketplace in which case they may create their own user interface.

Is the current marketplace web view responsive on mobile?
Yes. Validic is platform and device agnostic.

Can we download the entire data set instead of one end user at a time?
We only allow data to be accessed for those end users who have authenticated with app/device vendors and we do not sell or permit downloads of the entire data set. Data calls to the Validc API may be made at the organization (population) or user level and additional bulk population level data delivery calls are available as well. For more information, please visit the Data Retrieval section of our API Documentation.

If someone was terminated from a company would we have to manually delete them from the Validic system?
Yes, you would send use a DELETE call accompnied by the user access token which results in the deletion of the user and any of their activities in our system. For details on this, please visit the Users section of our API Documentation.

How does the duplication work with multiple apps? What if their run is tracked by multiple apps and devices?
We don’t make assumptions about the data and will return data returned by both devices. The exception is when a single device may upload the same activity to multiple vendors’ websites, in which case we dedup that record.

Is there any non-identifiable demographic information that is available for users?
Yes, if it is available from the app/device vendor, we are able to collect and supply Gender, State, Country, Birth Year, Height and Weight.

Are all of the apps pull? Or do some of the apps push data as well?
We receive push notifications from some of our integration partners. We fetch data on regular intervals for the remaining vendors.

How long are response times typically?
The Validic API averages 40-60ms response times.

Do you pull directly from devices or when they are synced?
We interact with the web presence (when it becomes available to their cloud) not to the actual hardware. The exception is Validic’s proprietary mobile application and SDK that captures data directly from BLE clinical devices.

Do you collect any extra data?
Some non-standardized data points, such as Nike Fuel Points, can be made available through an expanded filter. For more information regarding data filters please visit the Filters section of our API Documentation.

How do you deal with timezones?
This varies depending on our vendor integration partner. For more information, please read the Timestamp Format & UTC Timezone Offset Support article.

Is the data encrypted?
Yes, the data is encrypted in transit and at rest via 256-bit encryption.

Who owns that data?
Validic does not make any claims regarding the ownership of the data and ultimately your end users own that data thus enabling them the ability to retract access to their data.

Can access tokens be sent using an Authorization HTTP Header?
Yes. Here are two ways to make an API call with the Access Token added as an
Authorization HTTP Header:
Via cURL:

curl -X GET -H ‘Authorization: Token token={ACCESS_TOKEN}’
https://api.validic.com/v1/organizations/{ORGANIZATION_ID}.json

– via Standard REST template with Authorization HTTP Headers:

GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}.json -H ‘Authorization:
Token token={ACCESS_TOKEN}’

What is the difference between using the latest.json endpoint and push notifications?
The primary difference is that push notifications are intended for real time, individual user-level data delivery, while the latest.json endpoint is intended for near real time, bulk population-level data delivery. For more information, please read our knowledgebase article: Latest endpoint vs. Push Notifications.

How do I reset or re-acquire a user’s authentication token?
Should you require resetting or re-acquiring a user’s authentication token (the authentication token is provided in our API response when the user is provisioned in our system), you may make a GET request call for a new user authentication token:

GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{VALIDIC_USER_ID}/
refresh_token.json?access_token={ACCESS_TOKEN}
200
{
“code”: 200,
“message”: “Ok”,
“user”: {
“id_”: “51552cd7fded0807c4000017″,
“uid”: “1234567890”,
“authentication_token”: “uXek7RK2wUnm84BJRv5Q”
}
}

How do I paginate through large record sets?
When making API calls, it is normal for a given scope (“start_date” and “end_date” of an API call)to include a large record resultset. However, only 100 of these records would be included in the response, up to a maximum of 200 records by adding a “limit” parameter. In order to access the rest of the records in the result set, you may then use the “next” attribute of the Summary object in the API response. The value of “next” is a full HTTP resource that you can use to make an API request and retrieve the next set of records in the resultset. Please note that the succeeding response may as well contain value for the “next” attribute.

Is there an endpoint that returns all the activities (routine, fitness, weight, etc) for a user for a requested period of time?
We do not have a feature to return all activities of a specific user at a certain period of time. We only return activity records per endpoint (Fitness, Routine, Nutrition, Sleep, Weight, Diabetes, Biometric, and Tobacco Cessation).

I am getting a 409 error when provisioning a user, how do I resolve this?
There may be cases where you were unable to save the user’s Validic ID and Access Token during User Provisioning. When you try to provision the same user using the same `uid`, you get a 409 Conflict Response. For more information regarding steps to resolution, please visit our How to Resolve 409 Conflict knowledge base article.

Can we get the total number of users who have already connected an app?
There are three options you may use in order to capture the total number of your users who have already connected an app.

The first option is by making an OrganizationID.json API Call. In the API response, you will be able to retrieve the total number of users who have already connect an app by looking at the “users” field. You may be able to do this by making the sample API Call:

GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}.json?access_token={ORGANIZATION_ACCESS_TOKEN}

The second option is by making the Users.json API Call and appending the parameter “status=active”. Here, you are able to verify the Validic USER IDs or “_id” with each having a corresponding “uid” or the users’ unique identification used when they were provisioned. The API response using this API Call will enable you to see the total number of active users, which by definition mean that they have already connected at least one app. You may be able to do this by making the sample API Call:


GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users.json?access_token={ORGANIZATION_ACCESS_TOKEN}&status=active

The third option is by making the Profile.json API Call. The Profile.json endpoint provides a listing of applications currently synced by user, which will give you the benefit of aggregating the total number of users who have synced a particular application. To do this, you may loop through each of your users and make the following API call below:

GET https://api.validic.com/v1/profile.json?authentication_token={USER_ACCESS_TOKEN}

Why are we receiving 404 errors when using the Validic standard marketplace?
When using the Validic standard marketplace, users may encounter 404 errors when accessing the Marketplace. This is normally caused by the following:

  • missing or invalid User Access Token in the Marketplace URL
  • missing or invalid Organization ID in the Marketplace URL

When this occurs, you may troubleshoot by making sure the proper Organization ID and the user’s current User Access Token is supplied in the URL.

Can we sync one vendor account into multiple Validic users?
Yes and no, the behavior is typically dependent on the authorization process of the app. For additional information, please read our knowledge base article on the topic.

#

Getting Started

The following section will provide you with four simple steps that encompass the basic information necessary to make a quick connection with the Validic API.

#

Step 1: Verify your Validic Organization Credentials

If you haven’t already, contact us for a Validic account.

Once you have your Organization credentials, you may verify if your credentials are working by making the following API call:

GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}.json?access_
token={ORGANIZATION_ACCESS_TOKEN}
 200
 {
 "summary": {
 "status": 200,
 "message": "Ok",
 "results": 1,
 "start_date": null,
 "end_date": null,
 "offset": 0,
 "limit": 100,
 "params": {
 "start_date": null,
 "end_date": null,
 "offset": null,
 "limit": null,
 "source": null
 }
 },
 "organization": {
 "_id": "{ORGANIZATION_ID}",
 "name": "{ORGANIZATION_NAME}",
 "users": 64,
 "users_provisioned": 124,
 "activities": 25334,
 "connections": 260,
 "organizations": []
 }
 }
#

Step 2: User Provisioning

Provisioning users is an ID exchange mechanism that allows your users data to remain de-identified, safe and secure. To provision users in Validic, you will need the Organization ID and Organization Access Token you received from Validic. You will identify a user to Validic via a POST call containing a non-identifiable UID and Validic will return to you a Validic user ID and user Access Token.

First, the user provisioning POST call requires setting HTTP headers to “Content-Type: application/json”.

Second, the CUSTOMER_USER_ID information you need to pass is your user’s identifier in your application, typically a user ID. We require using non-identifiable IDs instead of emails or names in order to remain compliant with HIPAA/PHI deidentification standards.

You need to store the corresponding USER_ID and USER_ACCESS_TOKEN from the response for the provisioned user. You will refer to them when accessing user-related API calls in the future.

The user provisioning call is made as follows:

POST https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users.json
 {
 "user": {
 "uid": "{CUSTOMER_USER_ID}"
 },
 "access_token": "{ORGANIZATION_ACCESS_TOKEN}"
 }
 201
 {
 "code": 201,
 "message": "Ok",
 "user": {
 "_id": "{USER_ID}",
 "access_token": "{USER_ACCESS_TOKEN}"
 }
 }

For full detail regarding user provisioning and user related API calls, please visit
the Users section of our API Documentation.

#

Step 3: Deploying the App Marketplace

You have now verified your Organization Credentials and Provisioned Users within the Validic system, now you want to begin gathering user data. Validic enables your users to connect an app/device and permission the use of that data via what Validic refers to as the App Marketplace.

Validic provides two ways of deploying the marketplace. All customers may deploy the Validic standard HTML5 App Marketplace and our Enterprise customers may also deploy the custom marketplace, which allows our clients to build out the Marketplace with a consistent, cohesive user experience.

Validic Standard HTML5 App Marketplace:

The Validic Standard HTML5 version of the App Marketplace provides developers with a quick and easy connection process to access data from our integration partners without any additional development work. You simply need to send your users to the Validic Standard App Marketplace. The Validic App Marketplace lists all the available apps and allows users to sync and authorize access to their app data. Through the App Marketplace your users will be prompted to connect a device and will be walked through an authorization process that permissions the use of their data to you.

You need to construct and send the user to this URL for the user to access the Validic
App Marketplace:

GET https://app.validic.com/{ORGANIZATION_ID}/{USER_ACCESS_TOKEN}

 

Custom App Marketplace Deployment:

Our Enterprise customers may also design and create a custom implementation of your own App Marketplace. To authenticate users, you will need your Organization’s ID, your Organization’s Access Token, and the User Access Token created when you provisioned the user. Validic provides our Enterprise customers with one simple API call to access all of the appropriate URL’s and information needed to build the custom App Marketplace native to your platform leveraging your existing look and feel enabling you to create a consistent, cohesive user experience.

Please view our API Documentation for further information on how to deploy the App Marketplace, example calls, and to see a live demo of the Validic Standard HTML5 App Marketplace.

#

Step 4: Accessing Data

Now that your user has synced and authorized device data, Validic will begin fetching the user’s data immediately and that data will be available in the Validic system for you to retrieve. You need to use an HTTPS request to fetch an object(s), which are returned in JSON format. To do this, simply append your Organization Access Token to the end of the request. For example, to see a list of fitness activities for a user account:

GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/fitness.json?acces
s_token={ORGANIZATION_ACCESS_TOKEN}

 

A full list of Validic object types, parameters, API calls, data filters and detailed technical how to’s can be found in our API Documentation

#

API Documentation

Organization Credentials

Your Organization credentials consist of a unique Organization ID and Organization Access Token. Your organization credentials are issued during the Validic implementation process. Once you have been issued your Validic Organization credentials, please make the following organization overview API call to verify your credentials are functioning properly.

#

Organization Summary Overview

Example

To retrieve a summary overview of an Organization and its Child Organizations make the following call:

GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}.json?access_token={ORGANIZATION_ACCESS_TOKEN}
GET https://api.validic.com/v1/organizations/516828cf6deddabe51000001.json?acc
ess_token=e61467e3845e8a66f7453dc55ea3fc445d1b879a6f96ebe7b243badbeae04
f63
200
{
"summary": {
...
}, "organizations": {
"_id": "516828cf6deddabe51000001",
"name": "Sample Organization",
"users": 25442,
"users_provisioned": 83211,
"activities": 453298,
"connections": 38749,
"organizations": [
{
"_id": "516828df6deddabe51000004",
"name": "Child Org 1",
"users": 11892,
"users_provisioned": 31923,
"activities": 212783,
"connections": 17453,
"organizations": []
}, {
"_id": "516828df6deddabe51000008",
"name": "Child Org 2",
"users": 11529,
"users_provisioned": 48384,
"activities": 240515,
"connections": 21296,
"organizations": []
      }
    ]
  }
}

Organization Overview Params

Field
Type
Description
name
String
The name of the Organization. Used primarily for internal identification rather than public display.
users
Integer
The number of users under an Organization with one or more apps connected. This number is aggregate for an Organization and its Child Organizations.
users_provisioned
Integer
The total number of users with a provisioned Validic account (including those without one or more apps connected). This number is aggregate for an Organization and its Child Organizations.
activities
Integer
A running total of all activities logged under an Organization. This number is aggregate for an Organization and its Child Organizations.
connections
Integer
The number of live connections between an Organization’s users and their apps. This number is aggregate for an Organization and its Child Organizations.
#

Users

users
#

Provisioning Users

To ensure HIPAA/PHI compliant data storage and transfer, Validic does not store identifiable user information in our system. As such, users must be provisioned in a unique way to provide user authentication and data linkage between your system and Validic.

When provisioning a user in Validic, you will be required to pass a unique User ID (UID). This UID is typically the user’s ID in your system. This information is encrypted before being stored in our system.

Users are provisioned in Validic with a POST call that includes a unique UID and the organization’s access_token (both are required), and optional profile parameters.

After the user POST request is sent, a 201 Created HTTP response code will be returned, echoing your input with the addition of a Validic User ID and User Authentication Token. It is imperative that you store the id and access token, as they will be used to help authenticate the user to Validic.

Basic User Provisioning:

Example
POST https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users.json
POST https://api.validic.com/v1/organizations/516828cf6deddabe51000001/users.js
on
-H 'Content-Type: application/json'
{
"user": {
"uid": "123467890"
    },
  "access_token": "e61467e3845e8a66f7453dc55ea3fc445d1b879a6f96ebe7b243bad
beae04f63"
}
201
{
"code": 201,
"message": "Ok",
"user": {
"_id": "51552cd7fded0807c4000017",
"uid": "123467890",
"access_token": "d18397e3845e8b66f7453dc55ea3fc445d1b879a6f96ebe7b243b
adabce08c98",
"profile": null
  }
}
#

User Provisioning with Optional Profile Parameters:

Example
POST https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users.json
POST https://api.validic.com/v1/organizations/516828cf6deddabe51000001/users.js
on
 -H 'Content-Type: application/json'
 {
 "user": {
 "uid": "123467890",
 "profile": {
 "gender": "M",
 "location": "NC",
 "birth_year": "1973",
 "height": 167.5,
 "weight": 83.9146
 }
 },
 "access_token": "e61467e3845e8a66f7453dc55ea3fc445d1b879a6f96ebe7b243bad
beae04f63"
 }
 201
 {
 "code": 201,
 "message": "Ok",
 "user": {
 "_id": "51552cd7fded0807c4000017",
 "uid": "123467890",
 "access_token": "d18397e3845e8b66f7453dc55ea3fc445d1b879a6f96ebe7b243b
adabce08c98",
     "profile": {
       "gender": "M",
       "location": "NC",
       "birth_year": "1973",
       "height": 167.5,
       "weight": 83.9146
     }
   }
 }
#

Refreshing or Re-acquiring the User’s Access Token:

If you need to reset or re-acquire a user’s access token, you may make a GET request call for a new user access token:

Example
GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{USER_ID}/refresh_token.json?access_token={ORGANIZATION_ACCESS_TOKEN}
GET https://api.validic.com/v1/organizations/516828cf6deddabe51000001/users/51
552cd7fded0807c4000017/refresh_token.json?access_token=e61467e3845e8a66f74
53dc55ea3fc445d1b879a6f96ebe7b243badbeae04f63
 200
 {
 "code": 200,
 "message": "Ok",
 "user": {
 "_id": "51552cd7fded0807c4000017",
 "uid": "123467890",
 "authentication_token": "cPDsxsTuLpSmgsxsXuLF3dc55ea3fc441d1b899a6fU6e
beTb243xadabce08d98"
 }
 }
#

Updating Users

Should you need to update a user, such as changing the uid you initially set in during User Provisioning, you may make a PUT request to modify the user:

Example
PUT https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{USER_ID}.json
PUT https://api.validic.com/v1/organizations/5176906c6deddac02c000001/users/51
552cd7fded0807c4000017.json
 -H 'Content-Type: application/json'
 {
 "user": {
 "uid": "abcde"
 },
 "access_token": "e61467e3845e8a66f7453dc55ea3fc445d1b879a6f96ebe7b243bad
beae04f63"
 }
 200
 {
 "code": 200,
 "message": "The user has been successfully updated",
 "user": {
"_id": "51552cd7fded0807c4000017",
 "uid": "abcde",
 "profile": null
 }
 }
#

Deleting Users

You may want to permanently disconnect a user from Validic, for example, if the person is no longer employed at an organization. You may delete a user by making a delete call to the user’s ID provided during provisioning or the uid you provided during provisioning. Deleting a user follows REST standards. Note that the Organization access token must be passed for authentication.

Deleting a user by specifying the user’s Validic ID:

Example
DELETE https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{USER_ID}.json
DELETE https://api.validic.com/v1/organizations/5176906c6deddac02c000001/user
s/51552cd7fded0807c4000017.json
 -H 'Content-Type: application/json'
 {
 "access_token": "e61467e3845e8a66f7453dc55ea3fc445d1b879a6f96ebe7b243bad
beae04f63"
 }
 200
 {
 "code": 200,
 "message": "Ok"
 }

In case you do not have the User’s Validic ID, you may also delete a user using the uid you used to provision the user.

Deleting a user by specifying the uid provided when user was provisioned:

Example
DELETE https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users.json
DELETE https://api.validic.com/v1/organizations/5176906c6deddac02c000001/users.json
 -H 'Content-Type: application/json'
 {
 "access_token": "e61467e3845e8a66f7453dc55ea3fc445d1b879a6f96ebe7b243bad
beae04f63",
"uid": "123467890"
 }
 200
 {
 "code": 200,
 "message": "Ok"
 }

Alternatively, you may pass the access token as a URL parameter instead.

#

Suspending Users

You may want to suspend a user from Validic, for example, if the person is similarly suspended in your organization. A suspended user will not have access to your Validic Marketplace. Additionally, Validic will discontinue syncing data from their applications. Suspending a user follows REST standards. Note that the Organization access token must be passed for authentication.

Example
PUT https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{USER_ID}
PUT https://api.validic.com/v1/organizations/5176906c6deddac02c000001/users/51
552cd7fded0807c4000017.json
 -H 'Content-Type: application/json'
 {
 "suspend": "1",
 "access_token": "e61467e3845e8a66f7453dc55ea3fc445d1b879a6f96ebe7b243bad
beae04f63"
 }
 200
 {
 "code": 200,
 "message": "The user has been suspended successfully"
 }

You may unsuspend a user by setting suspend to 0.

#

User Credentials

All Users in Validic have credentials which can be accessed with a /me call. Due to HIPAA de-identification standards, only non-identifiable data is available.

Example
GET https://api.validic.com/v1/me.json?authentication_token={USER_ACCESS_TOKEN}
GET https://api.validic.com/v1/me.json?authentication_token=d18397e3845e8b66f
7453dc55ea3fc445d1b879a6f96ebe7b243badabce08c98
 200
 {
 "me": {
 "_id": "51552cd7fded0807c4000017"
 }
 }
#

User Profile

A profile contains information about a User including connected applications. Due to HIPAA de-identification standards, only non-identifiable data is available.

Example
GET https://api.validic.com/v1/profile.json?authentication_token={USER_ACCESS_TOKEN}
GET https://api.validic.com/v1/profile.json?authentication_token=dbcd72a51f1b4a7
8450791a7f5c832b7a0876ffd03703bcce5d3a62e47c37c78
 200
 {
 "profile": {
 "uid": "123467890",
 "_id": "51552cd7fded0807c4000017",
 "gender": "M",
 "location": "NC",
 "country": "United States",
 "birth_year": "1973",
 "height": 167.5,
 "weight": 83.9146,
 "applications": []
 }
 }
Example
POST https://api.validic.com/v1/profile.json
POST https://api.validic.com/v1/profile.json
 -H 'Content-Type: application/json'
 {
 "profile": {
 "gender": "M",
 "location": "NC",
 "country": "United States",
 "birth_year": "1973",
 "height": 167.5,
 "weight": 83.9146
 },
 "authentication_token": "d18397e3845e8b66f7453dc55ea3fc445d1b879a6f96ebe7
b243badabce08c98"
 }
 201
 {
 "code": 201,
 "message": "Ok",
 "profile": {
 "uid": "123467890",
 "_id": "51552cd7fded0807c4000017",
 "gender": "M",
 "location": "NC",
 "country": "United States",
 "birth_year": "1973",
 "height": 167.5,
 "weight": 83.9146,
 "applications": []
 }
 }

Params

Field
Type
Description
uid
String
User’s ID from the provisioning application
_id
String
User’s Validic ID
gender
String
Either M or F
location
String
2-letter State abbreviation in United States, postal code or City, State for other countries
country
String
The user’s Country of residence (e.g., “United States,” “Canada,” etc.)
birth_year
String
User’s year of birth
height
Double
User’s most current height in cm
weight
Double
User’s most current weight in kg
applications
String
A list of connected 3rd party applications (stored in a hash)
#

Sync Apps & Devices

#

Validic Standard HTML 5 Marketplace Deployment

The Validic Marketplace is the place where users go to browse and connect health apps and devices so their data will be available to your system. The simplest way to integrate the Validic Marketplace is to simply have a link in your system which opens up a new window with the Validic Standard HTML5 Marketplace. The Validic Marketplace handles all API app connections and callbacks.

To render the Validic standard marketplace to your users you will use your Organization’s ID and the User Access Token created when you provisioned the user. You will create a button or link in your system that looks like this:

sync

For a demonstration of this functionality and rendering of the standard HTML5 Marketplace, click the button below:

#

Customizing Your Own App Marketplace

 

Our Enterprise customers may also design and create a custom implementation of your own Validic App Marketplace. To deploy the marketplace, you will need your Organization’s ID, your Organization’s Access Token, and the User Access Token created when you provisioned the user.

The Validic App Marketplace is specific to each user, with a listing of all apps and its appropriate sync, refresh, and unsync URLs. To sync an application, simply use the sync
URL for the app which will bring the user to the app’s authorization page. Similarly, to unsync the app, simply pass on the unsync url for the app. The refresh URL on the other hand acts as a trigger to fetch on demand that user’s app data from the source.

The unsync and refresh URLs are only available once the app has been synced.

Example
GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/apps.json?authentication_token={USER_ACCESS_TOKEN}&access_token={ORGANIZATION_ACCESS_TOKEN}
GET https://api.validic.com/v1/organizations/5176906c6deddac02c000001/apps.jso
n?authentication_token=d18397e3845e8b66f7453dc55ea3fc445d1b879a6f96ebe7b2
43badabce08c98&access_token=e61467e3845e8a66f7453dc55ea3fc445d1b879a6f9
6ebe7b243badbeae04f63
 200
 {
 summary": {
 ...
 }, "apps": [
 {
 "name": "Fitbit",
 "sync_url": "https://app.validic.com/organizations/5176906c6deddac02c00000
1/auth/fitbit?user_token=d18397e3845e8b66f7453dc55ea3fc445d1b879a6f96ebe7b
243badabce08c98&format_redirect=json",
 "unsync_url": "https://app.validic.com/organizations/5176906c6deddac02c000
001/unsync/fitbit?user_token=d18397e3845e8b66f7453dc55ea3fc445d1b879a6f96e
be7b243badabce08c98&format_redirect=json",
"refresh_url": "https://app.validic.com/organizations/5176906c6deddac02c000
001/refresh/fitbit?user_token=d18397e3845e8b66f7453dc55ea3fc445d1b879a6f96e
be7b243badabce08c98&format_redirect=json",
 "download_link": "http://www.fitbit.com/product/mobile/iphone",
 "excerpt": "Fitbit will help you lead a healthier, more active life. The Fitbit fam
ily motivates you to stay active, live better and reach your goals. ",
 "extra_excerpt": "Let's make fitness a fun, achievable part of everyday life. Our
 products track your health and fitness, then sync wirelessly to offer insight and enco
uragement whether you're online or on the go. So get ready to go farther.",
 "subname": "fitbit",
 "kind": [
 "fitness",
 "nutrition",
 "walking",
 "running",
 "jogging",
 "swimming",
 "hiking",
 "elliptical",
 "ballet",
 "bowling",
 "bicycling",
 "horseback_riding",
 "gardening",
 "yoga",
 "calorie_tracking",
 "meal_tracking"
 ],
 "logo_url": "/assets/appicons/fitbit-icon.jpg",
 "platform_types": [
 "Web",
 "iOS",
 "Android",
 "BlackBerry"
 ],
 "synced": true,
 "last_sync": "2013-03-10T00:00:00+00:00"
 },
 ...
 ]
 }

Params

Field
Type
Description
name
String
The display name for the app
sync_url
String
URI for redirecting the user to the app’s authorization page to sync the app
unsync_url
String
URI for unsyncing the app
refresh_url
String
URI for refreshing the user’s app data
download_link
String
URI for downloading the app software
excerpt
String
Short description of the app
extra_excerpt
String
Long description of the app
subname
String
Source filter name for the app
kind
Array
Kinds of activities supported by the app
logo_url
String
Relative path of the image icon for the app. Prepend with https://app.validic.com
platform_types
Array
Platforms where app is available
synced
Boolean
Synced status of the app
last_sync
String
Timestamp when the app was last synced by user

#
Controlling Sync, Refresh and Unsync redirect behavior

For custom marketplace implementations, additional control over the behavior of a sync, unsync, or refresh call may be added through a redirect_uri parameter

Example
GET https://app.validic.com/organizations/{ORGANIZATION_ID}/auth/{SOURCE}?user_token={USER_ACCESS_TOKEN}&format_redirect=json&redirect_uri={URI}
GET https://app.validic.com/organizations/5176906c6deddac02c000001/auth/fitbit?
user_token=d18397e3845e8b66f7453dc55ea3fc445d1b879a6f96ebe7b243badabce0
8c98&format_redirect=json&redirect_uri=http://google.co

This will redirect the user the specified resource after a successful request.

#
Additional Display of Supported Devices

You may additionally display supported devices for each app by adding an expanded filter and setting it to 1.

Example
GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/apps.json?authentication_token={USER_ACCESS_TOKEN}&access_token={ORGANIZATION_ACCESS_TOKEN}&expanded=1
GET https://api.validic.com/v1/organizations/5176906c6deddac02c000001/apps.jso
n?authentication_token=d18397e3845e8b66f7453dc55ea3fc445d1b879a6f96ebe7b2
43badabce08c98&access_token=e61467e3845e8a66f7453dc55ea3fc445d1b879a6f9
6ebe7b243badbeae04f63&expanded=1
 200
 {
 summary": {
 ...
 }, "apps": [
 {
 "name": "Fitbit",
 "sync_url": "https://app.validic.com/organizations/5176906c6deddac02c00000
1/auth/fitbit?user_token=d18397e3845e8b66f7453dc55ea3fc445d1b879a6f96ebe7b
243badabce08c98&format_redirect=json",
 "unsync_url": "https://app.validic.com/organizations/5176906c6deddac02c000
001/unsync/fitbit?user_token=d18397e3845e8b66f7453dc55ea3fc445d1b879a6f96e
be7b243badabce08c98&format_redirect=json",
"refresh_url": "https://app.validic.com/organizations/5176906c6deddac02c000
001/refresh/fitbit?user_token=d18397e3845e8b66f7453dc55ea3fc445d1b879a6f96e
be7b243badabce08c98&format_redirect=json",
 "download_link": "http://www.fitbit.com/product/mobile/iphone",
 "excerpt": "Fitbit will help you lead a healthier, more active life. The Fitbit fam
ily motivates you to stay active, live better and reach your goals. ",
 "extra_excerpt": "Let's make fitness a fun, achievable part of everyday life. Our
 products track your health and fitness, then sync wirelessly to offer insight and enco
uragement whether you're online or on the go. So get ready to go farther.",
 "subname": "fitbit",
 "kind": [
 "fitness",
 "nutrition",
 "walking",
 "running",
 "jogging",
 "swimming",
 "hiking",
 "elliptical",
 "ballet",
 "bowling",
 "bicycling",
 "horseback_riding",
 "gardening",
 "yoga",
 "calorie_tracking",
 "meal_tracking"
 ],
 "logo_url": "/assets/appicons/fitbit-icon.jpg",
 "platform_types": [
 "Web",
 "iOS",
 "Android",
 "BlackBerry"
 ],
 "synced": true,
 "last_sync": "2013-03-10T00:00:00+00:00",
 + "items_supported": [
 + {
 + "name": "Fitbit Aria Scale",
 + "type": "In-home Device",
"description": "Aria™ tracks your weight, body fat percentage, and BMI,
painting a picture of your long-term progress. It wirelessly syncs your stats with onli
ne graph and mobile tools that help you stay motivated and on track. When you're in
 control, stepping on the scale feels good.",
 + "excerpt": "Wi-fi Smart Scale",
 + "resource_url": "http://www.fitbit.com/aria",
 + "data_objects": [
 + "weight",
 + "biometrics"
 + ],
 + "kind": [
 + "weight",
 + "biometrics"
 + ],
 + "image_url": "http://static6.fitbit.com/simple.b-dis-png.h9e38e9e1e5f4be
5c341edc1ef6dd77ac.pack?items=%2Fcontent%2Fassets%2Fonezip%2Fimages%2
Fproducts%2Faria%2FAria_side_angle_white_large.png",
 + "discontinued": false
 + },
 + ...
 + ]
 },
 ...
 ]
 }

Params

Field
Type
Description
name
String
The display name for the device
type
String
Type of device
description
String
Long description for the device
excerpt
String
Short description for the device
resource_url
String
URI for vendor device information
data_objects
Array
API Data Objects supported by device
kind
Array
Kinds of activities supported by device
image_url
String
URI for the image icon for the device
discontinued
Boolean
Market availability status of the device

For more information regarding data filters, please visit the Filters section of our documentation.

#

Authenticate

Once your users choose to sync a device in the Validic App Marketplace they will be taken through an authentication process. This is the second of two ID exchange mechanisms, or handshakes, that enables your end user data to remain de-identified in the Validic system and complies with HIPAA and Safe Harbor certification standards. An example of the user experience workflow can be followed below.

User Chooses to Sync a Device in the App Marketplace:

auth1

User signs in to, or creates, account:

auth2

User permissions the use of their data to your organization:

auth3

Note, Validic will apply for credentials and branding on your behalf during the implementation process so that your users have a consistent and cohesive user experience while Validic operates in the background unbeknownst to your end user.

User is redirected to the Validic Standard HTML5 App Marketplace or our enterprise customers deploying the custom marketplace may choose to redirect their end user to another location within their application:

auth4

You may also walk yourself through a live demo of this process via the Validic ACME marketplace. Click the button below to get started.

#

Data Objects

Now that your users have been provisioned, they have navigated to the App Marketplace and chosen to sync a device, authorized the use of that data to you, it is time to begin accessing data available to you via the Validic system. The following sections contain information regarding the end points, or objects as Validic refers to them, available for you to call for from the Validic API as well as the data parameter fields contained within each of those object types. Additionally, we walk you through all available Validic API calls.

#

Fitness Activities

Fitness records return data for activities that are undertaken with the express purpose of exercising. These activities have a defined duration (time, distance, elevation, etc.). Activities are stored in the items array structure as follows:

Example
GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{USER_ID}/fitness.json?access_token={ORGANIZATION_ACCESS_TOKEN}
GET https://api.validic.com/v1/organizations/5176906c6deddac02c000001/users/51
552cd7fded0807c4000017/fitness.json?access_token=e7ba1f04e88f25d399a91c8cb
cd72300e01309e96b7725e40b49cd1effaa5deb
 200
 {
 "summary": {
 ...
 }, "fitness": [
 {
 "_id": "51552cd7fded0807c400001f",
 "timestamp": "2013-03-10T07:12:16+00:00",
 "utc_offset": "+00:00",
 "type": "Walking",
 "intensity": "low",
 "start_time": "2013-03-10T07:12:16+00:00",
 "distance": 2600,
 "duration": 2460,
 "calories": 350,
 "source": "sample_app",
 "source_name": "Sample App",
 "last_updated": "2013-03-10T07:12:16+00:00"
 }
 ]
 }

Params

Field
Type
Description
timestamp
String
Timestamp for the measurement set
utc_offset
String
Timezone information for the measurement set
type
String
Sample types of activities: Running, Cycling, Mountain Biking, Walking, Hiking, Downhill Skiing, Cross-country Skiing, Snowboarding, Skating, Swimming, Rowing, Elliptical, Other. Activities vary from source to source and are returned as provided by source.
intensity
String
String Subjective intensity with which an activity was performed. Examples are: low, medium, high. Returned as provided by source.
start_time
String
String Starting time for the activity. Preferred format is an ISO 8601 timestamp (YYYY-MM-DDThh:mm:ssZ, e.g., 2013-03-10T07:12:16-05:00).
distance
Double
Total distance for the activity in meters
duration
Double
Duration of the activity in seconds
calories
Double
Total calories burned for the activity
source
String
The short name of the application that recorded the activity
source_name
String
The display name of the application that recorded the activity
last_updated
String
Date and time when the measurement set was last updated
activity_id
String
Unique identifier of the activity (required for POST requests)

For more information regarding the difference between Fitness and Routine data types, please reference our Knowledge Base Article.

#

Routine Activities

Activities that occur regularly throughout the day, without the specific goal of exercise, for example calories burned and consumed, steps taken, stairs climbed. These activities are aggregate throughout the day. Activities are stored in the items array structure as follows:

Example
GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{USER_ID}/routine.json?access_token={ORGANIZATION_ACCESS_TOKEN}
GET https://api.validic.com/v1/organizations/5176906c6deddac02c000001/users/51
552cd7fded0807c4000017/routine.json?access_token=e7ba1f04e88f25d399a91c8cb
cd72300e01309e96b7725e40b49cd1effaa5deb
 200
 {
 "summary": {
 ...
 }, "routine": [
 {
 "_id": "51552cdbfded0807c4000062",
 "timestamp": "2013-03-10T07:12:16+00:00",
 "utc_offset": "+00:00",
 "steps": 9355,
 "distance": 7290.33,
 "floors": 23,
 "elevation": 3.4,
 "calories_burned": 2874,
 "source": "sample_app",
 "source_name": "Sample App",
 "last_updated": "2013-03-10T07:12:16+00:00"
 }
 ]
 }

Params

Field
Type
Description
timestamp
String
Timestamp for the measurement set
utc_offset
String
Timezone information for the measurement set
steps
Double
The value of the measured quantity
distance
Double
The value of the measured quantity in meters
floors
Double
The value of the measured quantity
elevation
Double
The value of the measured quantity in meters
calories_burned
Double
The value of the measured quantity
source
String
The short name of the application that recorded the activity
source_name
String
The display name of the application that recorded the activity
last_updated
String
Date and time when the measurement set was last updated
activity_id
String
Unique identifier of the activity (required for POST requests)

For more information regarding the difference between Fitness and Routine data types, please reference our Knowledge Base Article.

#

Nutrition

Activities related to calorie intake and consumption and nutritional information (such as fat, protein, carbohydrates, sodium, etc.).

Example
GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{USER_ID}/nutrition.json?access_token={ORGANIZATION_ACCESS_TOKEN}
GET https://api.validic.com/v1/organizations/5176906c6deddac02c000001/users/51
552cd7fded0807c4000017/nutrition.json?access_token=e7ba1f04e88f25d399a91c8c
bcd72300e01309e96b7725e40b49cd1effaa5deb
 200
 {
 "summary": {
 ...
 }, "nutrition": [
 {
 "_id": "51552cd9fded0807c4000043",
 "timestamp": "2013-03-10T07:12:16+00:00",
 "utc_offset": "+00:00",
 "calories": 865,
 "carbohydrates": 121,
 "fat": 31,
 "fiber": 9,
 "protein": 21,
 "sodium": 1129,
 "water": 14,
 "meal": "lunch",
 "source": "sample_app",
 "source_name": "Sample App",
 "last_updated": "2013-03-10T07:12:16+00:00"
 }
 ]
 }

Params

Field
Type
Description
timestamp
String
Timestamp for the measurement set
utc_offset
String
Timezone information for the measurement set
calories
Double
The value of the measured quantity
carbohydrates
Double
The value of the measured quantity in g
fat
Double
The value of the measured quantity in g
fiber
Double
The value of the measured quantity in g
protein
Double
The value of the measured quantity in g
sodium
Double
The value of the measured quantity in mg
water
Double
The value of the measured quantity in fl oz
meal
String
The meal, for example: pizza, Coke, chicken breast, other, unspecified
source
String
The short name of the application that recorded the activity
source_name
String
The display name of the application that recorded the activity
last_updated
String
Date and time when the measurement set was last updated
entry_id
String
Unique identifier of the entry (required for POST requests)
#

Sleep

Measurements related to the length of time spent in various sleep cycles, as well as number of times woken during the night.

Example
GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{USER_ID}/sleep.json?access_token={ORGANIZATION_ACCESS_TOKEN}
GET https://api.validic.com/v1/organizations/5176906c6deddac02c000001/users/51
552cd7fded0807c4000017/sleep.json?access_token=e7ba1f04e88f25d399a91c8cbc
d72300e01309e96b7725e40b49cd1effaa5deb
 200
 {
 "summary": {
 ...
 }, "sleep": [
 {
 "_id": "51552cddfded0807c400008b",
 "timestamp": "2013-03-10T07:12:16+00:00",
 "utc_offset": "+00:00",
 "awake": 34,
 "deep": 234,
 "light": 94,
 "rem": 115,
 "times_woken": 4,
 "total_sleep": 477,
 "source": "sample_app",
 "source_name": "Sample App",
 "last_updated": "2013-03-10T07:12:16+00:00"
 }
 ]
 }

Params

Field
Type
Description
timestamp
String
Timestamp for the measurement set
utc_offset
String
Timezone information for the measurement set
total_sleep
Double
The value of the measured quantity in seconds
awake
Double
The value of the measured quantity in seconds
deep
Double
The value of the measured quantity in seconds
light
Double
The value of the measured quantity in seconds
rem
Double
The value of the measured quantity in seconds
times_woken
Double
The value of the measured quantity
source
String
The short name of the application that recorded the activity
source_name
String
The display name of the application that recorded the activity
last_updated
String
Date and time when the measurement set was last updated
activity_id
String
Unique identifier of the activity (required for POST requests)
#

Weight

Measurements associated with a user’s weight and body mass.

Example
GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{USER_ID}/weight.json?access_token={ORGANIZATION_ACCESS_TOKEN}
GET https://api.validic.com/v1/organizations/5176906c6deddac02c000001/users/5
552cd7fded0807c4000017/weight.json?access_token=e7ba1f04e88f25d399a91c8cb
cd72300e01309e96b7725e40b49cd1effaa5deb
 200
 {
 "summary": {
 ...
 }, "weight": [
 {
 "_id": "51552cdcfded0807c4000075",
 "timestamp": "2013-03-10T07:12:16+00:00",
 "utc_offset": "+00:00",
 "weight": 83.9146,
 "height": 167.5,
 "free_mass": 83.9146,
 "fat_percent": 21.4,
 "mass_weight": 83.9146,
 "bmi": 29.9,
"source": "sample_app",
 "source_name": "Sample App",
 "last_updated": "2013-03-10T07:12:16+00:00"
 }
 ]
 }

Params

Field
Type
Description
timestamp
String
Timestamp for the measurement set
utc_offset
String
Timezone information for the measurement set
weight
Double
The value of the measured quantity in kg
height
Double
The value of the measured quantity in cm
free_mass
Double
The value of the measured quantity in kg
fat_percent
Double
The value of the measured quantity
mass_weight
Double
The value of the measured quantity in kg
bmi
Double
The value of the measured quantity
source
String
The short name of the application that recorded the activity
source_name
String
The display name of the application that recorded the activity
last_updated
String
Date and time when the measurement set was last updated
data_id
String
Unique identifier of the measurement (required for POST requests)
#

Diabetes Measurements

Diabetes Measurements are comprised of a user’s blood glucose and hormone levels related to diabetes treatment and management.

Example
GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{USER_ID}/diabetes.json?access_token={ORGANIZATION_ACCESS_TOKEN}
GET https://api.validic.com/v1/organizations/5176906c6deddac02c000001/users/5
552cd7fded0807c4000017/diabetes.json?access_token=e7ba1f04e88f25d399a91c8c
bcd72300e01309e96b7725e40b49cd1effaa5deb
 200
 {
 "summary": {
 ...
 }, "diabetes": [
 {
 "_id": "51552cd6fded0807c4000007",
 "timestamp": "2013-03-10T07:12:16+00:00",
 "utc_offset": "+00:00",
 "c_peptide": 0.6,
 "fasting_plasma_glucose_test": 95,
 "hba1c": 4.8,
 "insulin": 460,
 "oral_glucose_tolerance_test": 137,
 "random_plasma_glucose_test": 256,
 "triglyceride": 128,
 "blood_glucose": 120,
"source": "sample_app",
 "source_name": "Sample App",
 "last_updated": "2013-03-10T07:12:16+00:00"
 }
 ]
 }

Params

Field
Type
Description
timestamp
String
Timestamp for the measurement set
utc_offset
String
Timezone information for the measurement set
c_peptide
Double
The value of the measured quantity in ng/mL
fasting_plasma_glucose_test
Double
The value of the measured quantity in mg/dL
hba1c
Double
The value of the measured quantity in %
insulin
Double
The value of the measured quantity in U
oral_glucose_tolerance_test
Double
The value of the measured quantity in mg/dL
random_plasma_glucose_test
Double
The value of the measured quantity in mg/dL
triglyceride
Double
The value of the measured quantity in mg/dL
blood_glucose
Double
The value of the measured quantity in mg/dL
source
String
The short name of the application that recorded the activity
source_name
String
The display name of the application that recorded the activity
last_updated
String
Date and time when the measurement set was last updated
activity_id
String
Unique identifier of the measurement (required for POST requests)
#

Biometric Measurements

Biometric Measurements are comprised of a user’s biometric health data such as blood pressure, cholesterol, heart rate, and blood and hormone levels.

Example
GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{USER_ID}/biometrics.json?access_token={ORGANIZATION_ACCESS_TOKEN}
GET https://api.validic.com/v1/organizations/5176906c6deddac02c000001/users/5
552cd7fded0807c4000017/biometrics.json?access_token=e7ba1f04e88f25d399a91c
8cbcd72300e01309e96b7725e40b49cd1effaa5deb
 200
 {
 "summary": {
 ...
 }, "biometrics": [
{
 "_id": "51552cdcfded0807c4000075",
 "timestamp": "2013-03-10T07:12:16+00:00",
 "utc_offset": "+00:00",
 "blood_calcium": 9.2,
 "blood_chromium": 1.32,
 "blood_folic_acid": 8.1,
 "blood_magnesium": 1.89,
 "blood_potassium": 3.9,
 "blood_sodium": 137.8,
 "blood_vitamin_b12": 612,
 "blood_zinc": 93,
 "creatine_kinase": 87,
 "crp": 0,
 "diastolic": 73,
 "ferritin": 189,
 "hdl": 44,
 "hscrp": 0.3,
 "il6": 6.4,
 "ldl": 156,
 "resting_heartrate": 74,
 "systolic": 122,
 "testosterone": 457,
 "total_cholesterol": 208,
 "tsh": 0.6,
 "uric_acid": 4.2,
 "vitamin_d": 54.8,
 "white_cell_count": 7453,
 "spo2": 96,
 "temperature": 37,
 "source": "sample_app",
 "source_name": "Sample App",
 "last_updated": "2013-03-10T07:12:16+00:00"
 }
 ]
 }

Params

Field
Type
Description
timestamp
String
Timestamp for the measurement set
utc_offset
String
Timezone information for the measurement set
blood_calcium
Double
The value of the measured quantity in mg/dL
blood_chromium
Double
The value of the measured quantity in µg/L
blood_folic_acid
Double
The value of the measured quantity in ng/mL
blood_magnesium
Double
The value of the measured quantity in mg/dL
blood_potassium
Double
The value of the measured quantity in mEq/L
blood_sodium
Double
The value of the measured quantity in mEq/L
blood_vitamin_b12
Double
The value of the measured quantity in pg/mL
blood_zinc
Double
The value of the measured quantity in µg/dL
creatine_kinase
Double
The value of the measured quantity in U/L
crp
Double
The value of the measured quantity in mg/L
diastolic
Double
The value of the measured quantity in mmHg
ferritin
Double
The value of the measured quantity in ng/mL
hdl
Double
The value of the measured quantity in mg/dL
hscrp
Double
The value of the measured quantity in mg/L
il6
Double
The value of the measured quantity in pg/mL
ldl
Double
The value of the measured quantity in mg/dL
resting_heartrate
Double
The value of the measured quantity in bpm
systolic
Double
The value of the measured quantity in mmHg
testosterone
Double
The value of the measured quantity in ng/dL
total_cholesterol
Double
The value of the measured quantity in mg/dL
tsh
Double
The value of the measured quantity in mIU/L
uric_acid
Double
The value of the measured quantity in mg/dL
vitamin_d
Double
The value of the measured quantity in ng/mL
white_cell_count
Double
The value of the measured quantity in cells/µL
spo2
Double
The value of the measured quantity in %
temperature
Double
The value of the measured quantity in Celsius
source
String
The short name of the application that recorded the activity
source_name
String
The display name of the application that recorded the activity
last_updated
String
Date and time when the measurement set was last updated
data_id
String
Unique identifier of the measurement (required for POST requests)
#

Tobacco Cessation

Measurements associated with a user going through a tobacco cessation program. These values are aggregated throughout the day.

Example
GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{USER_ID}/tobacco_cessation.json?access_token={ORGANIZATION_ACCESS_TOKEN}
GET https://api.validic.com/v1/organizations/5176906c6deddac02c000001/users/5
552cd7fded0807c4000017/tobacco_cessation.json?access_token=e7ba1f04e88f25d3
99a91c8cbcd72300e01309e96b7725e40b49cd1effaa5deb
 200
 {
 "summary": {
 ...
 }, "tobacco_cessation": [
 {
 "_id": "51552cd8fded0807c4000031",
 "timestamp": "2013-03-10T07:12:16+00:00",
 "utc_offset": "+00:00",
 "cigarettes_allowed": 9,
 "cigarettes_smoked": 2,
 "cravings": 12,
 "last_smoked": "2013-03-10T05:55:36+00:00",
 "source": "sample_app",
 "source_name": "Sample App",
 "last_updated": "2013-03-10T07:12:16+00:00"
 }
 ]
 }

Params

Field
Type
Description
timestamp
String
Timestamp for the measurement set
utc_offset
String
Timezone information for the measurement set
cigarettes_allowed
Double
Number of cigarettes budgeted for a given day
cigarettes_smoked
Double
Number of cigarettes smoked for a given day
cravings
Double
Number of cravings a user has for a given day
last_smoked
String
Timestamp for the last cigarette smoked
source
String
The short name of the application that recorded the activity
source_name
String
The display name of the application that recorded the activity
last_updated
String
Date and time when the measurement set was last updated
#

Data Retrieval

Once data is available in the Validic system, you may begin retrieving the data through the following API calls.

#

Summary Object

All GET responses contain a summary object with information about the request. For the sake of brevity, we will not duplicate the summary object elsewhere in the examples. This functionality should be assumed for all GET responses.

A sample summary object:

200
 {
 "summary": {
 "status": 200,
 "message": "OK",
 "results": 3,
 "start_date": "2013-03-27T00:00:00+00:00",
 "end_date": "2013-03-27T23:59:59+00:00",
 "offset": 0,
 "limit": 100,
 "previous": null,
 "next": null,
 "params": {
 "start_date": null,
"end_date": null,
 "offset": null,
 "limit": null
 }
 }
 }

Summary Params

Field
Type
Description
status
Integer
The HTTP header response code returned
message
String
The HTTP header response code message returned
results
Integer
The total number of records returned across all pages.
start_date
String
The optional start timestamp of the activities you wish to pull in the ISO 8601 standard format”YYYY-MM-DDThh:mm:ssZ” (e.g., “2013-03-28T14:32:00+00:00″ where “+00:00″ is the UTC offset). Defaults to yesterday’s start of day (e.g., “2013-03-27T00:00:00+00:00″). May be set in GET request (e.g., &start_date=2013-03-28T14:32:00+00:00).
end_date
String
The optional end timestamp of the activities you wish to pull in the ISO 8601 standard format”YYYY-MM-DDThh:mm:ssZ” (e.g., “2013-03-28T14:32:00+00:00″ where “+00:00″ is the UTC offset). Defaults to yesterday’s end of day (e.g., “2013-03-27T23:59:59+00:00″). May be set in GET request (e.g., &end_date=2013-03-28T14:32:00+00:00).
offset
Integer
Record offset for retrieving paginated records. Default is 0. May be set in GET requests
limit
Integer
Limit of records returned per page. Default is 100. Must be an integer between 1 and 200. May be set in GET request.
previous
String
The URI of the previous page in the feed.
next
String
The URI of the next page in the feed.
#

User Data

The following call in this example will return all fitness data from the previous day
through the time of the call today for the user specified (USER_ID) in the call:

GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{USER_ID}/fitness.json?authentication_token={USER_ACCESS_TOKEN}

or, using a shorthand version:

GET https://api.validic.com/v1/fitness.json?authentication_token={USER_ACCESS_TOKEN}
#

 

Population Data

The following call in this example will return all fitness data from the previous day through the time of the call today for the organization specified (ORGANIZATION_ID) in the call:

GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/fitness.json?access_token={ORGANIZATION_ACCESS_TOKEN}
#

 

Accessing the Latest Information

By default, bulk data calls are ordered by the timestamp of an individual activity. The challenge here is that if an individual was on vacation for a week and syncs a device upon returning, how will you know of data that occurred a week ago but only just made it into the Validic system?

The latest endpoint gives you the latest data recorded and updated in Validic, regardless of when the activity occurred. For example, if you pulled and processed Validic data at 4:00 a.m., and then you want to update your system again at 8:00 a.m., you can specify to only receive new and updated data that was added to our system between 4 a.m. and 8 a.m. by appending a timestamp with the start_date and end_date.

The following returns the most recently recorded/updated fitness activities for all users of an Organization that were recorded between start_date and end_date:

Example
GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/fitness/latest.json?start_date={TIMESTAMP}&end_date={TIMESTAMP}&access_token={ORGANIZATION_ACCESS_TOKEN}
GET https://api.validic.com/v1/organizations/5176906c6deddac02c000001/fitness/l
atest.json?start_date=2013-06-01T04:00:00-04:00&access_token=e61467e3845e8a
66f7453dc55ea3fc445d1b879a6f96ebe7b243badbeae04f63
 200
 {
 "summary": {
 ...
 },
 "fitness": [{
 "_id": "5176903b6dedda539c000001",
 "timestamp": "2013-06-01T04:07:01+00:00",
 "utc_offset": "-05:00"
 "type": "Running",
 "intensity": "high",
 "start_time": null,
 "distance": 2242.74,
 "duration": 1683,
 "source": "sample_app",
 "source_name": "Sample App",
 "last_upd

Latest.json Example:
A best practices implementation of /routine/latest.json calls would look something like this:

/routine/latest.json?start_date=2014-03-09T10:00:00Z&end_date=2014-03-09T10:04:59Z /
routine/latest.json?start_date=2014-03-09T10:05:00Z&end_date=2014-03-09T10:09:59Z /r
outine/latest.json?start_date=2014-03-09T10:10:00Z&end_date=2014-03-09T10:14:59Z /ro
utine/latest.json?start_date=2014-03-09T10:15:00Z&end_date=2014-03-09T10:19:59Z /rou
tine/latest.json?start_date=2014-03-09T10:20:00Z&end_date=2014-03-09T10:24:59Z /rout
ine/latest.json?start_date=2014-03-09T10:25:00Z&end_date=2014-03-09T10:29:59Z /routi
ne/latest.json?start_date=2014-03-09T10:30:00Z&end_date=2014-03-09T10:34:59Z /routin
e/latest.json?start_date=2014-03-09T10:35:00Z&end_date=2014-03-09T10:39:59Z /routine
/latest.json?start_date=2014-03-09T10:40:00Z&end_date=2014-03-09T10:44:59Z /routine/
latest.json?start_date=2014-03-09T10:45:00Z&end_date=2014-03-09T10:49:59Z 

The benefit of this series of calls is that you ping Validic every five minutes (could be every 2 minutes, every 10 minutes, etc.) and you receive any updates that have been made for your organization in the specified time range. So for example, if a user doesn’t sync her Fitbit for 5 days and then syncs it on 2014-03- 09T10:47:39Z, Validic will return all of her Fitbit activities from the last 5 days in the last call in the series above.

Latest.json vs Push Notifications
Please refer to our Knowledge Base Article for further information regarding discussion around leveraging the latest.json call vs push notification service and user level data calls.

#

Push Notification Service

Validic provides our Enterprise customers with the ability to register for Push Notification service for near-real time data update notifications and optimal resource use. Enterprise customers may have one or more Push Notification URLs set. To do so, contact us at support@validic.com for setting up Push Notification service for your account.

Once set, Validic will begin pushing data to your Push Notification URL via a POST request:

Each Push Notification sent out may include multiple items corresponding to activities that are now available for retrieval from the Validic API. Each item inside a Push Notification includes the necessary elements for you to construct an API call to retrieve a particular piece of activity data.

Example
POST http://{YOUR_PUSH_NOTICATION_URL}
POST https://yoursite.com/notification
 {
 "data": [{
 "_id": "51552cd7fded0807c4000017",
 "activity_type": "fitness",
 "activity_date": "2013-10-08T19:07:01+00:00",
 "source": "sample_app"
 },
 ...
 ]
 }

Params

Field
Type
Description
_id
String
Validic ID of the user
activity_type
String
Type of activity data corresponding to one Validic API endpoint
activity_date
String
Timestamp for the measurement set
source
String
The short name of the application that recorded the activity

Upon receipt of a Push Notification, you may begin fetching new data from the API through a GET Request using the data parameters from the Push Notification:

Example
GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{USER_ID}/{ACTIVITY_TYPE}.json?access_token={ORGANIZATION_ACCESS_TOKEN}&start_date={ACTIVITY_DATE}&end_date={ACTIVITY_DATE}&source={SOURCE}
GET https://api.validic.com/v1/organizations/5176906c6deddac02c000001/users/51
552cd7fded0807c4000017/fitness.json?access_token=e61467e3845e8a66f7453dc55
ea3fc445d1b879a6f96ebe7b243badbeae04f63&start_date=2013-10-08T19:07:01+0
0:00&end_date=2013-10-08T19:07:01+00:00&source=sample_app
 200
 {
 "summary": {
 ...
 },
 "fitness": [
 {
 "_id": "5176903b6dedda539c000001",
 "timestamp": "2013-10-08T19:07:01+00:00",
 "utc_offset": "-05:00",
 "type": "Running",
 "intensity": "high",
 "start_time": "2013-10-08T14:07:01-05:00",
 "distance": 2242.74,
 "duration": 1683,
 "source": "sample_app",
 "source_name": "Sample App",
 "last_updated": "2013-10-08T19:07:01+00:00"
 }
 ]
 }

When retrieving records based from items in Push Notifications, you may encounter empty responses and this is normal. Validic, by default, does not include in its normal API responses records where their values are all null and/or zero. However, should you have particular use for retrieving these records, you may pass either the allow_null or expanded parameters to your API calls and set them to 1.

Example
GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{_ID}/{ACTIVITY_TYPE}.json?access_token={ORGANIZATION_ACCESS_TOKEN}&start_date={ACTIVITY_DATE}&end_date={ACTIVITY_DATE}&source={SOURCE}&allow_null=1
GET https://api.validic.com/v1/organizations/5176906c6deddac02c000001/users/51
552cd7fded0807c4000017/fitness.json?access_token=e61467e3845e8a66f7453dc55
ea3fc445d1b879a6f96ebe7b243badbeae04f63&start_date=2013-10-08T19:07:01+0
0:00&end_date=2013-10-08T19:07:01+00:00&source=sample_app&allow_null=1
 200
 {
 "summary": {
 ...
 },
 "fitness": [
 {
 "_id": "5176903b6dedda539c000001",
 "timestamp": "2013-10-08T19:07:01+00:00",
 "utc_offset": "-05:00",
 "type": null,
 "intensity": null,
 "start_time": null,
 "distance": 0,
 "duration": 0,
 "source": "sample_app",
 "source_name": "Sample App",
 "last_updated": "2013-10-08T19:07:01+00:00"
 }
 ]
 }
Example
GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{_ID}/{ACTIVITY_TYPE}.json?access_token={ORGANIZATION_ACCESS_TOKEN}&start_date={ACTIVITY_DATE}&end_date={ACTIVITY_DATE}&source={SOURCE}&expanded=1
GET https://api.validic.com/v1/organizations/5176906c6deddac02c000001/users/51
552cd7fded0807c4000017/fitness.json?access_token=e61467e3845e8a66f7453dc55
ea3fc445d1b879a6f96ebe7b243badbeae04f63&start_date=2013-10-08T19:07:01+0
0:00&end_date=2013-10-08T19:07:01+00:00&source=sample_app&expanded=1
 200
 {
 "summary": {
 ...
 },
 "fitness": [
 {
 "_id": "5176903b6dedda539c000001",
 "timestamp": "2013-10-08T19:07:01+00:00",
 "utc_offset": "-05:00",
 "type": null,
 "intensity": null,
 "start_time": null,
 "distance": 0,
 "duration": 0,
 "source": "sample_app",
 "source_name": "Sample App",
 "last_updated": "2013-10-08T19:07:01+00:00",
 + "stars": 1, # extra field not included in Validic's standard response
 + "friend_id": 421 # extra field not included in Validic's standard response
 }
 ]
 }

#
Authenticating Push Notifications
The Validic API allows you to authenticate Push Notifications sent to your application via use of a Validic Signature. The Validic Signature is an HMAC based generated signature with the following components:

Params

Component
Description
Access Token
The Organization Access Token
Service Name
The name of the service. For Push Notifications, the service name is ‘notifications’
Validic-Timestamp
The timestamp of the Push Notification when it was sent
Application Secret
The designated Application Secret

To acquire your Application Secret, you may submit a request at support@validic.com.

#
Validating the Signature

To validate the Validic Signature, you may create your own signature using the components above and compare it with Validic Signature found in the Push Notification HTTP Headers. The following steps outline how to create your own signature:

POST https://yoursite.com/notification
 HEADERS
 Accept: */*
 Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
 Connection: close
 Content-Length: 258
 Content-Type: application/json
 Host: api.validic.com
 User-Agent: Faraday v0.8.8
 Validic-Signature: kgagP0HIFuoo+7nZkXQ4FOEaux8=
 Validic-Timestamp: 2014-03-11T21:58:25
 BODY
 {
 "data": [
 ...
 ]
 }

In this example, the Organization Access Token used is “e61467e3845e8a66f7453dc55ea3fc445d1b879a6f96ebe7b243badbeae04f63″ and Application Secret is “123ABC”.

  1. Concatenate your Organization Access Token, the service name (‘notification’) and Validic-Timestamp found in the Push Notification HTTP Headers. Do not use any characters to separate them. e61467e3845e8a66f7453dc55ea3fc445d1b879a6f96ebe7b243badbeae04f63notification2014-03-11T21:58:25
  2. Calculate the HMAC by using the SHA-1 hash algorithm.
  3. Apply Base64 encoding to the resulting string.
  4. Compare the resulting string to the Validic Signature. Your resulting string must match the Validic-Signature found in the Push Notification HTTP Headers.

For sample implementations on popular programming languages and scripting toolkits, you may visit https://services.timeanddate.com/api/doc/chap-auth.html for more information.

#

Comprehensive API Call List

The following section provides you with a comprehensive list of ALL Validic API calls a client might utilize.

  1. Basic User Provisioning
    Example
    POST https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users.json
     -H 'Content-Type: application/json'
     {
     "user": {
     "uid": "123467890"
     },
     "access_token": "ORGANIZATION_ACCESS_TOKEN"
     }
    
  2. User Provisioning with Profile Parameters
    Example
    POST https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users.json
     -H 'Content-Type: application/json'
     {
     "user": {
     "uid": "123467890",
     "profile": {
     "gender": "M",
     "location": "NC",
     "birth_year": "1973",
     "height": 167.5,
     "weight": 83.9146
     }
     },
     "access_token": "ORGANIZATION_ACCESS_TOKEN"
     }
    
  3. Update User
    Example
    PUT https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{USER_ID}.json
     -H 'Content-Type: application/json'
    {
     "user": {
     "uid": "abcde"
     },
     "access_token": "ORGANIZATION_ACCESS_TOKEN"
     }
    
  4. Delete User
    1. Example
      DELETE https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{USER_ID}.json
       -H 'Content-Type: application/json'
       {
       "access_token": "ORGANIZATION_ACCESS_TOKEN"
       }
      
    2. Example
      DELETE https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users.json
       -H 'Content-Type: application/json'
       {
       "access_token": "ORGANIZATION_ACCESS_TOKEN",
       "uid": "123467890"
       }
      
    3. Example
      DELETE https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users.json?access_token=ORGANIZATION_ACCESS_TOKEN
       -H 'Content-Type: application/json'
       {
       "uid": "123467890"
       }
      
    4. DELETE https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users.json?access_token=ORGANIZATION_ACCESS_TOKEN&uid=123467890
  5. Suspend User
    Example
    PUT https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{USER_ID}
     -H 'Content-Type: application/json'
     {
     "suspend": "1",
     "access_token": "ORGANIZATION_ACCESS_TOKEN"
     }
    
  6. GET User Data
    1. GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users.json?access_token={ORGANIZATION_ACCESS_TOKEN}
    2. GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{USER_ID}.json?access_token={ORGANIZATION_ACCESS_TOKEN}
    3. GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{USER_ID}.json?authentication_token={USER_ACCESS_TOKEN}
    4. GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{USER_ID}/fitness/latest.json?access_token={ORGANIZATION_ACCESS_TOKEN}&start_date={START_DATE}&end_date={END_DATE}
    5. GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{USER_ID}/routine/intraday.json?access_token={ORGANIZATION_ACCESS_TOKEN}&start_date={START_DATE}&end_date={END_DATE}
  7. Shorthand User Data Calls
    1. GET https://api.validic.com/v1/routine.json?authentication_token={USER_ACCESS_TOKEN}&start_date={START_DATE}&end_date={END_DATE}
    2. GET https://api.validic.com/v1/routine/latest.json?authentication_token={USER_ACCESS_TOKEN}&start_date={START_DATE}&end_date={END_DATE}
    3. GET https://api.validic.com/v1/routine/intraday.json?authentication_token={USER_ACCESS_TOKEN}&start_date={START_DATE}&end_date={END_DATE}
  8. GET User Apps
    1. GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{USER_ID}/apps.json?access_token={ORGANIZATION_ACCESS_TOKEN}
    2. GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{USER_ID}/apps.json?authentication_token={USER_ACCESS_TOKEN}
  9. GET User Stats
    GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/stats/users_count.json?access_token={ORGANIZATION_ACCESS_TOKEN}&start_date={START_DATE}&end_date={END_DATE}
  10. GET User Credentials
    GET https://api.validic.com/v1/me.json?authentication_token={USER_ACCESS_TOKEN}
  11. GET User Profile
    GET https://api.validic.com/v1/profile.json?authentication_token={USER_ACCESS_TOKEN}
  12. Update User Profile
    Example
    POST https://api.validic.com/v1/profile.json
     -H 'Content-Type: application/json'
     {
     "profile": {
     "gender": "M",
     "location": "NC",
     "country": "United States",
     "birth_year": "1973",
     "height": 167.5,
     "weight": 83.9146
     },
     "authentication_token":
    "d18397e3845e8b66f7453dc55ea3fc445d1b879a6f96ebe7b243badabce08c98"
     }
    
  13. Refresh User Access Token
    https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users/{USER_ID}/refresh_token.json?access_token={ORGANIZATION_ACCESS_TOKEN}
  14. GET Bulk Organization Data
    1. GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/{object}.json?access_token={ORGANIZATION_ACCESS_TOKEN}&start_date={START_DATE}&end_date={END_DATE}
    2. GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/{object}/latest.json?access_token={ORGANIZATION_ACCESS_TOKEN}&start_date={START_DATE}&end_date={END_DATE}&source={SOURCE}&expanded={BOOLEAN}&allow_null={BOOLEAN}&show_validated={BOOLEAN}&limit={LIMIT}&offset={OFFSET}&page={PAGE}
    3. GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/{object}/intraday.json?access_token={ORGANIZATION_ACCESS_TOKEN}&start_date={START_DATE}&end_date={END_DATE}
#

API Response Codes

Below is a reference of response codes provided from the Validic API:

A sample response object:

401
 {
 "code": 401,
 "message", "Unauthorized"
}

Response Code Definitions

Code
Message
Description
200
Ok
Request was successful
201
Created
POST request was successfully created
401
Unauthorized
Request was not authorized
403
Forbidden
Request was forbidden, wrong access token supplied
404
Not Found
Resource was not found
406
Not Acceptable
Supplied POST data was not accepted
409
Conflict
Resource could not processed due to a conflict (e.g. user already exists)
422
Unprocessable Entity
Resource could not be processed, wrong parameters or credentials supplied
429
Limit Exceeded
Resource could not be processed, maximum number of request to the resource was exceeded
#

Filters

Activity Data can be filtered to retrieve a specific range of data, data from a specific source, to allow non-standardized data to be exposed and to provide administrative functionality from a population view. The following examples outline how to use data filters available via the Validic API:

#
Start Date of Activity

GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/fitness.json?access_token={ORGANIZATION_ACCESS_TOKEN}&start_date=2014-03-10T00:00:00+00:00

#

End Date of Activity

GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/fitness.json?access_token={ORGANIZATION_ACCESS_TOKEN}&end_date=2014-03-10T23:59:59+00:00

#

Source Filter

The source filter allows for retrieving datasets specific to a particular source (e.g., Fitbit, BodyMedia, etc.). The source parameter may include one or more sources. Specifying multiple sources should be space delimited.

GET https://api.validic.com/v1/fitness.json?authentication_token={USER_ACCESS_TOKEN}&source={SOURCE}

or

GET https://api.validic.com/v1/fitness.json?authentication_token={USER_ACCESS_TOKEN}&source={SOURCE1} {SOURCE2}
GET https://api.validic.com/v1/fitness.json?authentication_token=df3e98f9947c1f3
48ee097fafa07e27898cb3a78e46fb518488d53f26ff27717&source=sample_app
 200
 {
 "summary": {
 ...
 }, "fitness": [
 {
 "_id": "51552cd7fded0807c400001f",
 "timestamp": "2013-03-10T07:12:16+00:00",
 "utc_offset": "-05:00"
 "type": "Walking",
 "intensity": "low",
 "start_time": "2013-03-10T02:12:16-05:00",
 "total_distance": 2600,
 "duration": 2460,
 "source": "sample_app",
 "source_name": "Sample App",
 "last_updated": "2013-03-10T07:12:16+00:00"
 },
 {
 "_id": "51552cd7fded0807c400001f",
 "timestamp": "2013-03-10T07:12:16+00:00",
 "utc_offset": "-05:00"
 "type": "Walking",
 "intensity": "low",
 "start_time": "2013-03-10T02:12:16-05:00",
 "total_distance": 2600,
 "duration": 2460,
 "source": "sample_app",
 "source_name": "Sample App",
 "last_updated": "2013-03-10T07:12:16+00:00"
 }
 ]
 }

#
Expanded Filter
The expanded filter allows for displaying all available additional output parameters from a single source. By default, expanded is set to 0 (false). Note that expanded is only available when combined with the source filter, and only one source is specified.

For example, the Nike+ API returns fuel as part of its response, which is not something Validic returns by default. To access this, you would specify source=nikeplus&expanded=1.

GET https://api.validic.com/v1/fitness.json?authentication_token={USER_ACCESS_TO
KEN}&source=sample_app&expanded=1

GET https://api.validic.com/v1/fitness.json?authentication_token=df3e98f9947c1f3
48ee097fafa07e27898cb3a78e46fb518488d53f26ff27717&source=sample_app&ex
panded=1
 200
 {
 "summary": {
 ...
 }, "fitness": [
 {
 "_id": "51552cd7fded0807c400001f",
 "timestamp": "2013-03-10T07:12:16-00:00",
 "utc_offset": "-05:00"
 "type": "Walking",
 "intensity": "low",
 "start_time": "2013-03-10T02:12:16-05:00",
"total_distance": 2600,
 "duration": 2460,
 "source": "sample_app",
 "source_name": "Sample App",
 "last_updated": "2013-03-10T07:12:16+00:00",
 + "average_pace": 3.7, # additional parameter specific to "sample_app"
 + "total_calories": 480 # additional parameter specific to "sample_app"
 }
 ]
 }

#
Status Filter
The status filter allows for displaying all users within an organization with the supplied status. By default, status is set to all.

GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/users.json?access_token={ORGANIZATION_ACCESS_TOKEN}&status=all
GET https://api.validic.com/v1/organizations/5176906c6deddac02c000001/users.jso
n?access_token=df3e98f9947c1f348ee097fafa07e27898cb3a78e46fb518488d53f26f
f27717&status=all
 200
 {
 "summary": {
 ...
 }, "users": [
 {
 "_id": "51552cd7fded0807c400001f",
 "uid": "1"
 },
 {
 "_id": "51433ft7fdrd0719c4010011",
 "uid": "2"
 }
 ]
 }

Status List and Definitions

Status
Description
all
All users within the organization
active
All users within the organization that have one or more synced application that is integrated with Validic, and has logged at least one activity in any of their synced applications within the last 90 days.
inactive
All users within the organization that have one or more synced application that is integrated with Validic, and has not logged at least one activity in any of their synced applications within the last 90 days.
provisioned
All users within the organization that have not yet synced any application that is integrated with Validic.
suspended
All users within the organization whose accounts have been suspended.

#
Validated Data Filter
The show_validated filter allows you to be able to determine if the data you are receiving through the Validic API was generated using a device. Responses returned by the Validic API will include a new “validated” field which you may refer to for dertermining if data was device generated. For data to be considered as validated, any activity retrieved by Validic from a source that can be confirmed as recorded by a device, as opposed to entered manually, is considered validated. When determining if a record is validated, Validic will only set the “validated” field to true if there is information coming from the source that the activity was recorded by the device, If the value is false, this may mean that it was manually entered or that Validic is unable to definitively determine that the origin of the record was through the use of a device.

GET https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/fitness.json?access_token={ORGANIZATION_ACCESS_TOKEN}&show_validated=1
GET https://api.validic.com/v1/organizations/51aca5a06dedda916400002b/fitness.json?access_token=ENTERPRISE_KEY&show_validated=1
200
{
  "summary": {
    ...
  },
  "fitness": [
    {
      "_id": "55018daa8d01da30e4000139",
      "timestamp": "2015-03-12T18:00:00+00:00",
      "utc_offset": "-09:00",
      "type": "Martial Arts:Brazilian Jiu Jitsu",
      "intensity": null,
      "start_time": "2015-03-12T09:00:00-09:00",
      "distance": 40346.1538,
      "duration": 8100.0,
      "calories": 1372.0,
      "source": "fitbug",
      "source_name": "Fitbug",
      "last_updated": "2015-03-12T12:59:22+00:00",
      "user_id": "52ffcb4bf1f70eefba000004",
      "validated": false
    },
    ...
  ]
}

#

Resources

#

Validic API Libraries

OAuth 2 uses request signing to avoid sending shared secrets between the client and server any more than necessary. It’s easy to get request signing wrong, so we recommend using an established OAuth 2 client library rather than implementing the specification yourself.

Recommended libraries:

Not seeing the library you’re looking for? We’re working on them. In the mean time, here are some OAuth libraries to help get you started. A more complete list of OAuth libraries can be found at http://oauth.net/code/.