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.

statusStatus of the transaction (Pending, Failed, Completed, Timeout)
provider (string)Payroll / HR provider name OR 'manual upload'
created _atTime of transaction creation
update_atLast 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
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)
deductionsAll 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)
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