Income Verification endpoints and webhooks

Endpoints for the Income Verification (beta) product

Income Verification (beta)

Verify user's income and paystubs.

In this section
/income/verification/createCreate an income verification instance
/income/verification/summary/getRetrieve income verification summary information
/income/verification/paystub/getRetrieve paystub summary information
/income/verification/documents/downloadDownload a ZIP file containing the original documents used for income verification
/employers/searchSearch for an employer to allow bypassing the Link flow (coming soon)
INCOME: income_verificationWebhook to notify that income verification has completed

/income/verification/create

Create an income verification instance

/income/verification/create begins the income verification process by returning an income_verification_id. You can then provide the income_verification_id to /link/token/create under the income_verification parameter in order to create a Link instance that will prompt the user to upload their income documents. Once the documents have been uploaded and parsed, Plaid will fire an INCOME webhook.

income/verification/create

Request fields and example

client_idstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secretstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
webhookrequiredstring
The URL endpoint to which Plaid should send webhooks related to the progress of the income verification process.
1
// Client libraries coming soon
income/verification/create

Response fields and example

income_verification_idstring
ID of the verification. This ID is persisted throughout the lifetime of the verification.
request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1
2
3
4
{
"income_verification_id": "f2a826d7-25cf-483b-a124-c40beb64b732",
"request_id": "lMjeOeu9X1VUh1F"
}

/income/verification/summary/get

Retrieve a summary of information derived from income verification

/income/verification/summary/get returns a verification summary for the income that was verified for an end user. It can be called once the status of the verification has been set to VERIFICATION_STATUS_PROCESSING_COMPLETE, as reported by the INCOME: verification_status webhook. Attempting to call the endpoint before verification has been completed will result in an error.

income/verification/summary/get

Request fields and example

client_idstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secretstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
income_verification_idrequiredstring
The ID of the verification.
1
// Client libraries coming soon
income/verification/summary/get

Response fields and example

income_summaries[object]
A list of income summaries.
employer_namenullableobject
The name of the employer, as reported on the paystub.
valuestring
The value of the field.
verification_statusstring
The verification status. One of the following:
"VERIFIED": The information was successfully verified.
"UNVERIFIED": The verification has not yet been performed.
"NEEDS_INFO": The verification was attempted but could not be completed due to missing information.
"UNABLE_TO_VERIFY": The verification was performed and the information could not be verified.
"UNKNOWN": The verification status is unknown.

Possible values: VERIFIED, UNVERIFIED, NEEDS_INFO, UNABLE_TO_VERIFY, UNKNOWN
employee_namenullableobject
The name of the employee, as reported on the paystub.
valuestring
The value of the field.
verification_statusstring
The verification status. One of the following:
"VERIFIED": The information was successfully verified.
"UNVERIFIED": The verification has not yet been performed.
"NEEDS_INFO": The verification was attempted but could not be completed due to missing information.
"UNABLE_TO_VERIFY": The verification was performed and the information could not be verified.
"UNKNOWN": The verification status is unknown.

Possible values: VERIFIED, UNVERIFIED, NEEDS_INFO, UNABLE_TO_VERIFY, UNKNOWN
ytd_gross_incomenullableobject
Year-to-date pre-tax earnings, as reported on the paystub.
valuenumber
The value of the field.
verification_statusstring
The verification status. One of the following:
"VERIFIED": The information was successfully verified.
"UNVERIFIED": The verification has not yet been performed.
"NEEDS_INFO": The verification was attempted but could not be completed due to missing information.
"UNABLE_TO_VERIFY": The verification was performed and the information could not be verified.
"UNKNOWN": The verification status is unknown.

