Table of Contents

FitnessSyncer API

This document provides an overview of the FitnessSyncer API so that you may integrate the data in FitnessSyncer with your applications. Should you have any questions, encounter any issues, or need a different interface, please contact us.

By using our API, you agree with our Terms of Use available on our site.

We will periodically make changes to this API. Changes will generally be additive, however, periodically, we may create breaking changes and will attempt to notify you with sufficient time to update your implementations. Please contact us to ensure that you are on this mailing list.

You can also use the FitnessSyncer OpenAPI Specification to generate code, although this documentation should be used. We also have a few generated and tested implementations if needed; please contact us to get access..

Introduction

FitnessSyncer’s API provides access to information health and fitness data from over 50 sources as is displayed within the FitnessSyncer Stream and FitnessSyncer Dashboard, including data sources such as Fitbit and data captured in FitnessSyncer Notebook.

The first step in integrating with the FitnessSyncer API is to authenticate. Authentication is done via the OAuth protocol and once the user grants permission to your application to access their information, FitnessSyncer will provide you with a token that you can use for your requests.

Authenticating with FitnessSyncer

Once authenticated, your application can then access any data in FitnessSyncer or upload data into FitnessSyncer.

Most applications will interact with a Source, which is a feed from one data provider for a type of data. A Data Provider is the application or hardware that provides data and data-types such as Activity Tracking, Exercise, Allergies, Weight, Blood Pressure, Cholesterol, Condition, Glucose, Medications, Nutrition, Oxygen, Sleep, and Temperature data.

For example, if a user has a Fitbit device from which they track Exercise and Sleep information, this will result in two Sources, one for the Exercise from Fitbit, and the other for Sleep Information from Fitbit.

FitnessSyncer also provides Destination Tasks. Destination Tasks complete operations such as synchronize the data into other services, provide e-mail notification, automatically refresh sources on a schedule, etc. These are also available within this API.

When FitnessSyncer has new data, consumers of our API will need to read that new data in. A subscription allows a webhook to be sent to you when there is new data. If you wish to use this, please contact us.

FitnessSyncer free accounts are limited to the number of sources and destinations they may create. Please contact us if this is an issue.

Authentication

The FitnessSyncer API uses OAuth2 for authentication. This is a standard authentication scheme that is well documented on the web; this documentation will provide you an overview of what you need to do.

Personal Applications can be created in our developer console. For other use-cases, please contact us and we will provide you with the following information:

Note that the Redirect URL is case sensitive and should be SSL-based as our browser policy is to not redirect to non-SSL enabled locations.

Authenticating

To authenticate a web-application, the basic workflow is as follows:

  1. Redirect the user to FitnessSyncer to authorize your application’s access to their data.
  2. Once approved, FitnessSyncer will redirect the user back to your site with a temporary token.
  3. With the temporary token, you need to acquire the Access and Refresh Tokens.

To start the authentication workflow, you will need to redirect the user to https://www.fitnesssyncer.com/api/oauth/authorize with following query string parameters:

Query String Parameter NameDescription
response_typeSet to “code”
client_idSet to your Client Id.
redirect_uriSet to your Redirect URL
scopeCurrently set to “sources”
stateSet to any state you wish to get returned on the redirect URL.

Here is an example URL:

https://www.fitnesssyncer.com/api/oauth/authorize?client_id=YourClientId&response_type=code&scope=Sources&redirect_uri=YourRedirectURL&state=InformationForYourService

On success, this will redirect back to your site with the following query string parameters:

Redirect Query String Parameter NameDescription
codeA temporary Access Code. The code will be set to “error” if there was an error granting the permission.
stateThe same value you passed in the above state, if any.

Once you have the code, you can access the code by making a POST request to https://api.fitnesssyncer.com/api/oauth/access_token. The body of this request should contain:

POST Parameter NameDescription
grant_typeSet to “authorization_code”
codeThe temporary code received.
client_idSet to your Client Id.
client_secretSet to your Client Secret.
redirect_uriSet to your Redirect URL

Upon success, you will receive a 200-response code with a JSON Body as follows:

KeyDescription
expires_inTime in seconds since the epoch when the token expires.
access_tokenToken to access the data.
refresh_tokenA token to get a new access_token when the token expires.

To access any resources from this point forward, simply include the Authorization header with the value “Bearer ” followed by the access_token above. For example, if the access_token was “asdfasdf”, the Authorization header would be set to “Bearer asdfasdf”.

Refreshing the token

The access token will expire periodically. You may either keep track of the expiration yourself or when you make a request, a 401-status code is returned and you will need to reauthenticate. You can renew the token by making a POST request to: https://api.fitnesssyncer.com/api/oauth/access_token. The body of this request should contain:

POST Parameter NameDescription
grant_typeSet to “refresh_token”
refresh_tokenSet to the refresh_token as received above.
client_idSet to your Client Id.
client_secretSet to your Client Secret.
redirect_uriSet to your Redirect URL as included in the original request

Upon success, you will receive a 200-response code with a JSON Body as follows:

KeyDescription
expires_inTime in seconds when the token expires in.
access_tokenToken to access the data.
refresh_tokenA token to get a new access_token when the token expires.

Revoking the token

You may revoke a token at any time by making a POST request to: https://api.fitnesssyncer.com/api/oauth/revoke_token. The header would be the Authorization header as defined above.

Verb

POST

Resource

https://api.fitnesssyncer.com/api/oauth/revoke_token

Request Parameters

None

Response

On success, a 200 will be returned with a JSON object indicating the successful status.

Creating users

If your application can create new users, you can do so using this API.

To do so, a POST request to https://api.fitnesssyncer.com/api/oauth/access_token. The body of this request should contain:

POST Parameter NameDescription
grant_typeSet to “password”
createSet to “true”
usernameThe new user’s username. This must be in the form of an e-mail address.
passwordThe new user’s password
client_idSet to your Client Id.
client_secretSet to your Client Secret.
redirect_uriSet to your Redirect URL

Upon success, you will receive a 200-response code with a JSON Body as follows:

KeyDescription
expires_inTime in seconds when the token expires in.
access_tokenToken to access the data.
refresh_tokenA token to get a new access_token when the token expires.

To access any resources from this point forward, simply include the Authorization header with the value “Bearer ” followed by the access_token above. For example, if the access_token was “asdfasdf”, the Authorization header would be set to “Bearer asdfasdf”.

Other Considerations

It is important to realize that a user can also revoke an access token. For example, under the Permissions tab of My Account, they may choose to revoke your permissions entirely. When this occurs, accessing and refreshing the token will fail with a 403 and you will need to reauthenticate from the beginning.

User Preferences

Reading user preferences

You may read the user’s preferences by using this API. This is for informational purposes only. None of the actual API requires your knowledge of these preferences.

Verb

GET

Resource

https://api.fitnesssyncer.com/api/users/preferences

Request Parameters

None

Response

The response will be a 200 with a JSON body with the User Preferences.

Example JSON

{
  "heightInMeters": 0,
  "canemail": false,
  "autosync": true,
  "bmr": 0,
  "timezone": "UTC",
  "weightMetric": false,
  "heartRateAge": 30,
  "internationaltime": false,
  "timezoneDisplayName": "Coordinated Universal Time",
  "waterML": false,
  "distanceOverSteps": false,
  "temperatureCelsius": false,
  "heartRateMax": 187,
  "pro": true,
  "glucoseMetric": false,
  "displayname": "",
  "heartRateLevel4": 149,
  "heartRateLevel5": 168,
  "heartRateLevel2": 112,
  "distanceMetric": false,
  "privateActivities": false,
  "heartRateLevel3": 130,
  "heartRateLevel1": 74,
  "weekStartsOnMonday": false
}

Updating user preferences

You may update the user’s preferences by using this API.

Verb

POST

Resource

https://api.fitnesssyncer.com/api/users/preferences

Request Parameters

The Request Body will be a JSON object with the changes of the User Preferences.

Response

The response will be a 200 with a JSON body with the User Preferences.

Data Sources

A Data Source is a feed of data that comes from a particular provider for a specific type of data.

Listing Data Sources

To learn the data sources that exist or to find the id of your desired data type, you will need to issue a list.

Verb

GET

Resource

https://api.fitnesssyncer.com/api/providers/sources/

Request Parameters

None

Response

The response will be a 200 with a JSON body that will the List Source Data. See the Data Types section for a description.

Example JSON

{"items": [{
  "name": "My Health Data",
  "id": "1d4c35b9-f006-4f34-acea-2af7bc25161a",
  "type": "Activity",
  "enabled": true,
  "providerType": "EpsonPulseSense"
}]}

Notes

The above will not contain entries from the FitnessSyncer Notebook. You must query for those separately.

