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. (Optional) Update your Link customization in the Dashboard to configure which types of documents a user can upload to verify their income. By default, if you do not change this setting, only pay stubs are accepted.
2. 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.
3. 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 ["payroll_document_income"].
   • Provide a webhook URI with the endpoint where you will receive Plaid webhooks.
   • If using Fraud Risk, set income_verification.payroll_income.parsing_config to either ['risk_signals'] or ['risk_signals', 'ocr']. For more details, see Fraud Risk detection.
4. On the client side, create an instance of Link using the link_token returned by /link/token/create; for more details, see Link.
5. 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.
6. 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.
7. 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 what document types were uploaded, which will determine which of the two 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.payroll_income.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, then launch Link and have the user go through the Link flow. You do not need to specify a parsing_config when calling /link/token/create, 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 configure which documents your users can upload, create a Link customization in the Dashboard. You must update this setting in order to accept documents other than pay stubs.

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

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

For more details, see Document upload settings.

In the Sandbox environment, when testing Document Income, by default, the contents of the actual document will not be processed and Sandbox will instead use pre-populated test data. You can customize the response you get by uploading JSON files with a custom configuration schema in the Link flow. Each JSON file will represent one document in the response and can include customizations for:

• Either a paystub or a W-2
• Risk signals
• OCR parsing status
• Risk signals status

The customization schema for each document and risk signals is very similar to the objects in the responses from /credit/payroll_income/get and /credit/payroll_income/risk_signals/get. Example JSON files that you can adapt can be found in the Custom Sandbox User GitHub repo.

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.