Possible values: VERIFIED, UNVERIFIED, NEEDS_INFO, UNABLE_TO_VERIFY, UNKNOWN
ytd_net_incomenullableobject
Year-to-date earnings after any tax withholdings, benefit payments or deductions, as reported on the paystub.
valuenumber
The value of the field.
verification_statusstring
The verification status. One of the following:
"VERIFIED": The information was successfully verified.
"UNVERIFIED": The verification has not yet been performed.
"NEEDS_INFO": The verification was attempted but could not be completed due to missing information.
"UNABLE_TO_VERIFY": The verification was performed and the information could not be verified.
"UNKNOWN": The verification status is unknown.

Possible values: VERIFIED, UNVERIFIED, NEEDS_INFO, UNABLE_TO_VERIFY, UNKNOWN
pay_frequencynullableobject
valuestring
The frequency of the pay period.
Possible values: monthly, semimonthly, weekly, biweekly, unknown, null
verification_statusstring
The verification status. One of the following:
"VERIFIED": The information was successfully verified.
"UNVERIFIED": The verification has not yet been performed.
"NEEDS_INFO": The verification was attempted but could not be completed due to missing information.
"UNABLE_TO_VERIFY": The verification was performed and the information could not be verified.
"UNKNOWN": The verification status is unknown.

Possible values: VERIFIED, UNVERIFIED, NEEDS_INFO, UNABLE_TO_VERIFY, UNKNOWN
projected_wagenullableobject
The employee's estimated annual salary, as derived from information reported on the paystub.
valuenumber
The value of the field.
verification_statusstring
The verification status. One of the following:
"VERIFIED": The information was successfully verified.
"UNVERIFIED": The verification has not yet been performed.
"NEEDS_INFO": The verification was attempted but could not be completed due to missing information.
"UNABLE_TO_VERIFY": The verification was performed and the information could not be verified.
"UNKNOWN": The verification status is unknown.

Possible values: VERIFIED, UNVERIFIED, NEEDS_INFO, UNABLE_TO_VERIFY, UNKNOWN
verified_transactionnullableobject
Information about the matched direct deposit transaction used to verify a user's payroll information.
descriptionstring
The description of the transaction.
amountnumber
The amount of the transaction.
datestring
The date of the transaction, in ISO 8601 format ("yyyy-mm-dd").
account_idstring
A unique identifier for the end user's account.
transaction_idstring
A unique identifier for the transaction.
request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
"income_summaries": [
{
"employee_name": {
"value": "ANNA CHARLESTON",
"verification_status": "UNVERIFIED"
},
"employer_name": {
"value": "PLAID INC",
"verification_status": "UNVERIFIED"
},
"pay_frequency": {
"value": "semimonthly",
"verification_status": "UNVERIFIED"
},
"projected_wage": {
"value": 100000,
"verification_status": "UNVERIFIED"
},
"verified_transaction": {
"account_id": "",
"amount": 0,
"date": "",
"description": "",
"transaction_id": ""
},
"ytd_gross_income": {
"value": 59375,
"verification_status": "UNVERIFIED"
},
"ytd_net_income": {
"value": 66205.35714285713,
"verification_status": "UNVERIFIED"
}
}
],
"request_id": "LhQf0THi8SH1yJm"
}

/income/verification/paystub/get

Retrieve information from the paystub used for income verification

/income/verification/paystub/get returns the information collected from the paystub that was used to verify an end user's income. It can be called once the status of the verification has been set to VERIFICATION_STATUS_PROCESSING_COMPLETE, as reported by the INCOME: verification_status webhook. Attempting to call the endpoint before verification has been completed will result in an error.

income/verification/paystub/get

Request fields and example

client_idstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secretstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
income_verification_idrequiredstring
The ID of the verification for which to get paystub information.
1
// Client libraries coming soon
income/verification/paystub/get

Response fields and example