If enabled and permission is granted by the participant, Researchers and Corporate Wellness can acquire the full list data sources from all participants using this API.

Get a Specific Source

If you have an id to a specific source item, you can easily acquire the configuration of that item easily.

Verb

GET

Resource

https://api.fitnesssyncer.com/api/providers/sources/id

Request Parameters

None

Response

The response will be a 200 with a JSON body that will contain a Source Data Item. See the Data Types section for a description.

Example JSON

{"item": {
  "name": "My Health Data",
  "id": "1d4c35b9-f006-4f34-acea-2af7bc25161a",
  "type": "Activity",
  "enabled": true,
  "providerType": "EpsonPulseSense"
}}

If enabled and permission is granted by the participant, Researchers and Corporate Wellness can acquire a specific participant’s data source.

Creating new Data Sources

To create a new Data Source, one must issue a PUT request with that configuration.

Please see Provider Authentication to configure authentication for your source.

The user can also change this item using our editor. It is recommended that you only cache this data temporarily.

Verb

PUT

Resource

https://api.fitnesssyncer.com/api/providers/sources/

Request Parameters

The Request Body will be a JSON object with the Source Data. See the Data Types section for that definition. The id in that Source Data will be ignored.

Response

The Response will be a JSON body with an id field indicating the ID of the new item.

Updating Data Sources

To update a Data Source, one must issue a POST request with that configuration.

Please see Provider Authentication to configure authentication for your source.

Verb

POST

Resource

https://api.fitnesssyncer.com/api/providers/sources/id

Request Parameters

The Request Body will be a JSON object with the Source Data. See the Data Types section for that definition. The id in that Source Data will be ignored.

Response

The Response will be a JSON body with an id field indicating the ID of the updated item.

Deleting Data Sources

When you are finished with a data source, simply delete it. This operation cannot be undone.

Verb

DELETE

Resource

https://api.fitnesssyncer.com/api/providers/sources/id

Request Parameters

None

Response

The Response will be a JSON body with an id field indicating the ID of the deleted item.

Refreshing Data Sources

FitnessSyncer will periodically refresh data sources. If your application wishes to ensure that you have the latest data available, you can request a refresh.

When this operation completes, the task is enqueued and will execute sometime in the near future. You may check on the status of the task via the Sync Status API.

Note: This is only available on certain accounts. Please contact us if you require it.

Verb

POST

Resource

https://api.fitnesssyncer.com/api/providers/sources/id/refresh

Request Parameters

None are required.

If the user is a FitnessSyncer Pro, you may issue a Historic Sync request.

Response

On success, this will return a 202 with a JSON body indicating the id of the item enqueued.

In the event that there is already a pending request for this user, a 409 will be returned to you.

Data Source Items

With the identifier for a Data Source, you can access the data associated with the item.

Listing Items

The Listing API is a paging-based API, with the first page being the most recent.

Verb

GET

Resource

https://api.fitnesssyncer.com/api/providers/sources/id/items/

Request Parameters

Query Parameter NameDescription
offsetHow many entries should we skip? Default is 0.
limitHow many entries would you like to return? Default and max is 100.

Response

The Response will be a JSON body with an items field containing a List Source Data.

If enabled and permission is granted by the participant, Researchers and Corporate Wellness can acquire a specific participant’s data listing.

Getting a Specific Item

With the identifier for a Data Source, you can then access the data associated with the item. Items are generally static, so you may cache them in accordance to our terms of use.

Verb

GET

Resource

https://api.fitnesssyncer.com/api/providers/sources/id/items/itemId

Request Parameters

None

Response

The Response will be a JSON body with a SyncItem Item. See the Data Types section for a definition.

If enabled and permission is granted by the participant, Researchers and Corporate Wellness can acquire a specific participant’s activity item.

Creating new Items

This will allow you to insert new items into FitnessSyncer. You should upload data in reverse date order. It should be noted that inserting an item older than the most current item might not synchronize that item for destinations. This operation can only be done for items for which you have permission to do so.

Verb

PUT

Resource

https://api.fitnesssyncer.com/api/providers/sources/id/items/

Request Parameters

Body would be the JSON Serialization of the Item to be inserted. See the Data Types section for details.

Response

The Response will be a JSON body with an id field containing the new id. If the source has a filter associated with it which filters this out, the returned id will be “-FILTERED-”.

Updating Items

You may update any item that you have created. It should be noted that updating older items might not properly update the fields for already synchronized items. This operation can only be done for items for which you have permission to do so.

Verb

POST

Resource

https://api.fitnesssyncer.com/api/providers/sources/id/items/itemId

Request Parameters

Body would be the JSON Serialization of the Item to put inserted. See the Data Types section for details.

Response

The Response will be a JSON body with an id field containing the new id. If the source has a filter associated with it which filters this out, the returned id will be “-FILTERED-”.

Uploading Fitness Files

If you have the data already within a file, you can upload that file into the system.

This API is just for uploading that file. To change any metadata, you will need to update that record accordingly.

Note that a single upload may result in multiple items depending on the file format.

Verb

POST

Resource

https://api.fitnesssyncer.com/api/providers/sources/id/items/upload

Request Parameters

The Body is a multipart-form that contains an element named as file which encompasses a TCX, GPX, KML, KMZ, FIT, or PWX file. This must also include the standard Content-Disposition header.

By default, FitnessSyncer will attempt to de-dupe uploads. If you wish to circumvent this, please include the dedupe=false query string parameter.

If you are attempting to upload a file for a specific item, you may also include the id={id} query string parameter.

Response

The Response will be a JSON body with a list of items; each item will include an id and url for the item.

Deleting Items

Verb

DELETE

Resource

https://api.fitnesssyncer.com/api/providers/sources/id/items/itemId

Request Parameters

None

Response

The Response will be a JSON body with an id field containing the deleted item.

Destination Tasks

A Destination Tasks is a task that operates over the source data to accomplish a task. The most common of these is a data synchronization task.

Listing Destination Tasks

To learn the destinations tasks that exist or to find the id of your desired destination, you will need to issue a list.

Verb

GET

Resource

https://api.fitnesssyncer.com/api/providers/destinations/

Request Parameters

None

Response

The response will be a 200 with a JSON body that will contain a List of Destination Tasks. See the Data Types section for a description.

Example JSON

{"items": [{
  "taskType": "Activity",
  "hour": -1,
  "name": "Synchronization Task",
  "id": "1d4c35b9-f006-4f34-acea-2af7bc25161a",
  "type": "sync",
  "enabled": true,
  "providerType": "FitBit"
}]}

Get a Specific Destination Task

If you have an id to a specific destination task, you can easily acquire the configuration of that task easily.

Verb

GET

Resource

https://api.fitnesssyncer.com/api/providers/destinations/id

Request Parameters

None

Response

The response will be a 200 with a JSON body that will contain an Item Destination Task. See the Data Types section for a description.

Example JSON

{"item": {
  "taskType": "Activity",
  "hour": -1,
  "name": "Synchronization Task",
  "id": "1d4c35b9-f006-4f34-acea-2af7bc25161a",
  "type": "sync",
  "enabled": true,
  "providerType": "FitBit"
}}

Creating new Destinations Task

To create a new Destination Task, one must issue a PUT request with that configuration.

Please see Provider Authentication to configure authentication for your destination.

The user can also change this item using our editor. It is recommended that you only cache this data temporarily.

Verb

PUT

Resource

https://api.fitnesssyncer.com/api/providers/destinations/

Request Parameters

The Request Body will be a JSON object with the Destination Data. See the Data Types section for that definition. The id in that Destination Data will be ignored.

Response

The Response will be a JSON body with an id field indicating the ID of the new item.

Updating Destinations Tasks

To update a Destination Task, one must issue a POST request with that configuration.

Please see Provider Authentication to configure authentication for your destination.

Verb

POST

Resource

https://api.fitnesssyncer.com/api/providers/destinations/id

Request Parameters

The Request Body will be a JSON object with the Destination Data. See the Data Types section for that definition. The id in that Destination Task will be ignored.

Response

The Response will be a JSON body with an id field indicating the ID of the updated item.

Deleting Data Destinations

When you are finished with a destination task, simply delete it. This operation cannot be undone.

Verb

DELETE

Resource

https://api.fitnesssyncer.com/api/providers/destinations/id

Request Parameters

None

Response

The Response will be a JSON body with an id field indicating the ID of the deleted item.

Executing Data Destinations

FitnessSyncer will periodically execute destinations tasks. If your application wishes to run these themselves, you can request an execute.

When this operation completes, the task is enqueued and will execute sometime in the near future. You may check on the status of the task via the Sync Status API.

Note: This is only available on certain accounts. Please contact us if you require it.

Verb

POST

Resource

https://api.fitnesssyncer.com/api/providers/destinations/id/execute

