Verify Income & Employer Details
Get Started
Before requesting income and employment verification, create a case and share data by uploading one or more payslips, bank statements and / or by creating one or more open banking connections.
Create a Case
Create a case using the create case endpoint. A case can optionally contain people. You can share data and request an Income and Employment verification at the case or person level.
- For unique insights for individual applicants within a case, add each person as a
personentity, upload relevant documents and request the verification perperson. - For joint applications or to generate insights on multliple applicants, add all necessary documents or connections to the
caseand request insights for the entirecase.
Upload Payslips
Upload payslips using the upload document endpoint. Ensure the entity_id and entity_type are specified in the request. For more accurate results, upload at least three months of payslips.
Payslips must meet the following criteria:
- Documents must be unaltered and unencrypted.
- Documents should have a good resolution. If they are scanned or are an image then the image should not be blurry and all text must be clear.
When a payslip has been uploaded and we have attempted to extract the data from it we will try to send a PayslipProcessing.Completed webhook if one has been configured in our API. For full details, please see the Payslip Processing Completed Webhook section.
Upload Bank Statements
Upload bank statements using the upload document endpoint. Ensure the entity_id and entity_type are specified in the request. For accurate insights, upload at least three months of statements.
Bank statements must meet the following criteria:
- Statements must be from a supported UK bank. You can find a list of supported banks here.
- Statements must be in PDF format,
base64encoded. - Statements must be downloaded directly from the official bank website or mobile application. Photos or scanned copies are not supported.
- Statements must be unaltered and unencrypted.
- Statements must be for a joint or individual bank account or credit card. Mortgage statements and loan statements are not supported.
Safari, Firefox and Edge browsers may alter the documents if viewed in the browser and then saved, either directly or via a “print to pdf” function.
When a bank statement has been uploaded and we have attempted to extract the data from it we will try to send a BankStatementProcessing.Completed webhook if one has been configured in our API. For full details, please see the Bank Statement Processing Completed Webhook section.
Create an Open Banking Connection
As an alternative to uploading bank statements, connect a bank account for a UK bank using open banking by utilising the relevant open banking connection endpoint.
You can find more information on the types of connected accounts that can be used to generate an affordability insights here.
When an open banking connection has been completed we will try to send a OpenBankingProcessing.Completed webhook if one has been configured in our API. For full details, please see the Open Banking Processing Completed Webhook section.
Review Data Sources
If you're not using webhooks or if you want to view all the data sources which have been provided for a given entity, you can also verify the processing status for all documents and open banking connections using our data sources endpoint.
The possible statuses are:
- Provided: The document has been successfully uploaded into the system but has not been processed.
- Pending: The data source is being processed.
- If the data source is a document, it is in the process of being classified or being extracted.
- If the data source is an open banking connection, the user has not yet completed the authorisation process.
- Complete: The data source has been successfully processed.
- Failed: The data source could not be processed for some reason. If a failed status is returned, a message will also be returned which includes more information on what the data source could not be processed.
- Excluded: The data source has been deleted or is not supported.
Before requesting Income & Employer Verification, ensure the status is Complete for all data sources you wish to use. Data Sources with a Provided Failed, Pending, or Excluded statuses cannot be used for income & employer verification.
Generate Income & Employment Verification Request
Once you've created a case and successfully uploaded the relevant documents or created the relevant open banking connections, you can request an income and employer verification.
Use the POST Income & Employer endpoint to initiate the verification for the specific entity.
{
"request_id": "8ef5079a-b3de-44a5-b4ff-c534259e752c",
"status": "Pending",
"entity_id": "b3f6ed8f-bc57-4a23-801e-e744aecb7b03",
"entity_type": "case",
"datetime_requested": "2024-01-01T12:38:45.711Z",,
"message": "Income request pending"
}
Record the request_id from the response as it will be required to check the status.
Check the Status of the Request
If you have configured any webhooks that reference the IncomeEmployerInsights.Completed event you will receive a request of this event type as soon as the affordability insights process has completed. Check out our webhooks guide for more information on how to set up and configure webhooks.
Alternatively, you can monitor the status of the request by polling the GET Income & Employer endpoint. Specify the request_id for the relevant entity in the request. Wait for a Complete status to be achieved before retrieving the verification results.
{
"request_id": "w5f84a41-01cf-4d21-901d-124c5a7c743a",
"status": "Pending",
"entity_id": "b3f6ed8f-bc57-4a23-801e-e744aecb7b03",
"entity_type": "case",
"datetime_requested": "2024-01-01T12:38:45.711Z",
"message": "Income request pending"
}
Retrieve Income & Employer Verification
Once you've requested income & employer verification and the status of your request is complete, you can retrieve the results.
The results include an overview of annual gross pay, monthly gross pay, and monthly net pay broken down by income recipient and further delineated by income type and source. They also include additional details about bonus payments and mandatory student loan repayments. The response will also list all of the different data sources which were used to complete the verification.
Use the GET Income & Employer endpoint and ensure the relevant request_id is specified in the URL.
{
"request_id": "8ef5079a-b3de-44a5-b4ff-c534259e752c",
"status": "Pending",
"entity_id": "b3f6ed8f-bc57-4a23-801e-e744aecb7b03",
"entity_type": "case",
"datetime_requested": "2024-01-01T12:38:45.711Z",
"datetime_completed": "2024-01-02T12:22:07.747Z",
"message": "Income request pending",
"data": {
"income_details": [
{
"income_recipient": "Sharon Smith",
"income_type": "Employment",
"income_source": "BUILDING HOME LTD",
"annual_gross_pay": "23657.04",
"monthly_gross_pay": "1971.42",
"monthly_net_pay": "1561.93",
"additional_information": {
"bonuses": [
{
"amount": "222.22",
"date": "2024-01-01"
}
],
"monthly_gross_pay_details": [
{
"category": "Monthly Basic Pay",
"amount": "1000.00"
},
{
"category": "Monthly Commission Pay",
"amount": "971.42"
}
],
"monthly_student_loan_deductions": "222.44"
},
"income_data_sources": [
{
"source_type": "Payslip",
"number_of_sources": 1,
"date_range_start_date": "2024-01",
"date_range_end_date": "2024-01",
"data_sources": [
{
"source_name": "PayslipFile.pdf",
"source_id": "4b9ac393-d34b-4a14-9ee3-88ce2d244e90",
"source_category_type": "Document",
"source_type": "Payslip"
}
]
}
]
}
],
"data_sources": [
{
"source_name": "PayslipFile.pdf",
"source_id": "4b9ac393-d34b-4a14-9ee3-88ce2d244e90",
"source_category_type": "Document",
"source_type": "Payslip"
}
]
}
}
For a full list of potential income_types and monthly gross pay categories, click here.
Updated about 1 month ago