In order to continue adding functionality, we regularly make improvements and changes to our API. The majority of changes are backwards compatible and should not affect your applications. When we need to release a breaking change, we will do so in a new API version that you can manually upgrade to. All changes will be detailed in the Changelog.
We consider the following types of changes to be backwards compatible. You should ensure your code is robust enough to gracefully handle the following changes:
- Adding new API resources.
- Adding new optional request parameters to existing API methods, using sensible defaults if not present in requests.
- Adding new fields to existing API responses.
- Changing the order of fields in existing API responses.
- Changing the length or format of opaque strings, such as object IDs, error messages, and human-readable strings.
- Adding new values to an existing enum.
When we make backwards-incompatible changes to the API we will release a new dated version, e.g.
2023-04-18. You can toggle between versions in the top-left corner of our documentation. You must send a
Pinwheel-Version header with each request to specify which version that request should be using. To upgrade your API version, use the relevant version date for the
Pinwheel-Version header of your request. See Version Headers on the API page for more information.
Pinwheel will occasionally sunset old API versions, which means they will no longer be available for use. Before we sunset a version, we will mark it as deprecated no fewer than six months before it is removed from our system. Plans to deprecate or sunset a version will be communicated to you by our customer success team. They will also be detailed in the Changelog.
Making a request to a sunsetted version will result in a
400 Bad Request error.
We will also release a new dated version when we make backwards-incompatible changes to our webhook events. This policy began with 2023-04-18. You can access webhook event docs for each API version via the dropdown in the top bar (e.g., "2022-03-02"). For more information on creating webhooks with a specified version, see the Webhooks guide.
Listed below are all the breaking changes introduced in the Pinwheel API. For a full list of upgrades, enhancements, and new features, see the Changelog.
params.actionfield in the direct_deposit_switch.added webhook event and Get Jobs response is now optional.
- The Create Link Token request now requires an
account_idis not provided.
- Accrued and processed earnings in the Get Earnings Stream Payouts endpoint have been replaced with a uniform structure. A confidence score is attached to every earnings, signaling Pinwheel's confidence in the earning amount.
- The Create Link Token request now takes an
allocationobject containing a
valuethat define its attributes. An allocation will also contain a list of
targets, allowing you to specify a list of accounts that the user can choose from when making their direct deposit switch.
paramsfield in the Get Jobs response for
direct_deposit_switchjobs will now include more specific detail on both the direct deposit switch action and the allocation type.
paramsfield in the direct_deposit_switch.added webhook event will now include more specific detail on both the direct deposit switch action and the allocation type.
- List endpoints now use cursor-pagination. See the Pagination guide for more information on how to integrate with these endpoints.
direct_deposit_paymentjob has been replaced with the
direct_deposit_paymentfunctionality is encompassed in the
direct_deposit_switchjob. Specification of this job type in the
required_jobslist for link token creation will result in a 400 status code.
(Deprecated, scheduled for sunset on 2/11/24) 2021-07-28
expiresfield in the response from Create Link Token is now an ISO-8601formatted timestamp string, bringing it inline with our API Conventions.
- The responses from Create Link Token no longer include the redundant
token_idfield. Use the
idfield directly instead.
- The request payloads for Create Link Token no longer accepts the scalar field
required_jobs, which supports an array of job types, instead.
Sunsetted: Discontinued and no longer available for usage.
Deprecated: Functional, but usage is discouraged. It is scheduled to be sunsetted.