Change Management

API Change Management

In order to continue adding functionality, we regularly make improvements and changes to our API.

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. The current version is 2021-07-28. Changes and upgrade instructions will be detailed in the Changelog.

You must send a Pinwheel-Version header with each request to specify how the Pinwheel API should behave. See Version Headers on the API page for more information.

Old versions are considered deprecated and will be sunsetted when no more API requests are made to them. Trying to use a sunsetted version will result in a 400 Bad Request error.

New dated versions, and 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 below.

You can access docs for deprecated API versions via the "Versions" menu in the left sidebar.

Terminology

Deprecated: usage is discouraged.

Sunsetted: discontinued, no longer available for usage.

Changelog

All notable changes to Pinwheel will be documented in this file, including new features, bug fixes, versioned changes, deprecations, and sunsets.

January 27, 2022

Deprecated the account.disconnected and account.reconnected webhook events. Use account.monitoring_status.updated instead. We are coordinating with customers currently using these webhook events to sunset usage and transition to the new event.

January 19, 2022

  • Modified REST API endpoints:
    • Changed GET /accounts/{account_id} and GET /accounts
      • New monitoring_status in the data field, indicating the ability of Pinwheel to automatically monitor for data changes in the payroll account.
  • New REST API endpoints:
    • Added POST /accounts/{account_id}/disable_monitoring
      • This is a renaming of the POST /accounts/{account_id}/disconnect REST API endpoint. We are coordinating with customers currently using this endpoint to sunset usage and transition to the new endpoint.
  • Modified webhook events:
    • Added monitoring_status to the account.added webhook event.
    • Redefined connected to refer to all Recurring Access availability, not just Monitoring.

January 14, 2022

Added account.monitoring_status.updated webhook event. It is triggered whenever a payroll account's monitoring status is updated.

December 2, 2021

React (2.3.4) and React Native (2.3.4) packages updated to:

  • Export EventPayload.
  • Export EmptyPayloadObject as Record<string, never>.
  • Use EmptyPayloadObject instead of {} in EventPayload type to behave as expected.
  • Export PinwheelError.
    • Mark Error as deprecated.
  • Export PinwheelErrorType.
    • Mark ErrorType as deprecated.
  • Update onExit type to be (error: PinwheelError | EmptyPayloadObject) to conform with current functionality.

December 1, 2021

I&E Monitoring released in beta. To support this new feature we've made the following modifications to REST API endpoints:

November 12, 2021

Added a new enum value unpaid to earnings category for paystubs and shifts.

November 10, 2021

Added the property platformId to the LinkResult payload sent for a success event from Link.

SDKMinimum Version
React2.3.3
React Native2.3.3
iOS2.3.9
Android2.3.13
Flutter2.3.1

November 1, 2021

Added new error code sessionTimeout. This error occurs when the session closes after a period of inactivity, e.g., due to lack of user action.

October 21, 2021

DDA Monitoring released in beta. To support this new feature we've made the following modifications to REST API endpoints and webhook events:

  • Modified REST API endpoints:
    • Changed Get Account and List Accounts
      • New data fields, data_refreshed_at and data_updated_at, indicating when direct deposit allocation data was last refreshed or updated.
    • Changed Create Link Token
      • New optional account_id request parameter.
      • required_jobs is optional if account_id is provided.
    • Changed Get Direct Deposit Allocations
      • New data field, updated_at, indicating when the data last changed.
      • New meta field with sub-property refreshed_at indicating when the data was last checked for changes.
  • New REST API endpoints:
  • Modified webhook events:
    • Changed accounts.added
      • New connected field in the payload indicating if DDA Monitoring will be run for an account.
  • New webhook events:

New Link client event login_attempt added. The event fires when the user submits a login attempt for the first time. The following table lists the SDKs and minimum versions required to receive the change.

SDKMinimum Version
React2.3.3
React Native2.3.2
iOS2.3.7
Android2.3.12
Flutter2.3.0

August 23, 2021

New Link error code added to the existing invalidUserInput error type. The new code, timedOutWithNoInput will be thrown if the Link modal is left open for 15 minutes with no user input. See the Error documentation page for more details.

August 11th, 2021

Updated the iOS SDK to 2.3.6 to make accountId a required field in PinwheelSuccessPayload.

July 28th, 2021

New API version 2021-07-28 released. Version 2021-04-29 is now deprecated and its usage is discouraged in new implementations.

The Pinwheel-Version header is now expected on all requests. Until version 2021-04-29 is sunsetted, the header will default to 2021-04-29 if not provided. After 2021-04-29 is sunsetted, requests without the Pinwheel-Version header will return a 400 Bad Request error.

Version 2021-07-28

Breaking Changes:

  • The expires field in the response from Create Link Token and Create Site is now an ISO-8601
    formatted timestamp string, bringing it inline with our API Conventions (previously it was an integer of seconds since Unix epoch).
  • The responses from Create Link Token and Create Site no longer includes the redundant token_id field; use the id field directly instead.
  • The request payloads for Create Link Token and Create Site no longer accepts the scalar field job. Use required_jobs, which supports an array of job types, instead.