Request Parameters

None

Response

On success, this will return a 200 with a JSON body indicating the id of the item enqueued.

In the event that there is already a pending request for this user, a 409 will be returned to you.

Providers

To configure a source or destination, you will require some information regarding our current providers and authenticating with them. The following documentation outlines this.

Listing Providers

This method acquires the data providers that are presently available on FitnessSyncer. It should be noted that this method is highly cacheable, especially if you are using a fixed set of providers.

Verb

GET

Resource

https://api.fitnesssyncer.com/api/providers/types/

Request Parameters

None

Response

The Response will be a JSON body with Provider List.

Provider Authentication

There are various ways to configure authentication for a provider. The provider list would have provided you with a value for authenticating.

NameDescription
UsernamePasswordThis indicates that you must provide a username and password for this user.
IdentifierThis indicates that you must provide an identifier for this user for authentication.
AppRequiredThis indicates that one of our or a partner app is required to authenticate. If it is a supported app, an appurl will be also included in the body.
OAuthThis indicates that you must request an OAuth token flow to be initiated for your user to provide FitnessSyncer with the appropriate authentication.
UnsupportedThis should not generally be returned, but should it be returned, you should ignore such providers.

Once you have selected a provider and created a source for it, you need to add authentication for it as follows.

You should build your application such that if there are new values, that your application appropriate degrades.

Verb

PUT

Resource

https://api.fitnesssyncer.com/api/providers/sources/id/authentication

https://api.fitnesssyncer.com/api/providers/destinations/id/authentication

Where id is the id of the Source you are trying to authenticate.

Request Parameters

The request body will contain a JSON object as described here.

UsernamePassword

This will securely store the authentication on our servers and return a 200 response to you on success.

KeyDescription
typeAlways UsernamePassword
usernameThe username required for the user’s authentication
passwordThe password required for the user’s authentication
UsernamePasswordKey

This will securely store the authentication on our servers and return a 200 response to you on success.

KeyDescription
typeAlways UsernamePasswordKey
usernameThe username required for the user’s authentication
passwordThe password required for the user’s authentication
clientIdThe client id required for the user’s authentication
clientSecretThe client secret required for the user’s authentication
Identifier

This will securely store the identifier for the service on our servers and return a 200 response to you on success.

KeyDescription
typeAlways Identifier
identifierThe identifier required for the user’s authentication
OAuth

This will start the redirects required to authenticate an OAuth-like scheme. This will return a 202 to you with a Location header to pass onto your user. Your user will end at the URL provided below on success or failure (except where beyond our control or extreme failures).

KeyDescription
typeAlways OAuth
redirectThe URL you wish for FitnessSyncer to redirect the user for either success or failure modes
OAuthReuse

See Provider Authenticate for how to get the id field for this request.

This will store the re-use request and will return a 200 response to you on success.

KeyDescription
typeAlways OAuthReuse
idid of the item which you wish to re-use the authentication of

Response

If your request has been stored successfully, the response code will be a 200 without a body.

If your request has been initiated successfully, the response code will be a 202. Such a request will contain a Location header that you must send your user to. That location will be directed back to a FitnessSyncer service that will drive the completion of the request and redirect the user back to your site when the request is successful or has failed.

Existing Provider Authentication

If you are using the same source system for multiple devices, you need to use the same authentication for each source. This method will allow you to acquire the authorization summary of what exists already so that you can re-use that authentication.

Verb

GET

Resource

https://api.fitnesssyncer.com/api/providers/authentication/

Request Parameters

None

Response

The Response will be a JSON body with a Providers Authentication.

Example JSON

{"providers": [{
  "keys": [{
    "name": "Fitbit Sleep Source",
    "id": "d8e1eb2e-bf26-4521-8c4b-7d85590e0588"
  }],
  "name": "Fitbit",
  "type": "FitBit"
}]}

Synchronization Status

The Source Refresh or Destination Task Execute APIs, you are not given any updates on what the status of those tasks is. This API provides you some insight.

Getting Synchronization Status

If you are using the same source system for multiple devices, you need to use the same authentication for each source. This method will allow you to acquire the authorization summary of what exists already so that you can re-use that authentication.

Verb

GET

Resource

https://api.fitnesssyncer.com/api/syncs/

Request Parameters

None

Response

The Response will be a JSON body with a Sync Status result.

FitnessSyncer Notebook

The FitnessSyncer Notebook uses the same API as the Data Source Items; however, the id is the constant “notebook”.

This section describes the new functionality for the API.

Listing Items by Type

Verb

GET

Resource

https://api.fitnesssyncer.com/api/providers/sources/notebook/itemsByType/type

where type is one of the TaskType’s

Request Parameters

Query Parameter NameDescription
offsetHow many entries should we skip? Default is 0.
limitHow many entries would you like to return? Default and max is 100.

Response

The Response will be a JSON body with an items field containing a List Sync Items.

Getting Categories

The FitnessSyncer Notebook can have various task types. This API will tell you which TaskTypes are being used.

Verb

GET

Resource

https://api.fitnesssyncer.com/api/providers/sources/notebook/categories

Request Parameters

None

Response

The Response will be a JSON body with an items field containing a List Task Types.

Notifications

You may subscribe your users to get notifications for certain classes of errors or new items to be sent directly to your site via WebHook or collected periodically.

For webhooks, the basic workflow for this is that you would provide us with a URL to be notified and potentially a filter. You can choose to be notified with each item or as a generic notification. Your site must use SSL using a non-self-served certificate. You should not whitelist our IP addresses as we updated our addresses regularly for scalability reasons. Each message sent to you will contain a X-FitnessSyncer-Signature header which will be the HMAC-SHA1 hash of the context body part using your OAuth2 Secret Key as the signature.

To pull notifications, the basic workflow for this is that you would provide with maybe a filter and then periodically you will collect the notifications and delete any claims.

Once notifications are enabled for your account, then you can subscribe a user using the API below. When the user adds a new item, this item would be sent or made available to your notification system.

If your account has multiple notification rules, you only need to subscribe once per user.

The request to your server will be a POST request containing:

POST Parameter NameDescription
contextA JSON Object containing at a minimum the notificationKey from below.
fileFor non-generic pushes, this would contain the GPX/TCX/FIT/PWX/KML/KMZ/etc. file.
sourceIdFor non-generic pushes, this would be the id of the SourceData that generated this item.
itemIdFor non-generic objects, this would be the item id.

Your server must respond with a 200 or 201. If your server responds with a 403, the user will be automatically unsubscribed. All other error codes will be retried up-to a predefined maximum attempts.

Learning if there is a subscription

To figure out if there is an active subscription, use this method. You may periodically wish to do this in the event of errors notifying your service of a subscription.

Verb

GET

Resource

https://api.fitnesssyncer.com/api/subscriptions/

Request Parameters

None

Response

The response to this query will be a JSON object with Subscription.

If there is not an active subscription, the response will be a 404.

Sample

{"notificationKey": "1bd2a05e-7c1e-40fc-b3de-57f0b1672861"}

Subscribing

To subscribe a user for notifications, you can use this API.

Verb

PUT

Resource

https://api.fitnesssyncer.com/api/subscriptions/

Request Parameters

None

Response

The response to this query will be a JSON object with Subscription.

Sample

{"notificationKey": "1bd2a05e-7c1e-40fc-b3de-57f0b1672861"}

Unsubscribing

To unsubscribe from the API, use this API.

Note that if your server responds with a 403 error when it is notified, they will be automatically unsubscribed.

Verb

DELETE

Resource

https://api.fitnesssyncer.com/api/subscriptions/notificationKey

Request Parameters

None

Response

The response to this query will be a JSON object with a status indicating success.

Sample

{"status": "OK"}

Pull Notifications: Claiming

For pull notifications, you will need to claim notifications, process the notifications, and then delete the claim. If you do not delete the claim, the notification will eventually come back to you.

Note that we will only provide you with a maximum of 100 notifications per response. If you have more than 100 notifications, you will need to requery the API for each notification.

Verb

POST

Resource

https://api.fitnesssyncer.com/api/notifications/

Request Parameters

None

Response

The body of the JSON object will have Notification result.

Sample

{
  "claim": "1bd2a05e-7c1e-40fc-b3de-57f0b1672861",
  "notifications": {
    "items": [{"notificationKey": "1bd2a05e-7c1e-40fc-b3de-57f0b1672861"}],
    "errors": []
  }
}

Pull Notifications: Deleting Notifications

Once you have successfully process a notification, you must delete the notification. Failure you to do so will result in the same notifications being processed by you multiple times.

Verb

DELETE

Resource

https://api.fitnesssyncer.com/api/notifications/claim

Request Parameters

None

Response

The response to this query will be a JSON object with a status indicating success.

