Learn about Document Income features and implementation
View Income requests, responses, and example code
View the starter Income sample app and code
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.
/user/createto create a
user_tokenthat 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.
/link/token/create. In addition to the required parameters, you will need to provide the following:
user_token, provide the
["income_verification"]. Document Income cannot be used in the same Link session as any other Plaid products, except for Payroll Income.
- (Optional) If you are only using Document Income and do not want customers to use Payroll Income, for
- Provide a
webhookURI with the endpoint where you will receive Plaid webhooks.
- If using Fraud Risk, set
['fraud_risk', 'ocr']. For more details, see Fraud Risk detection.
- On the client side, create an instance of Link using the
/link/token/create; for more details, see Link.
- Open Link in your web or mobile client and listen to the
onExitcallbacks, which will fire once the user has finished or exited the Link session.
- If using Fraud Risk, wait for the
INCOME: INCOME_VERIFICATION_RISK_SIGNALSwebhook, then call
- If the document requires manual review, call
/credit/payroll_income/getto get a URI where the user's original documents can be downloaded.
- If the document requires manual review, call
- If using Document Parsing, wait for the
INCOME: INCOME_VERIFICATIONwebhook, then call
/credit/bank_statements/uploads/getto obtain parsed income details. You can use
/credit/sessions/getto see which endpoints to call. For details, see Document Parsing.
Fraud risk detection
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:
- When calling
/link/token/create, set the
income_verification.parsing_configarray to include
'fraud_risk'. By default, this will disable Document Parsing; to keep it enabled, include
'ocr'in the array as well.
- When the risk analysis has been completed, you will receive an
INCOME_VERIFICATION_RISK_SIGNALSwebhook. This webhook may take up to 45 minutes to fire.
- Once the webhook has been received, call the
/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
To enable Fraud Risk on a verification where the Link flow has already been completed, use the
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:
/link/token/createas 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
ocrto enable Document Parsing.
To see which file types a user uploaded, use
document_income_resultsfield will show how many of each filetype were uploaded.
Wait for document parsing to complete, which will be indicated by the
INCOME_VERIFICATIONwebhook. This webhook may take up to 45 minutes to fire.
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
To enable Document Parsing on a verification where the Link flow has already been completed, use the
Downloading original documents
To download the original user-uploaded documents, use the
document_metadata.download_url returned by
Customizing document uploads
To limit which documents your users can upload, create a Link customization in the Dashboard after you have received Production access.
Supported document types
- Pay stubs
- Bank statements
Supported file types
For more details, see Document upload settings.
Testing Document Income
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. This data will be available immediately. To test that your application properly handles the real-world delayed processing behavior of Document Income, test in the Development environment.
/credit/payroll_income/get can optionally be tested in Sandbox without using Link. Call
/user/create, pass the returned
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.
If you're ready to launch to Production, see the Launch checklist.