Income verification data structure
After each successful transaction you will be provided with a response including the following data set and the respective payslip file provided by the Payroll platform / end-user (via upload). Some data points are not always available, due to the difference of information provided by the different payroll providers.
Employment Data
- Employee Name, Address, Employee ID, National Insurance No., Email
- Employer Name and Address
- Start and End Date of employment
Payslip Data
- Month, Pay date, Tax Month,
- Currency, Payment Method
- Data Source, Payslip file
Salary Data
- Total monthly earning, variable earnings
- Total monthly deduction, variable deductions
- YTD earnings
- YTD tax and NI contributions
- Annual Salary
You can find a link to the payslip file inside the transaction response. That link will be downloadable for at least 3 months.
Data points
The following list will show you what data points are provided in the response and specially which of the data is always provided and which ones can vary.
API JSON Response values
All values that are marked optional won't appear in the JSON response if missing on the payslip / hr portal.
For all mandatory fields, it can happen due to a flawed / faulty payslip, that a value is missing, which then will be having a "null" value. In this case we advise to re-check the attached payslip and contact your end user.
You will find this information also in the GET Transaction endpoint section of the API reference.
| Atributes | Description |
|---|---|
| status | Status of the transaction (Pending, Failed, Completed, Timeout) |
| provider (string) | Payroll / HR provider name OR 'manual upload' |
| created _at | Time of transaction creation |
| update_at | Last update of the transaction |
| employee (string) | All data in that block relate to the employee |
| employee_id* (string) | Internal company ID of the employee, displayed on the payslip / HR tool |
| full_name (string) | Employees full name |
| address* (string) | Employee address |
| tax_code (string) | Employee tax code |
| ni_number (string) | Employee National Insurance number (N.I.) |
| annual_salary* (string) | Employees annually salary as displayed on the payslip |
| employee_email** (string) | Employee personal email |
| employment_startdate** (string) | Start date of the current employment |
| employer (string) | All data in that block relate to the employer |
| name (string) | Employer name |
| address** (string) | Employer address |
| summary | |
| payslip_month (string) | Month of the issued Payslip |
| payment_date (string) | Salary payment date |
| tax_period (string) | Tax period |
| payment_method* (string) | Salary payment method |
| amount_paid (string) | Total net amount paid to employee |
| paystub_file (string) | Link to download the payslip |
| earnings (string) | All data in that block relate to the earnings displayed on that months payslip |
| basic_pay (string) | Employee monthly salary |
| variable_earnings (array) | Optional and variable item in the monthly earnings list (array). |
| total_earnings (string) | Sum of all Items in the earnings block (displayed on the payslip) |
| deductions | All data in that block relate to the deductions displayed on that months payslip |
| tax_deductions (string) | Employee income tax |
| social_security (string) | Employee N.I. contributions |
| variable_deductions (array) | Optional and variable item in the monthly deduction list |
| total_deductions (string) | Sum of all Items in the deductions block (displayed on the payslip) |
| tax_year_to_date | |
| accumulative_gross_pay (string) | Year to date gross pay of this employment |
| accumulative_taxable_pay (string) | Year to date taxable pay of this employment |
| accumulative_ni (string) | Year to date national insurance contribution |
| total_tax_paid (string) | Total amount of tax paid year to date |
*not always available on payslips
**data retrieved directly from the HR portal, not always possible