Sample

{"status": "OK"}

Descriptions API

For data values which contain a key and a value descriptor, the Descriptions API provides a convenient way to resolve those two values. This API is highly cacheable.

Getting Descriptions

This method acquires the metadata from FitnessSyncer. This is highly cacheable.

Verb

GET

Resource

https://api.fitnesssyncer.com/api/descriptions/type

where type is one of activities, comparisons, dataFields, granularities, or reducers.

Key Parameter NameDescription
activitiesList of Activity Types that FitnessSyncer Supports.
comparisonsList of Comparisons Types that FitnessSyncer Supports for Filters, Leaderboards, ShoeRenew, and other operations.
dataFieldsList of Data Fields that FitnessSyncer Supports for Reports
granularitiesList of Granularities that FitnessSyncer Supports for Reports
labelersList of Labelers that FitnessSyncer Supports for Reports
reducersList of Reduces that FitnessSyncer Supports for Filters, ShoeRenew, and other operations

Request Parameters

None

Response

The body of the JSON array of Descriptions Result.

Leaderboards API

FitnessSyncer Leaderboards allow for device independent competitions on a single Data Field. This API allows for the management of the competitions.

List Leaderboards

This method lists all Leaderboards for a user.

Verb

GET

Resource

https://api.fitnesssyncer.com/api/leaderboards/

Request Parameters

None

Response

The body with the Leaderboard List Result.

Get Leaderboard

This method gets a Leaderboard by id.

Verb

GET

Resource

https://api.fitnesssyncer.com/api/leaderboards/id

Request Parameters

None

Response

The body of Leaderboard Item Result.

Create Leaderboard

This method creates a Leaderboard.

Verb

PUT

Resource

https://api.fitnesssyncer.com/api/leaderboards/

Request Parameters

A body containing a Leaderboard

Response

The body with the Id Result.

Update Leaderboard

This method updates a Leaderboard.

Verb

POST

Resource

https://api.fitnesssyncer.com/api/leaderboards/id

Request Parameters

A body containing a Leaderboard

Response

The body with the Id Result.

Delete Leaderboard

This method deletes a Leaderboard.

Verb

DELETE

Resource

https://api.fitnesssyncer.com/api/leaderboards/id

Request Parameters

None

Response

The body with the Id Result.

Get Leaderboard Data

This method acquires the data associated with a Leaderboard.

Verb

GET

Resource

https://api.fitnesssyncer.com/api/leaderboards/id/data

Request Parameters

None

Response

The body with the Leaderboard Data Result.

Add User to Leaderboard

This method adds a user to a Leaderboard.

Verb

POST

Resource

https://api.fitnesssyncer.com/api/leaderboards/id/user

This also takes an optional sendInvitationEmails query string which if set to false, will not send e-mail notifications to the user.

Request Parameters

A body containing a Leaderboard

Response

The body with the Id Result.

User Accept Leaderboard

This accepts an invitation to a Leaderboard.

Calling this API implies that the user has consented to this action. The user must have been shown all of the information associated with the Leaderboard and told that their information will be visible to all users of the Leaderboard. Furthermore, for absolute data such as weight, the user should be informed *not* to share this information unless the user truly trusts the person or organization using this information.

Verb

PUT

Resource

https://api.fitnesssyncer.com/api/leaderboards/id/accept

Request Parameters

A body containing a Leaderboard

Response

The body with the Id Result.

Delete User to Leaderboard

This method deletes the current user from the Leaderboard.

Verb

DELETE

Resource

https://api.fitnesssyncer.com/api/leaderboards/id/user

Request Parameters

None

Response

The body with the Id Result.

User Administrator User Deletion

This method deletes the specified user(s) from the Leaderboard.

Verb

DELETE

Resource

https://api.fitnesssyncer.com/api/leaderboards/id/user

Request Parameters

Body of Leaderboard User

Response

The body with the Id Result.

Dashboards API

FitnessSyncer’s core application has rich Ddashboard capabilities. This API allows you to tap into the functionality provided, however, a key feature of this API is that you can simply create requests without creating or managing FitnessSyncer Reports directly and allows you to use your own visualization libraries.

Building a Chart can take time especially for users with lots of data and complex queries. To ensure that your request does not time out, this API is asynchronous. To get data for a dashboard, you must first create a dashboard request. Next, you must poll for the results using the Get Session API.

The best practice for creating reports is that you group similar requests for similar data types together. For example, if you are trying to fetch Steps and Distance information, grouping those together will be faster than making these separately.

The chart data is highly cacheable as the underlying data changes slowly. Please make reasonable caching decisions based on this.

When checking for results, you should also insert a reasonable delay betwen polling.

Note that dashboard results will automatically be removed after approximately 10 minutes.

Create Dashboard Request

This creates a Dashboard Request which will provide you with an Session that you can then resolve to get to the actual data.

Verb

POST

Resource

https://api.fitnesssyncer.com/api/dashboards/

Request Parameters

A body containing a Dashboard Request

Response

In some rare occasions, the data may already be available and may be returned immediately. If so, the HTTP Response Code will be a 200 and the body will be a Dashboard Data Response.

Typically, the HTTP Response Code will be a 202 the body will be a Dashboard Session Created.

Create Dashboard Request

After submitting a Create Dashboard Request, it will likely have responded with a 202 with a Dashboard Session Created.

If so, you must use the session id from that response to acquire the data using this API. This may require several calls before the data is available.

Note that dashboard results will automatically be removed after approximately 10 minutes.

Verb

POST

Resource

https://api.fitnesssyncer.com/api/dashboards/{session_id}

Request Parameters

None

Response

If the data is available, the HTTP Response Code will be a 200 and the body will be a Dashboard Data Response.

If the data is not available, the HTTP Response Code will be a 202 the body will be a Dashboard Session Created. The ssession id will not change between invocations.

If the session has expired, the HTTP Response Code will be a 410. You will need to recreate the Dashboard Request. If this happens repeatedly, please contact us.

Data Types

TaskType

A TaskType is an enumeration would presently is one of:

There may be other values in the future. Your API should ignore any TaskType it does not understand.

List of Source Data

JSON ItemData TypeDescription
itemsArray of SourceData

Source Data Item

JSON ItemData TypeDescription
itemSourceData

List of Source Data Items

JSON ItemData TypeDescription
itemsArray of SyncItemListItem

List of Sync Items

JSON ItemData TypeDescription
itemsArray of SyncItem

Sync Item Item

JSON ItemData TypeDescription
itemSyncItem

Source Data List Entry

JSON ItemData TypeDescription
itemIdStringId of the Item
dateLongTime of the item as milliseconds since the Epoch in UTC
linksSyncItemLinks
JSON ItemData TypeDescription
fitStringURL for the FIT file (if applicable)
pwxStringURL for the PWX file (if applicable)
tcxStringURL for the TCX file (if applicable)
kmlStringURL for the KML file (if applicable)
kmzStringURL for the KMZ file (if applicable)
csvStringURL for the CSV file (if applicable)
gpxStringURL for the GPX file (if applicable)

List of Task Type

JSON ItemData TypeDescription
itemsArray of StringList of the TaskTypes. One of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature

Id

JSON ItemData TypeDescription
idStringIdentifier of the item created or changed.

Historic Sync Request

This is an optional request body to the Refresh Data Source.

JSON ItemData TypeDescription
startLongStart time for the Historic Sync in milliseconds since the Epoch in UTC
endLongEnd time for the Historic Sync in milliseconds since the Epoch in UTC
emailBooleanTrue to e-mail the user at the end of the historic sync.

Source Data

This structure defines the Source Data

JSON ItemData TypeDescription
typeStringEnumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature
idStringA String identifier for the task. This is used throughout the API for uniquely identifying this item.
nameStringA user description for the source.
contextStringOptional and only available in Pro accounts, provides a grouping context for our charts.
providerTypeStringThe Provider Type enumeration value.
enabledBooleanIndicates whether this source is enabled or not.
deprecatedBooleanTrue if this item has been deprecated.
ignoreDailyCaloriesBooleanTrue to ignore the daily calories summary
lastErrorStringThis is a description of the last error that this source encountered.
dateLongDate of the last synchronization or error.
identifierStringIf the authentication for this is a username or identifier, this would be that string to aid in editing.

At this time, filters are not configurable via the API. Other fields may be included in the future and should be ignored.

Sample

{
  "name": "My Health Data",
  "id": "1d4c35b9-f006-4f34-acea-2af7bc25161a",
  "type": "Activity",
  "enabled": true,
  "providerType": "EpsonPulseSense"
}

List of Destination Task

JSON ItemData TypeDescription
itemsArray of DestinationTask

Destination Task Item

JSON ItemData TypeDescription
itemDestinationTask

