API Change Management

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.

Backwards Compatible Changes

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.

Versioned Changes

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.

Sunsetting Versions

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.

Webhook Versions

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.

Subscribe to Updates

To get notified when Pinwheel releases new changes to our API, you can subscribe to our Changelog with an RSS subscriber here.

Breaking Changes

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.

2023-11-22

The params.action field in the direct_deposit_switch.added webhook event and Get Jobs response is now optional.

2023-07-18

The Create Link Token request now requires an end_user_id if an account_id is not provided.

2023-04-18

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.

2022-09-09

The Create Link Token request now takes an allocation object containing a type and value that 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.

2022-06-22

The params field in the Get Jobs response for direct_deposit_switch jobs will now include more specific detail on both the direct deposit switch action and the allocation type.
The params field 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.

Terminology

Sunsetted: Discontinued and no longer available for usage.

Deprecated: Functional, but usage is discouraged. It is scheduled to be sunsetted.

Please contact [email protected] for access to our Dashboard.