Document Income

Document Income allows you to retrieve gross and/or net income information via user-uploaded documents such as a pay stub, bank statement, W-2, or 1099 form.

1. Call /user/create to create a user_token that will represent the end user interacting with your application. This step will only need to be done once per end user. If you are using multiple Income types, do not repeat this step when switching to a different Income type.
2. Call /link/token/create. In addition to the required parameters, you will need to provide the following:
   • For user_token, provide the user_token from /user/create.
   • For products, use ["income_verification"]. Document Income cannot be used in the same Link session as any other Plaid products, except for Payroll Income.
   • For income_verification.income_source_types, use payroll.
   • (Optional) If you are only using Document Income and do not want customers to use Payroll Income, for income_verification.payroll_income.flow_types, use ["document_digital_income"].
   • Provide a webhook URI with the endpoint where you will receive Plaid webhooks.
   • If using Fraud Risk, set income_verification.parsing_config to either ['risk_signals'] or ['risk_signals', 'ocr']. For more details, see Fraud Risk detection.
3. On the client side, create an instance of Link using the link_token returned by /link/token/create; for more details, see Link.
4. Open Link in your web or mobile client and listen to the onSuccess and onExit callbacks, which will fire once the user has finished or exited the Link session.
5. If using Fraud Risk, wait for the INCOME: INCOME_VERIFICATION_RISK_SIGNALS webhook, then call /credit/payroll_income/risk_signals/get.
   • If the document requires manual review, call /credit/payroll_income/get to get a URI where the user's original documents can be downloaded.
6. If using Document Parsing, wait for the INCOME: INCOME_VERIFICATION webhook, then call /credit/payroll_income/get and/or /credit/bank_statements/uploads/get to obtain parsed income details. You can use /credit/sessions/get to see which endpoints to call. For details, see Document Parsing.

To detect potential document fraud or document tampering during the Document Income flow, you can use the optional Fraud Risk feature. Fraud Risk's AI-powered analysis scans for over two dozen different fraud signals within categories such as: visual evidence of tampering, suspicious metadata, inconsistent contents, and similarity to known fraudulent documents. If your account is not enabled for this feature, contact sales or your Plaid Account Manager to request access.

To enable Fraud Risk:

1. When calling /link/token/create, set the income_verification.parsing_config array to include 'risk_signals'. By default, this will disable Document Parsing; to keep it enabled, include 'ocr' in the array as well.
2. When the risk analysis has been completed, you will receive an INCOME_VERIFICATION_RISK_SIGNALS webhook. This webhook may take up to 45 minutes to fire.
3. Once the webhook has been received, call the /credit/payroll_income/risk_signals/get endpoint.

/credit/payroll_income/risk_signals/get will return a risk score for each document, as well as a detailed set of reasons for any potential risk.

You can automatically reject documents with a high risk score, automatically accept documents with a low risk score, and manually review documents in between. We suggest starting with a threshold of 80 for auto-rejection and 20 for auto-acceptance. As you gather more data points on typical risk scores for your use case, you can tune these parameters to reduce the number of documents undergoing manual review.

To obtain a copy of the original document for manual review, call /credit/payroll_income/get and use the document_metadata.download_url.

To enable Fraud Risk on a verification where the Link flow has already been completed, use the /credit/payroll_income/parsing_config/update endpoint.

Document Parsing is an optional feature that allows you to obtain a JSON representation of an uploaded document. If your account is not enabled for this feature, contact sales or your Plaid Account Manager to request access.

To enable Document Parsing:

1. Call /link/token/create as normal. You do not need to specify a parsing_config, as Document Parsing will be enabled by default if this field is omitted. However, if this field is supplied (for example, to enable Fraud Risk), it must include ocr to enable Document Parsing.

2. To see which file types a user uploaded, use /credit/sessions/get. The document_income_results field will show how many of each filetype were uploaded.

3. Wait for document parsing to complete, which will be indicated by the INCOME_VERIFICATION webhook. This webhook may take up to 45 minutes to fire.

4. Once the webhook has been received, to obtain parsed JSON data from a pay stub, W-2, or 1099, use /credit/payroll_income/get. To obtain parsed JSON data from a bank statement, use /credit/bank_statements/uploads/get.

To enable Document Parsing on a verification where the Link flow has already been completed, use the /credit/payroll_income/parsing_config/update endpoint.

To download the original user-uploaded documents, use the document_metadata.download_url returned by /credit/payroll_income/get.

To limit which documents your users can upload, create a Link customization in the Dashboard after you have received Production access.

• Pay stubs
• Bank statements
• W-2
• 1099-K
• 1099-MISC

• PDF
• PNG
• JPEG
• GIF
• BMP
• TIFF

For more details, see Document upload settings.

Income can be tested in Sandbox against test data without contacting Plaid. In order to test Income against live Items in either Development or Production, you will need to first request access by submitting a product access request Support ticket explaining your use case.

In the Sandbox environment, when testing Document Income, the contents of the actual document will not be processed and Sandbox will instead use pre-populated test data -- all fields returned by /credit/payroll_income/get will be null, absent, or unknown, and all risk scores will be 100. This data will be available immediately. To test that your application properly handles the real-world delayed processing behavior of Document Income, or to test with real data, make sure to test in the Development environment.

/credit/payroll_income/get can optionally be tested in Sandbox without using Link. Call /user/create, pass the returned user_token to /sandbox/public_token/create (ins_90 is a good sample institution_id for testing Document Income in Sandbox), and then call /credit/payroll_income/get. The output of /sandbox/public_token/create will not be used, but calling it initializes the user token for testing.

Document Income is billed on a one-time fee model. The fee depends on the number and type of documents processed and which processing options are enabled (i.e. fraud risk, document parsing, or both).

To view the exact pricing you may be eligible for, apply for Production access or contact Sales. For more details about pricing and billing models, see Plaid billing.

If you're ready to launch to Production, see the Launch checklist.