Destination Task

This structure defines the Destination Task, which based on the type of task will extend this task to other types.

JSON ItemData TypeDescription
typeStringThis is the type of destination task. Not all of the types supported by FitnessSyncer are documented here.
idStringA String identifier for the task. This is used throughout the API for uniquely identifying this item.
nameStringA user description for the destination.
hourIntegerHour for this task to be ran (if Pro). The time is specified in PST.
localHourIntegerHour converted to the user's timezone (from their profile).
lastErrorStringThis is a description of the last error that this source encountered.
dateLongDate of the last synchronization or error.
enabledBooleanIndicates whether this destination is enabled or not.

At this time, filters are not configurable via the API. Other fields may be included in the future and should be ignored.

If you require access to one of the destination tasks which are not documented, simply contact us.

Sample

{
  "taskType": "Activity",
  "hour": -1,
  "name": "Synchronization Task",
  "id": "1d4c35b9-f006-4f34-acea-2af7bc25161a",
  "type": "sync",
  "enabled": true,
  "providerType": "FitBit"
}

Sync Destination Task

This structure defines the Destination Task of type “sync”. This extends Destination Task.

JSON ItemData TypeDescription
taskTypeStringEnumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature
providerTypeStringThe Provider Type enumeration value. See Listing Providers for details.
skipDataFieldsArray of StringList of fields to skip over (if applicable)
onlyIfNotOnDestBooleanMode that only places items on the destination IF there is nothing on the destination for the day. Not recommended.
identifierStringIf the authentication for this is a username or identifier, this would be that string to aid in editing.
typeStringThis is the type of destination task. Not all of the types supported by FitnessSyncer are documented here.
idStringA String identifier for the task. This is used throughout the API for uniquely identifying this item.
nameStringA user description for the destination.
hourIntegerHour for this task to be ran (if Pro). The time is specified in PST.
localHourIntegerHour converted to the user's timezone (from their profile).
lastErrorStringThis is a description of the last error that this source encountered.
dateLongDate of the last synchronization or error.
enabledBooleanIndicates whether this destination is enabled or not.

Sample

{
  "taskType": "Activity",
  "hour": -1,
  "name": "Synchronization Task",
  "id": "1d4c35b9-f006-4f34-acea-2af7bc25161a",
  "type": "sync",
  "enabled": true,
  "providerType": "FitBit"
}

User Preferences

JSON ItemData TypeDescription
autosyncBooleanIf this is a Pro user, this will denote whether Auto-Sync is enabled or not.
bmrIntegerBasal Metabolic Rate. If unknown, this will be 0.
birthdateLongBirth date as an epoch of the user. This will be 0 if unknown.
ageIntegerAge of the user. This will be 0 if unknown.
canemailBooleanTrue if FitnessSyncer can periodically send e-mails to this user.
distanceOverStepsBooleanFor destination syncs, does the user prefer distance or steps to be synchronized?
privateActivitiesBooleanIndicates whether the user prefers private activities for destination synchronizations?
heightInMetersDoubleHow tall is the user in meters? If unknown, this will be 0.
distanceMetricBooleanIndicates whether the user prefers metric units for distance and height.
nutritionMetricBooleanIndicates whether the user prefers metric units for nutrition.
weightMetricBooleanIndicates whether the user prefers metric units for weight.
glucoseMetricBooleanIndicates whether the user prefers metric units for blood-based units.
temperatureCelsiusBooleanIndicates whether the user prefers metric units for temperature.
waterMLBooleanIndicates whether the user prefers metric units for water consumption.
internationaltimeBooleanIndicates whether the user prefers 24-hour time and YYYY-MM-DD dates or not.
weekStartsOnMondayBooleanIndicates whether the user prefers the week to start on Monday instead of Sunday.
localeStringLocale of the user.
numericLocaleStringUser's number locale, currently en or fr.
bodyshapeStringBody Shape of the user. Must be one of: Unspecified, Rectangle, Triangle, Trapezoid, Oval, HourGlass, Round, InvertedTriangle
sexStringGender of the user. Must be one of: Unspecified, Female, Male
timezoneStringUser’s time zone.
timezoneDisplayNameStringTime Zone display Name.
displaynameStringUser’s Display Name.
heartRateLevel1IntegerUser’s minimum heart rate at level 1 or the system default.
heartRateLevel2IntegerUser’s minimum heart rate at level 2 or the system default.
heartRateLevel3IntegerUser’s minimum heart rate at level 3 or the system default.
heartRateLevel4IntegerUser’s minimum heart rate at level 4 or the system default.
heartRateLevel5IntegerUser’s minimum heart rate at level 5 or the system default.
heartRateAgeIntegerUser’s age last used to calculate the heart rate.
heartRateMaxIntegerUser’s maximum heart rate or the system default.
proBooleanTrue if the user is a FitnessSyncer Pro subscriber
betaBooleanTrue if the user has any boolean flags.
powerZonesMap of String to PowerZonesList of Power Zone Definitions based on Sport.
sleepRatioDoubleSleep Ratio for Sleep Debt Calculation. Defaults to 0.5 which represents 1:2 ratio (8 hours of sleep to 16 hours awake)
graphSleepByWakeTimeBooleanHow should the system graph sleep? If true, this will graph it based on the awake time. Otherwise, this will be graphed based on bedtime.

List of Providers

JSON ItemData TypeDescription
providersArray of Provider

Provider

JSON ItemData TypeDescription
providerTypeStringThis is the value of the providerType to be passed in. This should not be displayed.
nameStringThis is the description of the provider for display purposes.
authenticationStringThis is the type of authentication which this provider requires. See the Provider Authentication section for information.
betaBooleanIf this is true, this implies that this provider type is presently in public beta testing.
notificationsBooleanTrue if this service currently does notifications-based synchronization.
cloudStorageMapsProviderBooleanTrue if this is a Cloud Storage Map Provider.
cloudStorageCsvProviderBooleanTrue if this is a Cloudd Storage CSV Provider.
googleServicesBooleanTrue if this is part of the Google Authentication Service Suite
reauthenticateAllBooleanTrue if this is a candidate for Reauthenticate All.
historicSyncBooleanTrue if this type supports Historic Sync.
compatibleAuthenticationArray of StringList of providers
faqStringURL to the FAQ
logoStringURL to the Logo
appurlStringIf this represents an app, this represents the URL for that app.
ActivityReadBooleanTrue if this provider can read activity data.
ActivityWriteBooleanTrue if this provider can write activity data.
AllergyReadBooleanTrue if this provider can read allergy data.
AllergyWriteBooleanTrue if this provider can write allergy data.
WeightReadBooleanTrue if this provider can read body composition data.
WeightWriteBooleanTrue if this provider can write body composition data.
BloodPressureReadBooleanTrue if this provider can read blood pressure data.
BloodPressureWriteBooleanTrue if this provider can write blood pressure data.
CholesterolReadBooleanTrue if this provider can read cholesterol data.
CholesterolWriteBooleanTrue if this provider can write cholesterol data.
ConditionReadBooleanTrue if this provider can read condition data.
ConditionWriteBooleanTrue if this provider can write condition data.
GlucoseReadBooleanTrue if this provider can read glucose data.
GlucoseWriteBooleanTrue if this provider can write glucose data.
MedicationReadBooleanTrue if this provider can read medication data.
MedicationWriteBooleanTrue if this provider can write medication data.
NutritionReadBooleanTrue if this provider can read nutrition data.
NutritionWriteBooleanTrue if this provider can write nutrition data.
OxygenReadBooleanTrue if this provider can read oxygen data.
OxygenWriteBooleanTrue if this provider can write oxygen data.
SleepReadBooleanTrue if this provider can read sleep data.
SleepWriteBooleanTrue if this provider can write sleep data.
TemperatureReadBooleanTrue if this provider can read temperature data.
TemperatureWriteBooleanTrue if this provider can write temperature data.

Provider Authentication

JSON ItemData TypeDescription
providersArray of ProviderAuthenticationItemList of providers

Provider Authentication Item

JSON ItemData TypeDescription
nameStringThis is the description of the provider for display purposes.
providerTypeStringThis is the value of the providerType to be passed in. This should not be displayed.
keysArray of ProviderAuthenticationKey

Provider Authentication Key

JSON ItemData TypeDescription
nameStringName of the source or destination task represented here. If there are tasks with duplicate names, there may be an identifier at the end of the name to help with ordering.
idStringId of the source or destination to be used with the re-use.

Sync Status Results

JSON ItemData TypeDescription
resultsArray of SyncStatus

Sync Status

