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-11-22!


# Introduction

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.

# Implementation

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.




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
Employment[employment.added](🔗)
Identity[identity.added](🔗)
Income[income.added](🔗)
Paystubs[paystubs.added](🔗)
Shifts[shifts.added](🔗)

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.



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](🔗).