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.
Retrieve the Overview
The results provide a comprehensive overview, including annual gross pay, monthly gross pay, and monthly net pay, organized by income recipient and further categorized by income type and source. Additionally, the results detail the breakdown of monthly gross pay, deductions, and bonus payments. The response also lists all data sources utilized to complete the verification.
Use the GET Income & Employer endpoint and ensure the relevant request_id is specified in the URL.
{
"request_id": "fb93d887-6c30-436e-b9d4-6c435cfd127e",
"status": "Complete",
"entity_id": "a8d7db86-67ff-42cf-abfe-d7ad281fdb34",
"entity_type": "case",
"datetime_requested": "2024-11-22T11:33:29.635Z",
"datetime_completed": "2024-11-22T11:33:41.883Z",
"message": null,
"data": {
"income_details": [
{
"income_recipient": "Sam Weetabix",
"income_type": "Employment",
"income_source": "Cereals-R-Us",
"annual_gross_pay": 45363.72,
"monthly_gross_pay": 3780.31,
"monthly_deductions": 1108.13,
"monthly_net_pay": 2672.18,
"pay_frequencies": [
"Monthly"
],
"additional_information": {
"bonuses": [
{
"amount": 225,
"date": "2023-12-31"
},
{
"amount": 800,
"date": "2023-11-30"
}
],
"monthly_student_loan_deductions": 194.33,
"monthly_gross_pay_details": [
{
"category": "MonthlyBasicPay",
"amount": 2355.32
},
{
"category": "MonthlyBonusPay",
"amount": 341.67
},
{
"category": "MonthlyCommissionPay",
"amount": 239.58
},
{
"category": "MonthlyCarAllowancePay",
"amount": 742.08
},
{
"category": "MonthlyShiftAllowancePay",
"amount": 16.67
},
{
"category": "MonthlyOvertimePay",
"amount": 84.99
}
],
"monthly_deductions_details": [
{
"category": "MonthlyIncomeTax",
"amount": 555.2
},
{
"category": "MonthlyNationalInsurance",
"amount": 358.6
},
{
"category": "MonthlyStudentLoan",
"amount": 194.33
}
]
},
"income_data_sources": [
{
"source_type": "Payslip",
"number_of_sources": 3,
"start_date": "2023-10",
"end_date": "2023-12",
"data_sources": [
{
"source_name": "Sample payslips - monthly - Sam Weetabix - 1 of 3.pdf",
"source_id": "2cb4ae89-ffc4-4d65-913c-e80e225bde41",
"source_category_type": "Document",
"source_type": "Payslip"
},
{
"source_name": "Sample payslips - monthly - Sam Weetabix - 2 of 3.pdf",
"source_id": "5eea3a1b-cd7f-4f30-9f42-0a31caf516a1",
"source_category_type": "Document",
"source_type": "Payslip"
},
{
"source_name": "Sample payslips - monthly - Sam Weetabix - 3 of 3.pdf",
"source_id": "6379959c-7659-49f2-82b5-cabe017d16b7",
"source_category_type": "Document",
"source_type": "Payslip"
}
]
}
],
"job_titles": [
"Food Technologist"
],
"tax_codes": [
"1204L"
]
}
],
"data_sources": [
{
"source_name": "Sample payslips - monthly - Sam Weetabix - 1 of 3.pdf",
"source_id": "2cb4ae89-ffc4-4d65-913c-e80e225bde41",
"source_category_type": "Document",
"source_type": "Payslip"
},
{
"source_name": "Sample payslips - monthly - Sam Weetabix - 2 of 3.pdf",
"source_id": "5eea3a1b-cd7f-4f30-9f42-0a31caf516a1",
"source_category_type": "Document",
"source_type": "Payslip"
},
{
"source_name": "Sample payslips - monthly - Sam Weetabix - 3 of 3.pdf",
"source_id": "6379959c-7659-49f2-82b5-cabe017d16b7",
"source_category_type": "Document",
"source_type": "Payslip"
}
]
}
}
For a full list of potential income_types and monthly gross pay categories, click here.
Retrieve the Additional Details View
The additional details view offers an in-depth look at the data extracted from each individual payslip and bank statement used in the income and employer verification process. This allows you to validate all available data points exactly as they appear on the original payslip or bank statement, enhancing the accuracy of the validation process.
Use the GET Income & Employer endpoint and ensure the relevant request_id is specified in the URL.
Example: Three monthly payslips provided
This example shows the additional details view for a case with a single applicant who has submitted three monthly payslips. All available data can be reviewed and validated as presented in each payslip.
{
"request_id":"fb93d887-6c30-436e-b9d4-6c435cfd127e",
"status":"Complete",
"entity_id":"a8d7db86-67ff-42cf-abfe-d7ad281fdb34",
"entity_type":"case",
"datetime_requested":"2024-11-22T11:33:29.635Z",
"datetime_completed":"2024-11-22T11:33:41.883Z",
"message":null,
"data":[
{
"income_recipient":"Sam Weetabix",
"income_type":"Employment",
"income_source":"Cereals-R-Us",
"details":[
{
"source_type":"Payslip",
"source_id":"6379959c-7659-49f2-82b5-cabe017d16b7",
"source_name":"Sample payslips - monthly - Sam Weetabix - 3 of 3.pdf",
"income_source_data":{
"payslip_date":"2023-12-31",
"pay_period_start_date":null,
"pay_period_end_date":null,
"payment_date":"2023-12-31",
"pay_frequency":"Monthly",
"gross_pay":3831.61,
"total_deductions":1129.15,
"detailed_deduction_items":[
{
"category":"IncomeTax",
"short_description":"P.A.Y.E.",
"value":565.4
},
{
"category":"NationalInsurance",
"short_description":"N.I.",
"value":364.75
},
{
"category":"StudentLoan",
"short_description":"Student Loan",
"value":199
}
],
"net_pay":2702.46,
"detailed_pay_items":[
{
"category":"BasicPay",
"short_description":"Salary",
"value":2531.83
},
{
"category":"BasicPay",
"short_description":"Salary Sacrifice",
"value":-182.76
},
{
"category":"CarAllowancePay",
"short_description":"Car Allowance",
"value":742.08
},
{
"category":"CommissionPay",
"short_description":"Commission",
"value":381.27
},
{
"category":"OvertimePay",
"short_description":"Overtime",
"value":134.19
},
{
"category":"BonusPay",
"short_description":"Bonus",
"value":225
}
]
}
},
{
"source_type":"Payslip",
"source_id":"5eea3a1b-cd7f-4f30-9f42-0a31caf516a1",
"source_name":"Sample payslips - monthly - Sam Weetabix - 2 of 3.pdf",
"income_source_data":{
"payslip_date":null,
"pay_period_start_date":null,
"pay_period_end_date":null,
"payment_date":"2023-11-30",
"pay_frequency":"Monthly",
"gross_pay":4107.73,
"total_deductions":1242.69,
"detailed_deduction_items":[
{
"category":"IncomeTax",
"short_description":"P.A.Y.E.",
"value":620.8
},
{
"category":"NationalInsurance",
"short_description":"N.I.",
"value":397.89
},
{
"category":"StudentLoan",
"short_description":"Student Loan",
"value":224
}
],
"net_pay":2865.04,
"detailed_pay_items":[
{
"category":"BasicPay",
"short_description":"Salary",
"value":2531.83
},
{
"category":"BasicPay",
"short_description":"Salary Sacrifice",
"value":-174.09
},
{
"category":"CarAllowancePay",
"short_description":"Car Allowance",
"value":742.08
},
{
"category":"CommissionPay",
"short_description":"Commission",
"value":207.91
},
{
"category":"BonusPay",
"short_description":"Bonus",
"value":800
}
]
}
},
{
"source_type":"Payslip",
"source_id":"2cb4ae89-ffc4-4d65-913c-e80e225bde41",
"source_name":"Sample payslips - monthly - Sam Weetabix - 1 of 3.pdf",
"income_source_data":{
"payslip_date":null,
"pay_period_start_date":null,
"pay_period_end_date":null,
"payment_date":"2023-10-31",
"pay_frequency":"Monthly",
"gross_pay":3401.59,
"total_deductions":952.55,
"detailed_deduction_items":[
{
"category":"IncomeTax",
"short_description":"P.A.Y.E.",
"value":479.4
},
{
"category":"NationalInsurance",
"short_description":"N.I.",
"value":313.15
},
{
"category":"StudentLoan",
"short_description":"Student Loan",
"value":160
}
],
"net_pay":2449.04,
"detailed_pay_items":[
{
"category":"BasicPay",
"short_description":"Salary",
"value":2531.83
},
{
"category":"BasicPay",
"short_description":"Salary Sacrifice",
"value":-172.67
},
{
"category":"CarAllowancePay",
"short_description":"Car Allowance",
"value":742.08
},
{
"category":"ShiftAllowancePay",
"short_description":"On Call Allow",
"value":50
},
{
"category":"CommissionPay",
"short_description":"Commission",
"value":129.57
},
{
"category":"OvertimePay",
"short_description":"Overtime",
"value":120.78
}
]
}
}
]
}
]
}
Example: One payslip and one bank statement provided
This example illustrates the additional details view for a case with a single applicant, featuring one monthly payslip and one bank statement.
The structure of the
income_source_dataobject varies depending on thesource_type, as payslips and bank statements capture significantly different types of information.
{
"request_id": "8dcf5534-b019-4be3-9d8e-66d40f20ae58",
"status": "Complete",
"entity_id": "c98f0f60-4494-42a8-b819-347b8da58561",
"entity_type": "case",
"datetime_requested": "2024-11-26T10:15:41.956Z",
"datetime_completed": "2024-11-26T10:16:00.591Z",
"message": null,
"data": [
{
"income_recipient": "Sam Weetabix",
"income_type": "Employment",
"income_source": "Cereals-R-Us",
"details": [
{
"source_type": "Payslip",
"source_id": "aef63d0c-390b-44dd-82ec-5ab752838c6d",
"source_name": "Sample data A - monthly pay - Sam Weetabix - payslip 2024-10-31.pdf",
"income_source_data": {
"payslip_date": "2024-10-31",
"pay_period_start_date": null,
"pay_period_end_date": null,
"payment_date": "2024-10-31",
"pay_frequency": "Monthly",
"gross_pay": 4107.73,
"total_deductions": 1242.69,
"detailed_deduction_items": [
{
"category": "IncomeTax",
"short_description": "P.A.Y.E.",
"value": 620.8
},
{
"category": "NationalInsurance",
"short_description": "N.I.",
"value": 397.89
},
{
"category": "StudentLoan",
"short_description": "Student Loan",
"value": 224
}
],
"net_pay": 2865.04,
"detailed_pay_items": [
{
"category": "BasicPay",
"short_description": "Salary",
"value": 2531.83
},
{
"category": "BasicPay",
"short_description": "Salary Sacrifice",
"value": -174.09
},
{
"category": "CarAllowancePay",
"short_description": "Car Allowance",
"value": 742.08
},
{
"category": "CommissionPay",
"short_description": "Commission",
"value": 207.91
},
{
"category": "BonusPay",
"short_description": "Bonus",
"value": 800
}
]
}
}
]
},
{
"income_recipient": "Sam Weetabix",
"income_type": "Benefits",
"income_source": "Hmrc Child Benefit",
"details": [
{
"source_type": "BankStatement",
"source_id": "ce3d50e4-e7d9-413e-b251-a6e2b24922b8",
"source_name": "Sample data A - monthly pay - Sam Weetbix - bank statement to 2024-10-09.pdf",
"income_source_data": {
"start_date": "2024-09-10",
"end_date": "2024-10-09",
"net_pay": 139.75,
"detailed_pay_items": [
{
"category": "Benefits",
"short_description": "Hmrc Child Benefit",
"value": 139.75
}
]
}
}
]
},
{
"income_recipient": "Sam Weetabix",
"income_type": "Employment and/or Self-employment",
"income_source": "Salary Sam Weetabix Cereals-R-Us",
"details": [
{
"source_type": "BankStatement",
"source_id": "ce3d50e4-e7d9-413e-b251-a6e2b24922b8",
"source_name": "Sample data A - monthly pay - Sam Weetbix - bank statement to 2024-10-09.pdf",
"income_source_data": {
"start_date": "2024-09-10",
"end_date": "2024-10-09",
"net_pay": 2449.04,
"detailed_pay_items": [
{
"category": "Employment and/or Self-employment",
"short_description": "Salary SAM Weetabix CEREALS-R-US",
"value": 2449.04
}
]
}
}
]
}
]
}
Updated 22 days ago