JSON ItemData TypeDescription
idStringThe id of the source or destination.
typeStringIndication of the type ranging from SOURCE or DESTINATION. Other types should be ignored.
statusStringA summary of the current status, such as Running, Queued, Status, Complete
stateStringWhich state is this task in; this is not available for all tasks. Generally will be: HISTORIC_SYNC, REFRESHING, COMPARING, SYNCING, UPLOADING
infoStringIf available, the localized message summarizing the state
upToLongDate about how far this has been processed up-to
updateStringAny recent error messages from this source or destination.

Subscription

JSON ItemData TypeDescription
notificationKeyStringThe notification key for the subscription. This notificationKey will be in each of the notifications executed to your service on behalf of this user. Repeating queries here will result in new keys being created.

Notification

JSON ItemData TypeDescription
claimStringThe claim will be required for deleting the notification.
itemsArray of SubscriptionList of the subscriptions which have data.
errorsArray of SubscriptionList of the subscriptions which have encountered one or more errors.

Description Results

JSON ItemData TypeDescription
resultsArray of DescriptionThe array of results.

Description

JSON ItemData TypeDescription
keyStringThis is the key id which is to be referenced within this API.
descriptionStringDescription of the item.
taskTypeStringEnumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature
isMeasuredTypeBooleanTrue if this is a measured type where metric or imperial would make a difference.
metricBooleanTrue if this value should be used on metric values. False if this is imperial. Null if this is not applicable.
onlyReportSettingsBooleanTrue if this granularity is only allowed for Report Settings and not for Report Inquiries.
measurementTypeStringWhat type of display preference takes precedence when displaying this unit. One of: DISTANCE, WEIGHT, GLUCOSE, TEMPERATURE, NUTRITION, WATER

Power Zones

JSON ItemData TypeDescription
baseIntegerBase Power Zone
maxZone1IntegerMaximum value for Zone 1
maxZone2IntegerMaximum value for Zone 2
maxZone3IntegerMaximum value for Zone 3
maxZone4IntegerMaximum value for Zone 4
maxZone5IntegerMaximum value for Zone 5
maxZone6IntegerMaximum value for Zone 6

Leaderboard

JSON ItemData TypeDescription
idStringThis is the unique id for this leaderboard.
nameStringThis is the name of the Leaderboard. This must be unique.
descriptionStringDescription of the Leaderboard
granularityStringWhat is the granularity you wish for this to run at? Must be one of: DAY, WEEK, or MONTH
userLimitLongThis is the user limit for this leaderboard.
emailBooleanShould we send periodic e-mail notifications?
anyoneCanSignUpBooleanBy default, the Leaderboard will only allow users who have been explicitly invited. With this option enabled, anyone with a FitnessSyncer account can sign up up-to the limit.
chartLineGranularityBooleanShould the Leaderboard include the Line Chart per Granularity?
chartTableGranularityBooleanShould the Leaderboard include the Table per Granularity?
chartClassicLeaderboardBooleanShould the leaderboard include the Classic Leaderboard View?
relativeBooleanTrue if the graphs should be relative progress; this disables Group Goals and Classic Leaderboards. This can only be set on creation and cannot be toggled.
groupGoalDoubleFitnessSyncer Leaderboards can be configured to be both a challenge for individuals or for a group. If set to a non-negative value, this setting enables group challenges and this is the value for which the primary data field must exceed.
dataFieldArray of StringData Field for this Leaderboard. The first element is the primary comparison value whereas the others are used for tabular visualization.
startDateLongStart Date of the Leaderboard in milliseconds since Epoch
endDateLongEnd Date of the Leaderboard in milliseconds since Epoch

Leaderboard Item

JSON ItemData TypeDescription
itemLeaderboard

Leaderboard List

JSON ItemData TypeDescription
ownArray of LeaderboardList of the Leaderboards this user owns.
pendingArray of LeaderboardList of the Leaderboards this user has not yet accepted.
acceptedArray of LeaderboardList of the Leaderboards this user has accepted.

Leaderboard User

JSON ItemData TypeDescription
userStringAdd a single user
usersArray of StringAdd a set of users.

Leaderboard Data

JSON ItemData TypeDescription
dataLeaderboardData_data

Leaderboard Data Data

JSON ItemData TypeDescription
categoriesArray of StringCategories of the chart, in increasing order
entriesArray of LeaderboardData_data_entriesParticipants

Leaderboard Data Data Entries

JSON ItemData TypeDescription
participantStringDisplay name of the participant.
valuesArray of LeaderboardData_data_valuesValues of the Participant

Leaderboard Data Data Values

JSON ItemData TypeDescription
categoryStringCategory name
valueDoubleCategory value

Dashboard Request

The Dashboard Request configures the chart the way you want it. To understand the parameters to the request, it is best to segment the parameters into how they are used.

Data Selection Parameters
  • dataView
  • granularity
  • dataFields
  • includeNotebook
  • sourceIds
  • activityTypes
  • customStart
  • customEnd
Processing Parameters
  • removeDuplicates
  • reducer
  • finalReducer
Chart Parameters
  • treatNoDataAsZero
  • treatZeroAsNoData
  • labeler
JSON ItemData TypeDescription
includeNotebookBooleanShould we include the values from FitnessSyncer Notebook? The default is true.
sourceIdsArray of StringThis specifics the IDs of all of the sources to use for this query. If not specified, this will include all sources.
activityTypesArray of IntegerThis specifies the sport types you wish to include. If not specified, this will include all activities. See the Descriptions Activity API.
customStartLongIf the DataView is set to PERIOD, this is the time in milliseconds to use as the start time in UTC.
customEndLongIf the DataView is set to PERIOD, this is the time in milliseconds to use as the end time in UTC.
removeDuplicatesBooleanShould the chart remove duplicates? The default is true.
reducerStringThe reducer to run on the data per granularity. See the descriptions API. The default is RANGE_NO_ZEROS.
finalReducerStringThe reducer to run on the data per period. See the descriptions API. The default is RANGE_NO_ZEROS.
treatNoDataAsZeroBooleanIf there is no data available for a granularity, should it be treated as a null? The default is false.
treatZeroAsNoDataBooleanIf a value is 0, should it be treated as a null? The default is false.
dataViewStringView for the data. Must be one of: TEN_PERIODS, STANDARD, QUARTER, HALF, or YEAR. The default is STANDARD.
granularityStringWhat is the granularity you wish for this to run at? Must be one of: DAY10 (10 periods), DAY, WEEK, MONTH, or PERIOD. If PERIOD, you must set customStart and customEnd. The default is DAY10.
labelerStringWhat should we use for the labeler of the data? This allows you to group the data differently; the default is PROVIDER. See the descriptions API.
dataFieldsArray of StringEach of the DataFields for the fields to be returned. See the descriptions API. This is a required field.

Dashboard Session Created

JSON ItemData TypeDescription
sessionStringSession id to use with the Session API

Dashboard Response

The Dashboard response is a set of series intended for a chart. Depending on the number of data fields, parameters you have selected (such as the Range reducer and data values), and other parameters, there could be more than one series.

In the case of Range reducers (RANGE, RANGE_NO_ZEROS, and SUMRANGE_NO_ZEROS) and where data has more than one value per period, the series will be duplicated and will contain the minimum (min), maximum (max), average (avg), sum, and number of entries (count) as seperate series. You can identify this as the label will be duplicated and the type will indicate the meaning of the value.

Each series has a label and an array of values. The Categories root parameter correspond to the array indexes of these values.

JSON ItemData TypeDescription
noDataBooleanif this is true, there is no data associated with this request.
categoriesArray of StringCategories of the chart, in increasing order
seriesArray of DashboardResponse_seriesChart Data

Dashboard Data Series

JSON ItemData TypeDescription
labelStringLabel of the Row.
valuesArray of DashboardResponse_valuesValues of the Series

Dashboard Data Values

JSON ItemData TypeDescription
labelStringLabel for this series value.
typeStringWhen you are using a Range reducer and there is more than one value provided, the label will be duplicated and will have a series for each of the types.
valuesArray of DoubleCategory value for this series correlating to the category index in the global object. You will need to overlay the nulls array on this.
nullsArray of BooleanFor any category value for this series which is null, there will be a true in this array. This array may not be present.

Errors

JSON ItemData TypeDescription
error_descriptionStringDescription of the error for end-user consumption.

Items

Given a TaskType, this is the representation of the data behind it.

Common

JSON ItemData TypeDescription
providerTypeStringAn enumeration of the Provider Type for uploading data to this API.
dateLongTime in milliseconds since the Epoch in UTC
itemIdStringId of the item
taskIdStringId of the Source Data
commentStringComment associated with the data.
tagsArray of StringUser tag
typeStringEnumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature

Activity

This describes an activity. It extends Common where type equals Activity.

