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