GuidesAPI ReferenceChangelog
Log In
Hey! These docs are for version 2021-07-28, which is no longer officially supported. Click here for the latest version, 2023-07-18!

On Demand Updates (Beta) Implementation Guide


There are cases where you may want to take repeated actions on a payroll account. We recognize that asking the user to log in multiple times introduces friction, so we've added the ability to re-access the payroll account without needing the user to re-enter credentials.

If the user has multi-factor authentication enabled on their account, user action may be required to complete the login step.

Use cases

  • To increase share of wallet, you can incentivize users to increase their direct deposit allocation after an initial direct deposit switch. Users may initially allocate a small amount into the account, but with the right incentives, they may be willing to increase that amount.
  • To help with underwriting decisions, you can leverage income and employment data before asking the user to complete a direct deposit switch.
  • To reduce fraud, you can match the identity of the payroll account owner against your customer prior to allowing a direct deposit switch.


Enabling this functionality is similar to the way standard Link tokens are created today. When creating the Link token, pass in the account_id parameter from a prior account.added webhook event or from the login client side event in Link. The account_id can be preserved and passed in any time you have it for a user.

Taking the 3rd use case above where you match the identity of the payroll account owner against that of your user, you would first create the Link token with identity as the required job. Once your customer logs in and the job completes successfully, you will receive both the accounts.added and identity.added webhooks.

  "event": "account.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
    "platform_id": "fce3eee0-285b-496f-9b36-30e976194736",
    "created_at": "2021-01-12T02:36:01.287148+00:00",
    "connected": true
  "event": "identity.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
    "name": "identity",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success"

You can then query for full_name, date_of_birth, and last_four_ssn in addition to other fields to determine if the payroll account owner is the same person as your user. For more info, please see the Income & Employment guide here.

A webhook event will be sent for indicating success or failure, if you're registered for it.

JobWebhook Event

If performing an On Demand Update re-activated monitoring for an account a account.monitoring_status.updated webhook event will also be sent. You can learn more at Maintain Account Monitoring.

Once you have successfully completed the verification, you can create another Link token to initiate the direct deposit switch using the same account_id. In doing so, we will attempt to bypass the need for the user to re-enter credentials. Note that there are some cases, eg. where MFA is enabled, where the user will have to take an action to complete login.

POST /v1/link_tokens
Content-Type: application/json
  "org_name": "YOUR APP NAME",
  "account_type": "checking",
  "routing_number": "07464755",
  "account_number": "193464372203",
  "required_jobs": [
  "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65"

On Demand Updates is available beginning in version 2021-07-28 of the Pinwheel API (see Versioned Changes). If you try using On Demand Updates with an older version, or no version, a standard Link token will be created to connect a new account.

While this feature is currently in beta, we'd be happy to talk to you about your use cases and get you started with On Demand Updates.

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