Follow this guide to understand how you can integrate your application with payiroll® using REST.
Overview #
Use cases #
Your application needs to:
- POST worker and pay information via API
- GET live and historic payslips
Steps #
The following steps would allow you to POST data and GET live payslips:
| API call | What Data | Description | Notes |
|---|---|---|---|
| /api/v1/upload/{id}/start/ | Workers | Start the worker data feed | New workers will be automatically added as starters. Existing workers will be updated. Leavers are set if there is a leave date. |
| /api/v1/upload/{id}/poll/ | Workers | Poll for completion | Errors are listed here |
| /api/v1/upload/{id}/start/ | Pay | Start the pay data feed | This step can be repeated as often as required. |
| /api/v1/upload/{id}/poll/ | Pay | Poll for completion | |
| /api/v1/company/{id}/payslips/ | Payslip (live) | Returns a live payslip for each employee, for each pay schedule. |
Other operations not covered above are completed in the GUI, for example, submitting a final pay run. This means that the effort for API development integration is typically a few hours, and an order of magnitude less than with other systems.
Data formats #
Data is formatted as a list of lists or a list of dicts.
Shift pay POST payload examples #
The hours and rates are provided from your application:
[
["Works Id", "Rate", "Units"],
["B1", "55.55", "1"],
["C1", "12.34", "5"]
][
{"Works Id": "B1", "Rate": "55.55", "Units": "1"},
{"Works Id": "C1", "Rate": "12.34", "Units": "5"},
]Worker POST payload examples: #
Many columns are optional, and the uploader will provide defaults:
{
"username": "robinson.crusoe@example.net",
"email": "robinson.crusoe@example.net",
"is_active=True": "",
"title": "",
"name": "Robinson Crusoe",
"mobile": "",
"preferences={}": "",
"works_id": "RC1",
"start_date": "2025-01-01",
"working_days": "{{true,true,true,true,true,false,false}}",
"fte": "",
"end_date": "",
"original_start_date": "",
"department": "Candidates",
"existing_employee=False": "",
"notes": "",
"uploaded=": "True",
"external_uid=": "",
"postaldetail.line1": "221B",
"postaldetail.line2": "Baker Street",
"postaldetail.line3": "Lonoon",
"postaldetail.line4": "",
"postaldetail.postcode": "{W1A 1AA",
"postaldetail.foreign_country": "",
"taxdetail.weekly_hours_worked=Other": "",
"taxdetail.P45_tax_code=": "",
"taxdetail.P45_week1_month1=False": "",
"taxdetail.P45_leaving_date=": "",
"taxdetail.P45_total_pay_to_date=": "",
"taxdetail.P45_total_tax_to_date=": "",
"taxdetail.P45_continue_student_loan=0": "",
"taxdetail.P45_continue_postgraduate_loan=0": "",
"taxdetail.NI_category=General": "",
"taxdetail.workplace_postcode=": "",
"taxdetail.director=False": "",
"taxdetail.director_from=": "",
"taxdetail.director_NI_cumulative=False": "",
"taxdetail.paid_irregularly=False": "",
"taxdetail.off_payroll_worker=False": "",
"taxdetail.migrated_rti_payid=": "",
"taxdetail.cis=": "",
"taxeedetail.date_of_birth": "1970-02-02",
"taxeedetail.gender": "Male",
"taxeedetail.NI_number": "AB123456A",
"taxeedetail.employee_statement": "",
"taxeedetail.student_loan=0": "",
"taxeedetail.postgraduate_loan=0": "",
"taxeedetail.cis_trading_name=": "",
"taxeedetail.cis_utr=": "",
"taxeedetail.cis_crn=": "",
"bankdetail.account_name": "R CRUSOE",
"bankdetail.sort_code": "000000",
"bankdetail.account_number": "00000000",
"bankdetail.payment_method=": ""
}Data Validation #
paiyroll® will typically perform extensive validation on the data. For example, national insurance numbers, bank details, and so on. Full row-by-row error reporting is available from the poll request. Usually, you should present these to the user so they can correct any errors in your application. Once corrected, you can re-post.