July 13th, 2021

Added a new job outcome, pending, for Income and Employment jobs.

July 9th, 2021

We made the employer_name field required in the response from Get Employment.

June 22, 2021

We added support for Maven Central Repository distribution to our Android SDK. See the Link SDKs page for more details.

June 11th, 2021

We released a Flutter SDK, see the Link SDKs page for more details.

June 8th, 2021

We added a set of webhook events for shifts and paystubs that indicate how much data has been synced. See the implementation guide for Employment Data or Webhooks: Paystubs Sync Events for more details.

June 7, 2021

We added support for simulating error and pending scenarios in sandbox mode.

April 30, 2021

We launched a visual refresh of the Link modal including a redesign of the platform authentication screen to display the selected employer and an exit confirmation screen.

April 29, 2021

We simplified the signature algorithm used in webhook verification to reduce cross-language inconsistencies. See Webhooks: Verifying Pinwheel is the Sender for implementation details. Additionally, we moved webhook event IDs from the header into the request body, increasing the signature's entropy.

  • The header x-pinwheel-webhook-id has been removed. It's now available as event_id in the request body.
  • The request body parameter webhook_id has been removed. It's now available as the header x-pinwheel-webhook-id.

April 22, 2021

The employment endpoint response now includes job title. See the full API reference here.

April 21, 2021

We launched the direct_deposit_allocations job type, providing data about existing allocations of a user's payroll account. See the Direct Deposit guide and API Reference to get started.

April 19, 2021

We launched the shifts job type, providing data about ongoing and completed work performed by a user. See the Income and Employment guide and API Reference to get started.

April 14, 2021

The Pinwheel Link SDK 2.3 introduces a new job outcome, pending, to represent a job that was unable to be completed on its first try. We'll attempt to retry the job up to 24hrs after the initial attempt, and notify you of the final outcome via webhook. Read about the full details here.

April 6th, 2021

To promote secure usage, all Webhooks URLs are now required to be https://.

March 18, 2021

The unused, legacy "exit survey" feature was deprecated from Link making the skip_exit_survey parameter in link token creation irrelevant. We'll continue to support calls including that parameter, but it will no longer make a difference to the generated Link modal.

March 9, 2021

In our continued efforts to increase conversion, we've updated our Link SDKs to consolidate the employer and payroll provider search screens into one unified search experience with an upgraded UI. By default, the most popular platforms will be pre-populated.

February 26, 2021

Webhooks will be sent for successful paystubs jobs even when no data is available. The params object is be used to differentiate between successful jobs with data, and those without data available.

February 19, 2021

The Link modal now returns platformId in the login event type and callback to provide the same functionality as the webhook change mentioned below on February 18th.

February 18, 2021

The Get Account endpoint now includes platform_id, the unique identifier of the payroll platform associated with the account. This identifier is also be included the account.added webhook event. You can use the new Get Platform endpoint to fetch the platform's name, supported jobs, and other information.

We also added error_type to Jobs responses and relevant Webhook payloads to help you understand what happened if a user runs into an unexpected error.

February 12, 2021

Pinwheel Link 2.0 is live! The new version features support for Income and Employment Data jobs, improved callbacks and listeners in Link, and a fresh UI. Full details on the new features and how to upgrade are in the migration guide.

We also launched our new and improved interactive docs, which includes new and updated guides for Income and Employment Data, Link, Webhooks, and this changelog. Our API Reference now includes interactive request makers and code generation to help you test and implement without hassle.

February 5, 2021

All Pinwheel API responses now include a x-pinwheel-request-id header to help you keep track of your requests. More details in the API guide.

January 28, 2021

We now have an official React SDK for Link, making deploying a React app as easy as pie.

January 13, 2021

We added a new query parameter include_esps to the List Platforms endpoint, allowing you to include employer-specific platforms when viewing the platforms Pinwheel supports. Employer-specific platforms describe an Employer that uses a unique, dedicated payroll portal to serve their employees, like Walmart.

January 5, 2021

We added a new Jobs endpoint to enable you to query all completed jobs from your account in one place. It can be filtered by timestamp, job type, and Link token.

December 20, 2020

We improved our Search Employers and Platforms endpoint to use fuzzy matching across names and known aliases of Employers and Platforms. You can search by passing in a string to the q query parameter.

December 2, 2020

We're excited to announce the launch of our iOS SDK! Pinwheel SDKs are now available for iOS, Android, and React Native.

November 24, 2020

We launched brand new Android and React Native SDKs so you can expand the number of users you reach.

November 6, 2020

We're thrilled to announce the launch of Webhooks. You can now set up a webhook to listen to events from Pinwheel in real time.

We also added a new Search Employers and Platforms endpoint that provides a unified search across all Employers and Platforms.

November 5, 2020

We launched a Changelog. You can now see all notable changes to Pinwheel's platform in one place. New features coming soon!


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


Did this page help you?