JSON ItemData TypeDescription
activityStringGeneral Summary of the Activity or Exercise Type, generally in one word.
fitnessSyncerActivityStringSimilar to the activity, however, the activity is the raw string from the service and fitnessSyncerActivity is the FitnessSyncer normalized activity
titleStringA human readable title of the activity.
distanceKMDoubleDistance of the Activity in KM. Use 0 if not applicable.
durationDoubleDuration in Seconds. Use 0 if not applicable.
caloriesIntegerCalories Burned
bmrIntegerBasal Metabolic Rate
endDateLongEnd Time in milliseconds since the Epoch in UTC (if not summary)
stepsIntegerNumber of steps for this activity.
avgHeartrateIntegerAverage heart rate for the activity.
minHeartrateIntegerMinimum heart rate for the activity.
maxHeartrateIntegerMaximum heart rate for the activity.
restingHeartrateIntegerResting heart rate for the activity.
avgStressLevelIntegerAverage Stress Level
minStressLevelIntegerMinimum Stress Level
maxStressLevelIntegerMaximum Stress Level
lowStressDurationSecondsIntegerSeconds Under Low Sttress
mediumStressDurationSecondsIntegerSeconds Under Medium Stress
highStressDurationSecondsIntegerSeconds Under High Stress
vo2MaxIntegerVO2Max Level
respiratoryRateDoubleRespiratory Rate
mindfulMinutesIntegerMindful Minutets
summaryBooleanIf this is a daily summary snapshot, this will be true. Generally when this is true, the date of the item will also be at midnight UTC of that date.
temperatureCelsiusDoubleAverage Temperature in Celsius
repetitionsIntegerNumber of repetitions, especially for things like Push-Ups
weightDoubleWeights used for the exercise in KG
manualBooleanTrue if this was manually entered; false if not know or was not.
floorsClimbedIntegerApproximate Number of Floors Climbed
gpsGPSData
providerTypeStringAn enumeration of the Provider Type for uploading data to this API.
dateLongTime in milliseconds since the Epoch in UTC
itemIdStringId of the item
taskIdStringId of the Source Data
commentStringComment associated with the data.
tagsArray of StringUser tag
typeStringEnumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature

GPSData

JSON ItemData TypeDescription
idStringId of the GPS Event
titleStringTitle of the Stream
sportStringSport
dateLongDate of the event as a long of the number of milliseconds since the Epoch in UTC
lapArray of Lap

Lap

JSON ItemData TypeDescription
startLongStart time of this Lap in milliseconds since the Epoch in UTC
millisIntegerDuration in milliseconds
totalMovingTimeMillisIntegerMoving Time in milliseconds (if specified)
totalMovingTimeMillisCalcIntegerThis will either be equal to totalMovingTimeMillis or be the version we have calculated. This is a read-only field.
distIntegerDistance in Meters
caloriesIntegerCalories Expended for this Lap
speedDoubleSpeed in Meters per Second
maxHeartDoubleMaximum heart rate in this Lap
avgHeartDoubleAverage heart rate in this Lap
cadenceDoubleCadence for this Lap
sportStringOnly specified if different than the GPSData sport or a multisport activity.
notesDoubleNotes for this Lap
hrrDoubleHeart Rate Recovery
pointsArray of Point

Point

JSON ItemData TypeDescription
timeLongTime of this event in milliseconds since the epoch in UTC
distanceDoubleDistance in Meters
pointLatLng
altitudeDoubleAltitude in meters
heartRateDoubleHeart rate in beats per minute at this time
speedDoubleSpeed in meters per second
cadenceDoubleCadence
caloriesDoubleCalories Burned
hrvArray of Double
hrv_sdnnDoubleHeart Rate Variability in SDNN
powerDoublePower in Watts
estimatedPowerDoubleEstimated Power in Watts
tempDoubleTemperature in Celsius
stepsDoubleSteps moved up-to this point from the last point.
torqueDoubleTorque
locationAccuracyDoubleRating of the location accuracy
bearingDoubleBearings in Radians
tiltDoubleTilt in Radians
pedometerCadenceDoubleCurrent Cadence
crankCadenceDoubleCrank Cadence
crankRevolutionDeltaIntegerCrank Revolution Delta
wheelCadenceDoubleWheel Cadence
wheelRevolutionDeltaIntegerWheel Revolution Delta
movingBooleanTrue if this is considered to be in motion.
stanceTimeDoubleStance Time
legSpringStiffnessDoubleLeg Spring Stiffness
stressDoubleStress
formPowerDoubleForm Power
verticalOscilationDoubleVertical Oscillation
vo2MaxDoubleVO2 Max
respiratoryRateDoubleRespiratory Rate

LatLng

JSON ItemData TypeDescription
latDoubleLatitude
lngDoubleLongitude

Allergy

This describes an allergy. It extends Common where type equals Allergy.

JSON ItemData TypeDescription
allergyStringAllergy Name
isNegatedBooleanTrue if the treatment negates the allergy
treatmentStringTreatment of allergy
endDateLongTime in milliseconds since the Epoch in UTC of when this medication was last used. 0 implies that it is ongoing.
providerTypeStringAn enumeration of the Provider Type for uploading data to this API.
dateLongTime in milliseconds since the Epoch in UTC
itemIdStringId of the item
taskIdStringId of the Source Data
commentStringComment associated with the data.
tagsArray of StringUser tag
typeStringEnumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature

Weight

This describes a body composition record. It extends Common where type equals Weight.

JSON ItemData TypeDescription
weightDoubleWeight in KG
heightDoubleHeight in Meters
fatFreeMassDoubleFat Free Mass in KG
fatRatioDoubleFat Ratio
boneMassDoubleBone Mass in KG
bodyWaterKgDoubleBody Water in KG
bmiDoubleBody Mass Index. May be calculated if the User Preferences has the user's height.
muscleMassDoubleMuscle Mass in KG
fatMassWeightDoubleFat Mass Weight in KG
caliperChestDoubleChest Caliper in MM
caliperMidaxillaryDoubleMidaxillary Caliper in MM
caliperBicepDoubleBicep Caliper in MM
caliperAbdominalDoubleAbdominal Caliper in MM
caliperSuprailiacDoubleSuprailiac Caliper in MM
caliperThighDoubleThigh Caliper in MM
caliperCalfDoubleCalf Caliper in MM
caliperSubscapularDoubleSubscapular Caliper in MM
caliperTricepDoubleTricep Caliper in MM
caliperLowerBackDoubleLower Back Caliper in MM
providerTypeStringAn enumeration of the Provider Type for uploading data to this API.
dateLongTime in milliseconds since the Epoch in UTC
itemIdStringId of the item
taskIdStringId of the Source Data
commentStringComment associated with the data.
tagsArray of StringUser tag
typeStringEnumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature

Blood Pressure

This describes a blood pressure record. It extends Common where type equals BloodPressure.

JSON ItemData TypeDescription
diastolicDoubleDiastolic Blood Pressure
systolicDoubleSystolic Blood Pressure
pulseDoublePulse at the time of the reading
arrhythmiaBooleanTrue if Arrhythmia was detected in this reading.
providerTypeStringAn enumeration of the Provider Type for uploading data to this API.
dateLongTime in milliseconds since the Epoch in UTC
itemIdStringId of the item
taskIdStringId of the Source Data
commentStringComment associated with the data.
tagsArray of StringUser tag
typeStringEnumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature

Cholesterol

This describes a cholesterol. It extends Common where type equals Cholesterol.

JSON ItemData TypeDescription
ldlDoubleLDL Cholesterol in mmol per Liter
hdlDoubleHDL Cholesterol in mmol per Liter
totalCholesterolDoubleTotal Cholesterol in mmol per Liter
triglycerideDoubleTriglyceride in mmol per Liter
providerTypeStringAn enumeration of the Provider Type for uploading data to this API.
dateLongTime in milliseconds since the Epoch in UTC
itemIdStringId of the item
taskIdStringId of the Source Data
commentStringComment associated with the data.
tagsArray of StringUser tag
typeStringEnumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature

Condition

This describes a condition. It extends Common where type equals Condition.

JSON ItemData TypeDescription
conditionStringCondition Name
endDateLongTime in milliseconds since the Epoch in UTC of when this medication was last used. 0 implies that it is ongoing.
providerTypeStringAn enumeration of the Provider Type for uploading data to this API.
dateLongTime in milliseconds since the Epoch in UTC
itemIdStringId of the item
taskIdStringId of the Source Data
commentStringComment associated with the data.
tagsArray of StringUser tag
typeStringEnumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature

Glucose

This describes a glucose record. It extends Common where type equals Glucose.

