The Pinwheel API is built on RESTful principles. All request and response payloads are encoded in JSON. For security purposes, all requests must be sent via HTTPS. To get access to the [Developer Dashboard](🔗) and interface with the API, please contact [[email protected]](🔗).
The API is available in three modes that can be accessed by sending requests to different servers. Each API Key you are granted will be associated with a single mode.
|**sandbox**||<https://sandbox.getpinwheel.com>||Use Sandbox mode to build and test your integration. In this mode, you must use [test credentials](🔗) to authenticate with payroll platforms. All API endpoints will return mock data and no actual updates are made to any payroll account.|
|**development**||<https://development.getpinwheel.com>||Development mode can be used to test your integration before going live in Production. In this mode, you use real credentials to authenticate with payroll platforms. API endpoints return real data and updates are made to payroll accounts.|
|**production**||<https://api.getpinwheel.com>||Use Production mode to go live with your integration. Your users will use their login credentials to authenticate with their payroll accounts. API endpoints return real data and updates are made to payroll accounts. Note that in this mode, all API calls are billable.|
You can access the API Keys and Secrets for each mode in the [Developer Dashboard](🔗).
Your **API Key** is a unique identifier used by Pinwheel for logging and troubleshooting. Your **API secret** must be included in all requests to the API via a custom HTTP header. You will have a different API Secret for each mode.
|`||Your API Secret|
Our API accepts JSON-encoded requests. You must include a `
Content-Type` header with the value `
application/json` whenever you submit data in the request body, e.g., [POST /v1/link_tokens](🔗).
The Pinwheel API supports different behavior depending on the API version requested. You must send a `
Pinwheel-Version` header with each request to specify how the Pinwheel API should behave. You can find the latest API version on the [Change Management](🔗) page. If no header is specified the Pinwheel API will default to the deprecated version **2021-04-29**. Once version **2021-04-29** is sunsetted, requests without a `
Pinwheel-Version` header will return a `
400 Bad Request` error.
Responses from the Pinwheel API will include a `
Pinwheel-Version` header specifying which API version was used to process the request.
For more details, see [Versioned Changes](🔗) in the [Change Management](🔗) page.
There are a number of important objects in Pinwheel's systems. It is particularly useful to store the identifiers for [Accounts](🔗), [Link Token](🔗), and [Jobs](🔗). These identifiers will help you optimize your Pinwheel integration, troubleshoot issues, and reconcile billing.
In addition to these Pinwheel identifiers, you can incorporate your existing user model into Pinwheel by providing your own internal user identifier, `
end_user_id`, when you initiate an account connection. Please note this should be a unique identifier that does not contain any end-user PII. See [User Model](🔗) for more.
|Object||Description||Where to find it|
|`||UUID of each payroll account. Store the `||It is returned in Link via the `|
|`||UUID of a given Link token. Store the `||It is returned as `|
|`||UUID of a given job. Can be helpful for troubleshooting job specific issues.||It is returned in Link-initiated [Webhook](🔗) payloads and can be found by querying the [Jobs](🔗) endpoint.|
|`||The end-user identifier provided to Pinwheel by the customer specified through a parameter in the [Create Link Token](🔗) endpoint. `||`|
Every Pinwheel response will contain a unique request identifier. We recommend logging this request identifier to be used for troubleshooting.
All responses are encoded in JSON and return an object with the key `
data`. If the response is a single object, the value of the `
data` key is that object. For example, the [Get Employment](🔗) endpoint will return a single `
If the response is a collection, the value of the `
data` key is an array of objects. A `
meta` key is also returned with metadata about the response. For example the [List Platforms](🔗) endpoint will return a collection of `
## Status Codes
Pinwheel API responses use standard [HTTP Status Codes](🔗).
|204||No Content||The request was successfully processed and no content was returned.|
|307||Temporary Redirect||Redirection to another URI.|
|400||Bad Request||The request was invalid or cannot be served. The accompanying error type, code, and message will explain further.|
|401||Unauthorized||Missing or incorrect authentication credentials.|
|403||Forbidden||The request is understood, but it has been refused or access is not allowed. An accompanying error message and code will explain why.|
|404||Not Found||The requested resource could not be found.|
|429||Too Many Requests||Pinwheel is receiving too many requests from you. Slow down your request rate. We recommend retrying with an [exponential backoff strategy](🔗).|
|500||Internal Server Error||An unexpected error occurred. Try again later.|
|502||Bad Gateway||Pinwheel is down or being upgraded.|
|503||Service Unavailable||The Pinwheel servers are up, but overloaded with requests. Try again later.|
|504||Gateway Timeout||The Pinwheel servers are up, but the request could not be completed. Try again later.|
# Rate Limiting
Pinwheel uses rate limiting to safeguard our system against excessive traffic to maximize stability. If your application sends too many requests in quick succession, you may see error responses with a `
429` status code. Unless specifically noted, Pinwheel allows 50 queries per second on all API endpoints.
Please structure your application calls to avoid hitting these limits. If you do receive a `
429` response, we recommend retrying with an [exponential backoff strategy](🔗).
Some conventions used throughout our API are:
All dates and datetimes are returned as [ISO-8601](🔗) strings in UTC Timezone, e.g., `
Object IDs are represented as UUIDs, e.g., `
To avoid any potential loss of precision when parsing response payloads, all financial values are represented in the smallest common currency unit along with the ISO 4217 currency code. For example, $292.23 is represented as `
29223` with a currency code of `
Please contact [[email protected]](🔗) for access to our [Developer Dashboard](🔗).