Introduction to Income

Income (US only) allows you to verify a user's income automatically based on paystubs they provide.

1. (Optional) To optimize the Link UI and increase conversions, call /income/verification/precheck and provide information about the user's employer and/or access tokens associated with the user. You can provide the precheck_id returned by /income/verification/precheck when calling /link/token/create. Doing this will streamline the Link flow by pre-populating employer data for eligible users.

2. Call /link/token/create with your client ID, secret, desired webhook url, and (if obtained in the previous optional step) precheck_id. Specify income_verification and/or employment in the products array, depending on which endpoints you plan to use. In order to use any endpoint containing income in its name, such as /income/verification/paystubs/get income_verification must be included in the products array, and in order to use /employment/verification/get, employment must be included as well.

3. You will receive a link_token in the response body. Use this link_token to initialize Link on the client side.

4. Your end user will be presented with the Plaid Link interface, where they can connect instantly to their payroll provider or upload an appropriate document (paystubs, W2s) as an alternative.

5. When your user completes the flow, you will get a public_token in the onSuccess callback. Exchange the public_token for an access_token by calling /item/public_token/exchange. Save both the access_token and item_id from the response to your database.

   

6. When verification processing is complete, you’ll receive an INCOME: income_verification webhook with a corresponding item_id.

7. Using the item_id as an identifier, you can then call /income/verification/paystubs/get, /income/verification/taxforms/get, or /employment/verification/get to access the user’s income and employment information. You can also retrieve the documents used to verify income by calling /income/verification/documents/download.