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.
The data will be filtered based on the scopes provided; not all of the scopes listed are required.
Example request
curl -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/providers/sources/id/items/"Request Parameters
| Query Parameter Name | Description |
|---|---|
| startDate | Which date should we start from? This would be in milliseconds since the epoch. Default is to not use the date. |
| endDate | Which date should we end at? This would be in milliseconds since the epoch. Default is to not use the date. |
| offset | How many entries should we skip? Default is 0. |
| limit | How many entries would you like to return? Default and max is 100. |
| summary | When true, each entry carries only its itemId, date, and links rather than the whole item. The full item carries the same links. Default is false. |
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.
Each entry carries a links object; see Downloading Item Files.
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.
The data will be filtered based on the scopes provided; not all of the scopes listed are required.
Example request
curl -H "Authorization: Bearer AccessToken" "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.
Downloading Item Files
Whether you read an item from Listing Items or from Getting a Specific Item, and whether or not you asked for the summary form, it carries the same links object of absolute URLs for downloading that item as a file.
Which keys are present depends on what the item can be rendered as, and the object is absent entirely when there is nothing to download. Treat every key as optional and check for it rather than assuming a fixed set.
Fetch a URL with the same Authorization Bearer token you used for the item itself. It requires the source_data_activity_read scope regardless of the item’s own type, so a token holding only, say, source_data_sleep_read will be refused with a 403 on a sleep item’s FIT link.
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.
The appropriate scope must be granted for the TaskType selected for the operation to succeed.
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.
The appropriate scope must be granted for the TaskType selected for the operation to succeed.
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-”.
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.
The appropriate scope must be granted for the TaskType selected for the operation to succeed.
Fields
| JSON Item | Data Type | Description |
|---|---|---|
| file | String | File in one of the supported file formats. |
Fields
| JSON Item | Data Type | Description |
|---|---|---|
| items | Array of Object | Uploaded Item(s) |
| review | Object | Present when the document was taken as a laboratory or body composition report and is waiting for the person to check what was read out of it. Nothing has been stored yet, so `items` is empty: open this URL and the person confirms, corrects or discards what was read, and keeping it is what creates the item. It carries the answer whatever the answer is, so a document we would not read and one we could not make sense of arrive here too, each saying so in the person’s own language rather than as an error you have to word yourself. |
Fields of items
| JSON Item | Data Type | Description |
|---|---|---|
| id | String | id of the newly uploaded item |
| url | String | URL for more information |
Fields of review
| JSON Item | Data Type | Description |
|---|---|---|
| url | String | Where the person checks what was read, relative to the site as the item urls above are. Open it promptly and do not keep it: the reading it holds lives in a cache and expires, and it is not stored anywhere until the person keeps it. It is a page, so the person is signed in on the web to see it. Our own apps hand off to it with a one-time token instead, the way they do for the CSV column mapping, which is why it is a path rather than a whole URL. |
Request Parameters
The Body is a multipart-form that contains an element named as file which encompasses a TCX, GPX, KML, KMZ, FIT, PWX, or PDF 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.
A laboratory or body composition report that no parser recognizes, such as a PDF from a laboratory or an imaging center, is stored as the item’s attachment and nothing is read out of it. To have its results read instead, include the labExtract=true query string parameter, which is the person’s explicit agreement that the text of that document may be sent to our language model provider. Sending it requires a Notebook write scope and answers 401 without one: uploading the file needs no scope and still does not, because reading it is the part that spends the person’s monthly allowance and sends their report.
Only send it when the person has agreed to it for the document in hand. Tell them what leaves, where it goes, and that nothing is stored until they keep it. Do not keep the answer as a setting and apply it to the next document.
The agreement is about the sending, so it changes nothing for a file we read ourselves. A FHIR, C-CDA, CSV or workout file is parsed here and never leaves, whatever you send, and a report whose own text already answers the question is read here too.
Response
The Response will be a JSON body with a list of items; each item will include an id and url for the item.
A document that was read instead carries a review object holding a url, and the list of items is empty, because nothing is stored until the person checks what was read. It is relative to the site, as the item URLs are, and it is a page, so the person is signed in on the web to see it. Open it promptly and do not keep it: the reading it holds lives in a cache and expires. It carries the answer whatever the answer is, so a document we would not read and one we could not make sense of arrive there too, each saying so in the person’s own language.
A spent monthly allowance for reading documents is a 429, which is worth offering again without labExtract because the file is stored either way.
Deleting Items
The appropriate scope must be granted for the TaskType selected for the operation to succeed.
Example request
curl -X DELETE -H "Authorization: Bearer AccessToken" "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.
