# Overview
The Fitbit Plus API is a RESTful API. The requests and responses are formated according to the
[JSON API](http://jsonapi.org/format/1.0/) specification.
In addition to this documentation, we also provide an
[OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) "yaml" file describing the API:
[Fitbit Plus API Specification](swagger.yaml).
# Authentication
Authentication for the Fitbit Plus API is based on the
[OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749). Fitbit Plus currently supports grant
types of **client_credentials** and **refresh_token**.
See [POST /oauth/token](#operation/createToken) for details on the request and response formats.
## Building Integrations
We will provide customers with unique client credentials for each application/integration they build, allowing us
to enforce appropriate access controls and monitor API usage.
The client credentials will be scoped to the organization, and allow full access to all patients and related data
within that organization.
These credentials are appropriate for creating an integration that does one of the following:
- background reporting/analysis
- synchronizing data with another system (such as an EMR)
The API credentials and oauth flows we currently support are **not** well suited for creating a user-facing
application that allows a user (patient, coach, or admin) to login and have access to data which is appropriate to
that specific user. It is possible to build such an application, but it is not possible to use Fitbit Plus as a
federated identity provider. You would need to have a separate means of verifying a user's identity. We do not
currently support the required password-based oauth flow to make this possible.
# Paging
The Fitbit Plus API supports two different pagination strategies for GET collection endpoints.
#### Skip-based paging
Skip-based paging uses the query parameters `page[size]` and `page[number]` to specify the max number of resources returned and the page number. We default to skip-based paging if there are no page parameters. The response will include a `links` object containing links to the first, last, prev, and next pages of data.
If the contents of the collection change while you are iterating through the collection, you will see duplicate or missing documents. For example, if you are iterating through the `calender_event` resource via `GET /pub/calendar_event?sort=start_at&page[size]=50&page[number]=1`, and a new `calendar_event` is created that has a `start_at` value before the first `calendar_event`, when you fetch the next page at `GET /pub/calendar_event?sort=start_at&page[size]=50&page[number]=2`, the first entry in the second response will be a duplicate of the last entry in the first response.
#### Cursor-based paging
Cursor-based paging uses the query parameters `page[limit]` and `page[after]` to specify the max number of entries returned and identify where to begin the next page. Add `page[limit]` to the parameters to use cursor-based paging. The response will include a `links` object containing a link to the next page of data, if the next page exists.
Cursor-based paging is not subject to duplication if new resources are added to the collection. For example, if you are iterating through the `calender_event` resource via `GET /pub/calendar_event?sort=start_at&page[limit]=50`, and a new `calendar_event` is created that has a `start_at` value before the first `calendar_event`, you will not see a duplicate entry when you fetch the next page at `GET /pub/calendar_event?sort=start_at&page[limit]=50&page[after]=
The Benefits Intake API allows authorized third-party systems used by Veteran Service Organizations (VSOs), agencies, and Veterans to digitally submit VA benefits claim documents directly to the Veterans Benefits Administration's (VBA) claims intake process. This API handles documents related to the following benefit claim types:
* Compensation
* Pension/Survivors Benefits
* Education
* Fiduciary
* Insurance
* Veteran Readiness & Employment (VRE)
* Board of Veteran Appeals (BVA)
This API also provides submission status updates until documents are successfully established for VBA claim processing, eliminating the need for users to switch between systems to manually check whether documents have been successfully uploaded.
## Background
This API provides a secure, efficient, and tracked alternative to mail or fax for VA benefit claim document submissions. Documents are uploaded directly to the VBA so they can be processed as quickly as possible.
## Technical overview
The Benefits Intake API first provides an upload location and unique submission identifier, and then accepts a payload consisting of a document in PDF format, zero or more optional attachments in PDF format, and some JSON metadata.
The metadata describes the document and attachments, and identifies the person for whom it is being submitted. This payload is encoded as binary multipart/form-data (not base64). The unique identifier supplied with the payload can subsequently be used to request the processing status of the uploaded document package.
To avoid errors and processing delays, API consumers are encouraged to validate the `zipcode`,`fileNumber`, `veteranFirstName`, `veteranLastName` and `businessLine` fields before submission according to their description in the DocumentUploadMetadata model and use the 'businessLine' attribute for the most efficient processing. Additionally, please ensure no PDF user passwords are used in submitted PDFs.
### Attachment & file size limits
There is no limit on the number of files a payload can contain, but size limits do apply.
* Uploaded documents cannot be larger than 21" x 21"
* The entire payload cannot exceed 5 GB
* No single file in a payload can exceed 100 MB
### Date of receipt
The date that documents are successfully submitted through the Benefits Intake API is used as the official VA date of receipt. However, note that until a document status of `received`, `processing`, `success`, or `vbms` is returned, a client cannot consider the document received by VA.
A status of `received` means that the document package has been transmitted, but may not be validated. Any errors with the document package, such as unreadable PDFs or a Veteran not found, will cause the status to change to `error`.
If the document status is `error`, VA has not received the submission and cannot honor the submission date as the date of receipt.
### Authentication and Authorization
API requests are authorized through a symmetric API token, provided in an HTTP header with name 'apikey'. [Request an API key.](https://developer.va.gov/apply)
### Testing in the sandbox environment
In the sandbox environment, the final status of a submission is `received` and submissions do not actually progress to the central mail repository or VBMS.
Progress beyond the `received` status can be simulated for testing. We allow passing in a `Status-Override` header on the `/uploads/{id}` endpoint so that you can change the status of your submission to simulate the various scenarios.
The available statuses are `pending`, `uploaded`, `received`, `processing`, `success`, `vbms`, and `error`. The meaning of the various statuses is listed below in Models under DocumentUploadStatusAttributes.
### Test data
We use mock test data in the sandbox environment. Data is not sent upstream and it is not necessary to align submitted test data with any other systems' data.
### Validating documents
Use the POST `/uploads/validate_document` endpoint to make sure your documents will pass system file requirements and
validations before you send them through the submissions process. This step is optional but decreases the likelihood
of individual document errors during the submission process.
Validations performed:
* Document is a valid PDF (Note: `Content-Type` header value must be "application/pdf")
* Document does not have a user password (an owner password is acceptable)
* File size does not exceed 100 MB
* Page size does not exceed 21" x 21"
### Upload operation
Allows a client to upload a multi-part document package (form + attachments + metadata).
1. Client Request: POST https://sandbox-api.va.gov/services/vba_documents/v1/
* No request body or parameters required
2. Service Response: A JSON API object with the following attributes:
* `guid`: An identifier used for subsequent status requests
* `location`: A URL to which the actual document package payload can be submitted in the next step. The URL is specific to this upload request, and should not be re-used for subsequent uploads. The URL is valid for 900 seconds (15 minutes) from the time of this response. If the location is not used within 15 minutes, the GUID will expire. Once expired, status checks on the GUID will return a status of `expired`.
* Note: If, after you've submitted a document, the status hasn't changed to `uploaded` before 15 minutes has elapsed, we recommend retrying the upload in order to make sure the document properly reaches our servers. If the upload continues to fail, try encoding the payload as Base64 (See below).
3. Client Request: PUT to the location URL returned in Step 2.
* Request body should be encoded as binary multipart/form-data (base64 also available - see details below), equivalent to that generated by an HTML form submission or using "curl -F…". The format is described in more detail below.
* No `apikey` authorization header is required for this request, as authorization is embedded in the signed location URL.
4. Service Response: The HTTP status indicates whether the upload was successful.
* Additionally, the response includes an ETag header containing an MD5 hash of the submitted payload. This can be compared to the submitted payload to ensure data integrity of the upload.
### Status caching
Due to current system limitations, data for the `/uploads/report` endpoint is cached for one hour.
A request to the `/uploads/{id}` endpoint will return a real-time status for that GUID, and update its status in `/uploads/report`.
The `updated_at` field indicates the last time the status for a given GUID was updated.
### Document Submission Statuses
**Important note:** a submission has not been received by VA until it has a status of Received, Processing, Success,
or VBMS. Detailed descriptions of what each status means are found in this table.
| Status | What it means |
| --- | --- |
| **Pending** | Initial status.
Indicates no document package has been uploaded yet.
Date of Receipt is not yet established with this status |
| **Uploaded** | Indicates document package has been successfully uploaded (PUT) from your system to the API server but has not yet been validated.
Date of Receipt is not yet established with this status. Any errors with the document package, such as having an unreadable PDF, may cause an Error status. |
| **Received** | Indicates document package has been received upstream of the API and is awaiting Processing.
The VA Date of Receipt is set when this status is achieved.
This is the final status in the sandbox environment unless further progress is simulated. |
| **Processing**| Indicates the document package is being validated, processed, and made ready to route and work. |
| **Success** | Indicates the document package has been successfully received within VA's mail handling system.
Success is the final status for a small percentage of submitted packages with claim types, Veteran types, or exception processes that are not worked in VBMS. Most submissions reach a Success status within 1 business day. A small portion will take longer; however, some submissions may take up to 2 weeks to reach a Success status. |
| **VBMS** | Indicates this document package was successfully uploaded into a Veteran's eFolder within VBMS.
On average, submissions reach VBMS status within 3 business days; however, processing times vary and some submissions may remain in a Success status for several weeks before reaching a VBMS status.
Some document packages are worked in VA systems other than VBMS. For these submissions, Success is the final status. |
| **Error** | Indicates that there was an error. Refer to the error code and message for further information. |
| **Expired** | After a POST request, there is a 15-minute window during which documents must be uploaded via a PUT request.
An Expired status means the documents were not successfully uploaded within this 15-minute window. We recommend coding to retry unsuccessful uploads within 15 minutes using the same submission in case of connection issues. |
### Optional Base64 encoding
Base64 is an encoding scheme that converts binary data into text format, so that encoded textual data can be easily transported over networks uncorrupted and without data loss.
Base64 can be used to encode binary multipart/form-data it in its entirety. Note that the whole payload must be encoded, not individual parts/attachments.
After encoding your payload, you'll be required to preface your base64 string with `data:multipart/form-data;base64,` in order to allow our system to distinguish the file type. Your final string payload would look something like `data:multipart/form-data;base64,(encryption string)==` and close with the standard == marker. Note that the multipart boundaries i.e. -----WebKitFormBoundaryVfOwzCyvug0JmWYo and ending ------WebKitFormBoundaryVfOwzCyvug0JmWYo- must also be included.
### Consumer onboarding process
When you're ready to move to production, [request a production API key.](https://developer.va.gov/go-live)
The Veteran Confirmation API allows you to confirm Veteran status for a given person. This can be useful for offering Veterans discounts or other benefits. The API will only return “Confirmed” or “Not Confirmed”. ## Quickstart Guide ### 1. Get Access Credentials Get started by filling out the form on the [Apply for VA Lighthouse Developer Access](https://developer.va.gov/apply) page. After submitting a request, you will receive your credentials for using the API in the Development environment, which allows you to try it out with mock data before moving to the Production environment. ### 2. Test the API In the endpoint documentation below, we've provided a curl command builder for trying out the API before implementation with your app. Use [Test User](https://github.com/department-of-veterans-affairs/vets-api-clients/blob/master/test_accounts/confirmation_test_accounts.md) attributes to populate the request body. ### 3. Build your app The base URI for the Veteran Confirmation API in the Sandbox environment is: https://sandbox-api.va.gov/services/veteran_confirmation/v0 In this environment, use attributes from the list of [Test Users](https://github.com/department-of-veterans-affairs/vets-api-clients/blob/master/test_accounts/confirmation_test_accounts.md). Only Test Users can return a `"confirmed"` response. Check out some of our [sample apps](https://github.com/department-of-veterans-affairs/vets-api-clients). Please visit our VA Lighthouse [Support portal](https://developer.va.gov/support) should you need further assistance. ### 4. Show us a demo and get access to the Production environment After building your app, we ask that you give us a demo before we set you up with production credentials. Please see the [Path to Production](https://developer.va.gov/go-live) page for more details. ## Authorization This API requires an API key in combination with identifiable information for the person being confirmed listed below. API requests are authorized through a symmetric API token provided in an HTTP header with name `apikey`. Including more information has a better chance of making a match and returning a Confirmed status. ### Required information: * First Name * Last Name * Date of Birth * Social Security Number ### Optional information: * Middle Name * Gender ## Reference ### Sandbox vs. Production Data APIs accessed via the Sandbox environment are using the same underlying logic as VA’s production APIs; only the underlying data store is different. ### Master Veteran Index (MVI) The Master Veteran Index confirms a user's identity. In Production, several factors are considered to confirm identity. These include: a user’s first name, last name, date of birth and Social Security number. The MVI is mocked in the Sandbox environment. In this environment, the only factor used to confirm identity is the Social Security number. ### Rate Limiting We implemented basic rate limiting of 60 requests per minute. If you exceed this quota, your request will return a 429 status code. You may petition for increased rate limits by emailing and requests will be decided on a case by case basis. ### Raw Open API Spec https://api.va.gov/services/veteran_confirmation/docs/v0/api
## Background This RESTful API provides information about physical VA facilities. Information available includes geographic location, address, phone, hours of operation, and available services. VA operates several different types of facilities, the types represented in this API include: - Health Facilities (vha) - Benefits Facilities (vba) - Cemeteries (nca) - Vet Centers (vc) To read an FAQ on how wait times are calculated, click the "For more information" link on [this page](https://www.accesstocare.va.gov/PWT/SearchWaitTimes). ## Getting Started ### Base URLs The base URLs for the VA Facilities API in the various environments are: - Sandbox: `https://sandbox-api.va.gov/services/va_facilities/v0` - Production: `https://api.va.gov/services/va_facilities/v0` ### Authorization API requests are authorized through a symmetric API token, provided in an HTTP header with name `apikey`. ### Response Formats Clients may request several response formats by setting the `Accept` header. - `application/json` - The default JSON response format complies with JSON API. This media type is *not* available for bulk requests using the `/facilities/all` endpoint. It will return `406 Not Acceptable`. - `application/geo+json` - GeoJSON-compliant format, representing each facility as a feature with a point geometry. - `application/vnd.geo+json` - Deprecated. Prefer application/geo+json. - `text/csv` - Available for the bulk download operation only. Some structured fields are omitted from the CSV response. ### Response Elements Some data elements within the response are only present for facilities of a given type: - The patient satisfaction scores contained in the `satisfaction` element are only applicable to VA health facilities. - The patient wait time values contained in the `wait_times` element are only applicable to VA health facilities. - The list of available services in the `services` element is only applicable to VA health and benefits facilities. - The operational hours special instructions contained in the `operational_hours_special_instructions` element is only applicable to VA health and Vet Center facilities. ### Facility ID Formats and Constraints A facility ID has the format `prefix_stationNumber`. The prefix is one of nca, vc, vba, or vha. Cemeteries may be national (VA) or non-national; non-national cemeteries have the station number prefixed with an `s`. There are no other constraints on the format. Examples: - Health: `vha_402GA` - Benefits: `vba_539GB` - National cemetery: `nca_063` - Non-national cemetery: `nca_s1082` - Vet center: `vc_0872MVC` ### Mobile Facilities The mobile health facilities move regularly within a region. If a facility comes back from this API with `"mobile": "true"`, the latitude/longitude and address could be inaccurate. To get the exact current location, please call the number listed. ## Deprecations - `active_status` field is deprecated and replaced with `operating_status`. - `application/vnd.geo+json` media type is deprecated and replaced by `application/geo+json` ## Reference - [Raw VA Facilities Open API Spec](https://api.va.gov/services/va_facilities/docs/v0/api) - [GeoJSON Format](https://tools.ietf.org/html/rfc7946) - [JSON API Format](https://jsonapi.org/format/)
Use the VA Forms API to search for VA forms, get the form's PDF link and metadata, and check for new versions. Visit our VA Lighthouse [Contact Us page](https://developer.va.gov/support) for further assistance. ## Background This API offers an efficient way to stay up-to-date with the latest VA forms and information. The forms information listed on VA.gov matches the information returned by this API. - Search by form number, keyword, or title - Get a link to the form in PDF format - Get detailed form metadata including the number of pages, related forms, benefit categories, language, and more - Retrieve the latest date of PDF changes and the SHA256 checksum - Identify when a form is deleted by the VA ## Technical summary The VA Forms API collects form data from the official VA Form Repository on a nightly basis. The Index endpoint can return all available forms or, if an optional query parameter is passed, will return only forms that may relate to the query value. When a valid form name is passed to the Show endpoint, it will return a single form with additional metadata and full revision history. A JSON response is given with the PDF link (if published) and the corresponding form metadata. ### Authentication and authorization The form information shared by this API is publicly available. API requests are authorized through a symmetric API token, provided in an HTTP header with name apikey. [Get a sandbox API Key](https://developer.va.gov/apply). ### Testing in sandbox environment Form data in the sandbox environment is for testing your API only, and is not guaranteed to be up-to-date. This API also has a reduced API rate limit. When you're ready to move to production, be sure to [request a production API key.](https://developer.va.gov/go-live) ### SHA256 revision history Each form is checked nightly for recent file changes. A corresponding SHA256 checksum is calculated, which provides a record of when the PDF changed and the SHA256 hash that was calculated. This allows end users to know that they have the most recent version and can verify the integrity of a previously downloaded PDF. ### Valid PDF link Additionally, during the nightly refresh process, the link to the form PDF is verified and the `valid_pdf` metadata is updated accordingly. If marked `true`, the link is valid and is a current form. If marked `false`, the link is either broken or the form has been removed. ### Deleted forms If the `deleted_at` metadata is set, that means the VA has removed this form from the repository and it is no longer to be used.
## Terms and Definitions Throughout this document and the Velo platform the following terms are used: * **Payor.** An entity (typically a corporation) which wishes to pay funds to one or more payees via a payout. * **Payee.** The recipient of funds paid out by a payor. * **Payment.** A single transfer of funds from a payor to a payee. * **Payout.** A batch of Payments, typically used by a payor to logically group payments (e.g. by business day). Technically there need be no relationship between the payments in a payout - a single payout can contain payments to multiple payees and/or multiple payments to a single payee. * **Sandbox.** An integration environment provided by Velo Payments which offers a similar API experience to the production environment, but all funding and payment events are simulated, along with many other services such as OFAC sanctions list checking. ## Overview The Velo Payments API allows a payor to perform a number of operations. The following is a list of the main capabilities in a natural order of execution: * Authenticate with the Velo platform * Maintain a collection of payees * Query the payor’s current balance of funds within the platform and perform additional funding * Issue payments to payees * Query the platform for a history of those payments This document describes the main concepts and APIs required to get up and running with the Velo Payments platform. It is not an exhaustive API reference. For that, please see the separate Velo Payments API Reference. ## API Considerations The Velo Payments API is REST based and uses the JSON format for requests and responses. Most calls are secured using OAuth 2 security and require a valid authentication access token for successful operation. See the Authentication section for details. Where a dynamic value is required in the examples below, the {token} format is used, suggesting that the caller needs to supply the appropriate value of the token in question (without including the { or } characters). Where curl examples are given, the –d @filename.json approach is used, indicating that the request body should be placed into a file named filename.json in the current directory. Each of the curl examples in this document should be considered a single line on the command-line, regardless of how they appear in print. ## Authenticating with the Velo Platform Once Velo backoffice staff have added your organization as a payor within the Velo platform sandbox, they will create you a payor Id, an API key and an API secret and share these with you in a secure manner. You will need to use these values to authenticate with the Velo platform in order to gain access to the APIs. The steps to take are explained in the following: create a string comprising the API key (e.g. 44a9537d-d55d-4b47-8082-14061c2bcdd8) and API secret (e.g. c396b26b-137a-44fd-87f5-34631f8fd529) with a colon between them. E.g. 44a9537d-d55d-4b47-8082-14061c2bcdd8:c396b26b-137a-44fd-87f5-34631f8fd529 base64 encode this string. E.g.: NDRhOTUzN2QtZDU1ZC00YjQ3LTgwODItMTQwNjFjMmJjZGQ4OmMzOTZiMjZiLTEzN2EtNDRmZC04N2Y1LTM0NjMxZjhmZDUyOQ== create an HTTP **Authorization** header with the value set to e.g. Basic NDRhOTUzN2QtZDU1ZC00YjQ3LTgwODItMTQwNjFjMmJjZGQ4OmMzOTZiMjZiLTEzN2EtNDRmZC04N2Y1LTM0NjMxZjhmZDUyOQ== perform the Velo authentication REST call using the HTTP header created above e.g. via curl: ``` curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Basic NDRhOTUzN2QtZDU1ZC00YjQ3LTgwODItMTQwNjFjMmJjZGQ4OmMzOTZiMjZiLTEzN2EtNDRmZC04N2Y1LTM0NjMxZjhmZDUyOQ==" \ 'https://api.sandbox.velopayments.com/v1/authenticate?grant_type=client_credentials' ``` If successful, this call will result in a **200** HTTP status code and a response body such as: ``` { "access_token":"19f6bafd-93fd-4747-b229-00507bbc991f", "token_type":"bearer", "expires_in":1799, "scope":"..." } ``` ## API access following authentication Following successful authentication, the value of the access_token field in the response (indicated in green above) should then be presented with all subsequent API calls to allow the Velo platform to validate that the caller is authenticated. This is achieved by setting the HTTP Authorization header with the value set to e.g. Bearer 19f6bafd-93fd-4747-b229-00507bbc991f such as the curl example below: ``` -H "Authorization: Bearer 19f6bafd-93fd-4747-b229-00507bbc991f " ``` If you make other Velo API calls which require authorization but the Authorization header is missing or invalid then you will get a **401** HTTP status response.