JSON ItemData TypeDescription
valueDoubleGlucose Read in mmol per Liter
a1cBooleanTrue if the value was derived from an A1C
measurementTypeStringDescription of the Context, such as whole blood or plasma
measurementContextStringDescription of the Context, such as Before Breakfast
entriesArray of GlucosePointIn order to scale, we recommend grouping data per hour. These are the finer grained elements.
providerTypeStringAn enumeration of the Provider Type for uploading data to this API.
dateLongTime in milliseconds since the Epoch in UTC
itemIdStringId of the item
taskIdStringId of the Source Data
commentStringComment associated with the data.
tagsArray of StringUser tag
typeStringEnumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature

GlucosePoint

This describes a glucose entry.

JSON ItemData TypeDescription
timeLongTime in milliseconds since the Epoch in UTC
valueDoubleGlucose Read in mmol per Liter

Medication

This describes a medication record. It extends Common where type equals Medication.

JSON ItemData TypeDescription
medicationStringMedication Name
doseDoubleThe dose amount of this medication
doseUnitStringThe dose unit amount for this type. Must be one of: ML, MG, MCG, MGML, Tablet.
strengthDoubleThe strength amount of this medication
strengthUnitStringThe strength unit amount for this type. Must be one of: ML, MCG, MG, MGML
endDateLongTime in milliseconds since the Epoch in UTC of when this medication was last used. 0 implies that it is ongoing.
providerTypeStringAn enumeration of the Provider Type for uploading data to this API.
dateLongTime in milliseconds since the Epoch in UTC
itemIdStringId of the item
taskIdStringId of the Source Data
commentStringComment associated with the data.
tagsArray of StringUser tag
typeStringEnumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature

Nutrition

This describes a nutrition record. It extends Common where type equals Nutrition.

JSON ItemData TypeDescription
foodStringDescription of the Food Eaten
mealStringMeal that this was eaten at, typically Breakfast, Lunch, Dinner, Snack, or Other
mealApproximationStringBased on the time, this is FitnessSyncer's best approximation of the meal time
caloriesDoubleNumber of calories in this meal. This field is required if Water is not present.
carbohydratesDoubleCarbohydrates in Grams
fatDoubleFat in Grams
fiberDoubleFiber in Grams
proteinDoubleProtein in Grams
sugarDoubleSugar in Grams
cholesterolDoubleCholesterol in Grams
saturatedFatDoubleSaturated Fat in Grams
sodiumDoubleSodium in milligrams
ironDoubleIron in milligrams
potassiumDoublePotassium in milligrams
vitaminADoubleVitamin A in IU
vitaminCDoubleVitamin C in grams
vitaminDDoubleVitamin D in IU
calciumDoubleCalcium in grams
glycemicLoadIntegerGlycemic Load
waterDoubleNumber of Fluid Ounces of Water Consumed. This field is required if Calories is not present.
providerTypeStringAn enumeration of the Provider Type for uploading data to this API.
dateLongTime in milliseconds since the Epoch in UTC
itemIdStringId of the item
taskIdStringId of the Source Data
commentStringComment associated with the data.
tagsArray of StringUser tag
typeStringEnumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature

Oxygen

This describes an oxygen record. It extends Common where type equals Oxygen.

JSON ItemData TypeDescription
spo2DoubleSpO2 Reading in Percent
pulseDoublePulse Reading in BPM
entriesArray of OxygenPointIn order to scale, we recommend grouping data per hour. These are the finer grained elements.
providerTypeStringAn enumeration of the Provider Type for uploading data to this API.
dateLongTime in milliseconds since the Epoch in UTC
itemIdStringId of the item
taskIdStringId of the Source Data
commentStringComment associated with the data.
tagsArray of StringUser tag
typeStringEnumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature

OxygenPoint

This describes an oxygen entry.

JSON ItemData TypeDescription
timeLongTime in milliseconds since the Epoch in UTC
spo2DoubleSpO2 Reading in Percent
pulseDoublePulse Reading in BPM

Sleep

This describes a sleep record. It extends Common where type equals Sleep.

JSON ItemData TypeDescription
bedTimeLongBed Time in Milliseconds Since Epoch in UTC
awakeTimeLongAwake Time in Milliseconds Since Epoch in UTC
sleepingMinutesIntegerNumber of minutes actually asleep
awakeningsIntegerNumber of times awoken
efficiencyIntegerEfficiency of the Sleep as a Percentage
sleepEventsArray of SleepEventActual Sleep Events
inferredSleepEventsArray of SleepEventIf Actual Sleep Events are not available, FitnessSyncer will provide inferred Sleep Events. This is a read-only parameter.
sleepPointsArray of SleepPoint
settlingMinutesIntegerNumber of Minutes it took to Settle In
lightSleepMinutesIntegerNumber of Minutes in Light Sleep
l2SleepMinutesIntegerNumber of Minutes in L2 Sleep
l3SleepMinutesIntegerNumber of Minutes in L3 Sleep
deepSleepMinutesIntegerNumber of Minutes in Deep Sleep
remSleepMinutesIntegerNumber of Minutes in REM Sleep
awakeMinutesIntegerNumber of Minutes awake.
avgHRDoubleAverage Heart Rate during Sleep
avgRRDoubleAverage Respiratory Rate during Sleep
hrvRmssdEveningDoubleHRV RMSSD when going to Sleep
hrvRmssdMorningDoubleHRV RMSSD when waking up
providerTypeStringAn enumeration of the Provider Type for uploading data to this API.
dateLongTime in milliseconds since the Epoch in UTC
itemIdStringId of the item
taskIdStringId of the Source Data
commentStringComment associated with the data.
tagsArray of StringUser tag
typeStringEnumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature

SleepEvent

JSON ItemData TypeDescription
typeStringSleep Stage. Must be one of: LIGHT_SLEEP, ASLEEP, AWAKE, REALLY_AWAKE, REM.
offsetMinutesDoubleMinute within the sleep this started.
durationMinutesDoubleNumber of minutes that this event lasts for.

SleepPoint

JSON ItemData TypeDescription
timeLongTime in milliseconds since the Epoch in UTC
heartRateDoubleHeart rate in beats per minute at this time
respiratoryRateDoubleRespiratory Rate
hrv_sdnnDoubleHeart Rate Variability in SDNN

Temperature

This describes a temperature record. It extends Common where type equals Temperature.

JSON ItemData TypeDescription
temperatureDoubleTemperature Reading in Celsius
entriesArray of TemperaturePointIn order to scale, we recommend grouping data per hour. These are the finer grained elements.
providerTypeStringAn enumeration of the Provider Type for uploading data to this API.
dateLongTime in milliseconds since the Epoch in UTC
itemIdStringId of the item
taskIdStringId of the Source Data
commentStringComment associated with the data.
tagsArray of StringUser tag
typeStringEnumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature

TemperaturePoint

This describes a temperature entry.

JSON ItemData TypeDescription
timeLongTime in milliseconds since the Epoch in UTC
valueDoubleTemperature Reading in Celsius

Daily Summary Data

Activities serve both as an event and a daily aggregation of data. The difference is the summary flag. For items where the summary flag is enabled, the date associated with that item should be midnight UTC. The data should be the daily summary. Only one summary per day is allowed. When uploading, you must send the entire data not just the delta.

Character Sets

All requests to FitnessSyncer should be in the UTF-8 character set.

Language

FitnessSyncer accepts and supports the Accept-Language header and will produce the appropriate content for the user.

Compression

To save on bandwidth, you may request GZIP content. For downloads, include the Accept-Encoding: gzip header and include Content-Encoding: gzip header for uploads.

Edge Cases

You should URL encode the itemId that is sent as part of a URL in the cases that there are spaces, slashes, or other characters in it.

Rate Limits

FitnessSyncer may enforce rate limits based on your use-case. When a rate limit is exceeded, an HTTP Error Code of 429 will be returned; this response may include a Retry-After but is not guaranteed to, and if it is missing, you should retry after some time.

If you encounter regular rate limits, please contact us and we can assist in you adjusting your code to not encounter the issue or raise the limit.

Errors

The Error type is returned with each error, which includes an error_description. Here is a sample error:

{"error_description": "providerType not specified."}

If you encounter regular problems with a request, you should send us the date and x-fs-srvr-id headers so that we can investigate.

All 500 errors should be retried with exponential backoff.

FitnessSyncer changes DNS configuration to control certain aspects of our availability. Please ensure that your system does not cache DNS entries beyond our DNS TTL configuration. Failure to do so may result in request failures which are not covered by out SLA.

Future Proofing

This API will change over time. In general, the API will be augmented with new functionality and parameters. You should ignore any data for which your application does not presently understand.

In the event that the API must be changed in a non-backwards compatible way, you will be notified via the e-mail address registered with us.

It should also be noted that validation might change over time, which may introduce new errors in your application. Regular testing is encouraged.

Developer Support

Developer support can be done via our normal support process of contacting us.