paystubobject
An object representing data extracted from the end user's paystub.
paystub_idstring
The unique identifier for this paystub.
account_idnullablestring
The account identifier for the account associated with this paystub.
employerobject
Data about the employer.
employer_idstring
Plaid's unique identifier for the employer.
namestring
The name of the employer
addressnullableobject
Data about the components comprising an address.
citystring
The full city name
regionnullablestring
The region or state Example: "NC"
streetstring
The full street address Example: "564 Main Street, APT 15"
postal_codenullablestring
The postal code
countrystring
The ISO 3166-1 alpha-2 country code
confidence_scorenullablenumber
A number from 0 to 1 indicating Plaid's level of confidence in the pairing between the employer and the institution (not yet implemented).
employeeobject
Data about the employee.
namenullablestring
The name of the employee.
addressnullableobject
Data about the components comprising an address.
citystring
The full city name
regionnullablestring
The region or state Example: "NC"
streetstring
The full street address Example: "564 Main Street, APT 15"
postal_codenullablestring
The postal code
countrystring
The ISO 3166-1 alpha-2 country code
ssn_maskednullablestring
The SSN of the employee, with all but the last 4 digits masked out. For example: "XXX-XX-1111".
pay_period_detailsobject
Details about the pay period.
start_datenullablestring
The pay period start date, in ISO 8601 format: "yyyy-mm-dd".
end_datenullablestring
The pay period end date, in ISO 8601 format: "yyyy-mm-dd".
pay_daynullablestring
The date on which the paystub was issued, in ISO 8601 format ("yyyy-mm-dd").
gross_earningsnullablenumber
Total earnings before tax.
check_amountnullablenumber
The net amount of the paycheck.
income_breakdownobject
typenullablestring
The type of income. Possible values include "regular", "overtime", and "bonus".
ratenullablenumber
The hourly rate at which the income is paid.
hoursnullablenumber
The number of hours logged for this income for this pay period.
totalnullablenumber
The total pay for this pay period.
ytd_earningsobject
gross_earningsnumber
Year-to-date gross earnings.
net_earningsnumber
Year-to-date net (take home) earnings.
request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
"account_id": null,
"employee": {
"address": {
"city": "SAN FRANCISCO",
"country": "US",
"postal_code": "94133",
"region": "CA",
"street": "2140 TAYLOR ST"
},
"name": "ANNA CHARLESTON"
},
"employer": {
"name": "PLAID INC"
},
"income_breakdown": [],
"pay_period_details": {
"check_amount": 1490.21,
"end_date": "2020-12-15",
"gross_earnings": 4500,
"pay_day": "2020-12-15",
"start_date": "2020-12-01"
},
"request_id": "snygYZ9fR3vXuam",
"ytd_earnings": {
"gross_earnings": 59375,
"net_earnings": null
}
}

/income/verification/documents/download

Download the original documents used for income verification

/income/verification/documents/download provides the ability to download the source paystub PDF that the end user uploaded via Paystub Import.
The response to /income/verification/documents/download is a ZIP file in binary data. The request_id is returned in the Plaid-Request-ID header.
In the future, when Digital Verification is available, the most recent file available for download with the payroll provider will also be available from this endpoint.

income/verification/documents/download

Request fields and example

client_idstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secretstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
income_verification_idrequiredstring
The ID of the verification.
1
// Client libraries coming soon
Response

This endpoint returns binary ZIP data of MIME type application/zip.

INCOME: income_verification

Fired when the status of an income verification instance has changed. It will typically take several minutes for this webhook to fire after the end user has uploaded their documents, and may take up to 15 minutes.

webhook_typestring
"INCOME"
webhook_codestring
income_verification
income_verification_idstring
The income_verification_id of the verification instance whose status is being reported.
verification_statusstring
VERIFICATION_STATUS_PROCESSING_COMPLETE: The income verification status processing has completed.
VERIFICATION_STATUS_UPLOAD_ERROR: An upload error occurred when the end user attempted to upload their verification documentation.
VERIFICATION_STATUS_INVALID_TYPE: The end user attempted to upload verification documentation in an unsupported file format.
VERIFICATION_STATUS_DOCUMENT_REJECTED: The documentation uploaded by the end user was recognized as a supported file format, but not recognized as a valid paystub.
VERIFICATION_STATUS_PROCESSING_FAILED: A failure occurred when attempting to process the verification documentation.
1