Workers - API Requests

Workers - API Requests

This document provides information about the PurePro public API endpoints associated with worker operations and their objects.
Common operations;

https://slite.com/api/files/xlzuniJ3ouQOid/imported-image?apiToken=eyJhbGciOiJIUzI1NiIsImtpZCI6IjIwMjMtMDUtMDQifQ.eyJzY29wZSI6Im5vdGUtZXhwb3J0IiwibmlkIjoidG43QnNGazE2M0pfOEQiLCJpYXQiOjE3ODcyNTc1MzAsImlzcyI6Imh0dHBzOi8vc2xpdGUuY29tIiwianRpIjoicnBVR2tfT1NSVXVHVkgiLCJleHAiOjE3ODk4NDk1MzB9.7Acu8l-dnBMhATBCvF3a3kk3lOZ1dQO6ex4f7Cj2OJ8
APIs are Business Unit-specific and do not follow the Parent–Child Business Unit hierarchy.
The Worker must belong to the same Business Unit as the API request.
Please select one of the options below: -

Get Workers

Method:
BaseURL: {{publicApiUrl}}/Worker/{{accountReference}}/{{businessUnitReference}}/Worker_REF
To retrieve details for a specific worker. To retrieve worker details, users would need to pass account and business unit reference to the base URL, along with the worker reference.

PAYE Workers

PAYE Worker Add

Method:

https://slite.com/api/files/0l5RI4hm-bSGFM/imported-image?apiToken=eyJhbGciOiJIUzI1NiIsImtpZCI6IjIwMjMtMDUtMDQifQ.eyJzY29wZSI6Im5vdGUtZXhwb3J0IiwibmlkIjoidG43QnNGazE2M0pfOEQiLCJpYXQiOjE3ODcyNTc1MzAsImlzcyI6Imh0dHBzOi8vc2xpdGUuY29tIiwianRpIjoicnBVR2tfT1NSVXVHVkgiLCJleHAiOjE3ODk4NDk1MzB9.7Acu8l-dnBMhATBCvF3a3kk3lOZ1dQO6ex4f7Cj2OJ8
BaseURL: {{publicApiUrl}}/Worker/{{accountReference}}/{{businessUnitReference}}
To add a PAYE worker using the public API you must pass the account reference and business unit reference to the Base URL with the required objects in the body. Refer to  Appendix A⁠  containing a sample of the request body.
Property
Validations
Account
  • Cannot be Null
  • Cannot be left blank
Business Unit
  • Cannot be Null
  • Cannot be left blank
The dependencies and validations are:
Property
Acceptable Format
Validations
Refrence
String
  • Cannot be null
  • Can be blank and the system will automatically generate a reference from the worker if reference settings is not set as manual
Title
String
  • Cannot be Null
  • You must provide a Title for the worker
  • If contains Invalid Characters
  • Title must only contain Alpha Numeric characters
  • If contains Insufficient Characters
  • Title must be between 2 and 14 characters only
Surname
String
  • You must provide a worker surname
  • Must not contain Insufficient Characters
  • Worker Surname must be between 2 and 26 characters only
  • Must not contain Invalid Characters
Forename
String
  • You must provide a worker surname
  • Must not contain Insufficient Characters
  • Worker Forename must be between 2 and 26 characters only
  • Must not contain Invalid Characters
EngagementType
String
  • Cannot be Null
  • Cannot be Blank
  • Accepted value - Paye
DateOfBirth
Date Time
  • Cannot be Null
  • You must enter a worker DOB
  • Underage
  • Age must be greater than 16
  • Overage
  • Age must be less than 100
  • Acceptable format: 1986-04-21T00:00:00
StartDate
Date Time
  • Cannot be Null
  • You must enter a Start Date
  • Invalid Start Date
  • Start Date cannot be after the Leave Date
  • Acceptable format: 2020-01-28T00:00:00
LeaverReason
String
  • Can be Null
  • Cannot be blank
  • You must provide a reason for leaving when specifying Leave Date
  • Invalid Reason for Leaving
  • You must provide a valid Reason for Leaving.
  • Acceptable values are: - “Contract Terminated", "Found Alternative Work", "Found Permanent Job", "Placed Permanent", "Deceased", "Inactive Worker"
LeaveDate
String
  • Can be Null
  • Cannot be blank
  • You must provide a Leave Date if Leaver Reason has been provided
  • Invalid Leave Date
  • Leave Date cannot be before the Start Date
  • Accepted format: 2020-01-28T00:00:00
Gender
String
  • Cannot be Null
  • Cannot be blank
  • You must provide a Gender
  • Invalid Gender
  • You must provide a valid Gender Value.
  • Acceptable values are: “Male” and “Female”.
ShiftPattern
String
  • Can be Null
  • If shiftPattern = null then no shift pattern is allocated to the worker
  • Acceptable values are: "FULL_WEEK", "WEEKDAYS", "Weekends", "MON_WED_FRI"
NormalWorkingHours
String
  • Can be Null
  • Cannot be blank
  • Accepts values - A/B/C/D/E → corresponds to
  • A = Other
  • B = Upto 15.99 hours
  • C = 16.23.99 hours
  • D = 24 to 29.99 hours
  • E = 30 hours or more
IrregularEmployment
Boolean
  • Cannot be left blank
  • Cannot be Null
  • Must be either true or false
PaymentMethod
String
  • Cannot be Null
  • You must provide a Payment Method
  • Invalid Payment Method
  • You must provide a valid Payment method.
  • Acceptable values are: “BACS”, “Cheque”, “Manual”, “Cash”, “Chaps”
PayslipDeliveryMethod
String
  • Cannot be Null
  • You must provide a Payslip Delivery Method.
  • Acceptable values are: - “Email”, “Paper, “Online”
  • If the key payslipdeliverymethod = “paper” then email detail is not required can be left blank
  • if the key payslipdeliverymethod = “email” and no email detail provided then validation appear
PayrollDataUK
  • Cannot be Null
  • Can be left blank (where not null)
  • e.g. "payrollDataUk": {},
If left blank, PayrollDataUk will default the StarterForm to "StartingDeclaration" & EmploymeeStatement to "Unkown"
PayrollDataUK Subfields -
PaymentAfterLeaving
  • Can be null
  • Can be left blank (where not null)
  • This is Optional
  • If provided, value must be "True" or "False"
PreviousIsWeek1Value
  • Can be null
  • Can be left blank (where not null)
  • This is Optional
  • If provided, value must be "True" or "False"
PreviousTaxCode
  • Can be null
  • Cannot be left blank (where not null)
  • This is Optional
  • Accepted format: “1257L”
NiLetter
  • Can be null
  • Cannot be left blank (where not null)
  • This is Optional
  • If provided, must be a valid NI letter
WorkplacePostcode
  • Can be null
  • Cannot be left blank (where not null)
  • This is required if NI Letter = F/I/S/L/N/E/K/D
StarterForm
  • Cannot be Null
  • Can be blank (where not null)
  • This is Optional
  • If starterForm = P45 and isWeek1 = “False” then P45 leaving date and P45 week number must be supplied
  • P45 month number must not be greater than 12
  • P45 week number must not be greater than 53
  • P45 Period is required when starter form is P45
  • P45 Frequency is required when starter form is P45
  • P45 Leaving Date Required
  • Acceptable values are: "StartingDeclaration", "P45"
  • If starterForm = “startingdeclaration” then employeeStatement needs to be either "A", "B", “C”, “Unknown”
EmployeeStatement will default to "Starter Form" if not provided in the API request
EmployeeStatement
  • If starterForm = “startingdeclaration” then employeeStatement needs to be either "A", "B", “C”, “Unknown”
  • This is Optional
EmployeeStatement will default to "Statement Unknown" if not provided in the API request
TaxCode
  • Can be null
  • Can be blank (where not null)
  • This is Optional
  • If invalid tax code value is provided then the following validation will appear
  • Invalid Tax Code provided - Please check the tax code provided is in a valid format
  • Accepted format: “1257L”
Tax Code will default to the tax code as per the EmployeeStatement
IsWeek1
  • Can be null
  • Cannot be left blank (where not null)
  • This is Optional
  • If provided, value must be "True" or "False"
IsWeek1 will default to the value as per the EmployeeStatement
P45LeavingDate
  • Can be null
  • Cannot be left blank (where not null)
  • This is Optional
  • This is required only if StarterForm = P45
  • Accepted format = Date&Time e.g. 2020-12-06T00:00:00
P45Frequency
  • Can be null
  • Cannot be left blank (where not null)
  • This is Optional
  • This is required only if StarterForm = P45
  • Accepted values = "Week" or "Month" based on the payroll frequency
P45Period
  • Can be null
  • Cannot be left blank (where not null)
  • This is Optional
  • This is required only if StarterForm = P45
  • Accepted values integer (valid week or month number)
P45YtdGross
  • Can be null
  • Cannot be left blank
  • Can be 0
  • This is Optional
P45YtdTaxx
  • Can be null
  • Cannot be left blank
  • Can be 0
  • This is Optional
P45FiguresValid
  • Can be null
  • Can be left blank
  • This is Optional
  • If provided, value must be "True" or "False"
normalWorkingHours
  • Can be null
  • Cannot be left blank (where not null)
  • This is Optional
  • If provided, accepted values = A/B/C/D/E
IrregularEmployment
  • Can be null
  • Cannot be left blank (where not null)
  • This is Optional
  • If provided, value must be "True" or "False"
RTINumber
  • Can be null
  • Cannot be left blank (where not null)
  • This is Optional
  • If provided, value must be "True" or "False"
Apprentice
  • Can be null
  • Cannot be left blank (where not null)
  • This is Optional
  • If provided, value must be "True" or "False"
DirectorNi
  • Can be null
  • Cannot be left blank (where not null)
  • This is Optional
  • If provided, value must be "True" or "False"
DirectorNiMethod
  • Can be null
  • Cannot be left blank (where not null)
  • This is Optional
  • If provided, value must be "IrregularPayments" or "AlternatePayments"
P45ValidationBypass
  • Can be null
  • Cannot be left blank (where not null)
  • This is Optional
  • If provided, value must be "True" or "False"
Address
String
  • Can be null
  • If the address record doesn’t exist in the body, then will return 200 but record will display as failed validation error in the webapp
  • You must enter the Address Line 1
  • Address Line 1 must be between 1 and 35 characters
  • You must enter a postcode
  • Postcode - incorrect format
  • Worker has missing address detail. Please ensure at least 2 lines of the address are populated.
InternationalAddress
String
  • Can be true or false
  • If InternationalAddress = true
  • Mandatory values:
  • address1
  • address2
  • Country
Note: If Country = GB and InternationalAddress = true, then the supplied worker linked to the supplier record will be marked as validation error “Cannot set International Address when Country is UK for the supplier xx”.
Country can be provided using either the country code e.g. UK or the name e.g. United Kingdom
If InternationalAddress = false
  • Mandatory values:
  • address1 and
  • address2 or
  • address3 or
  • Town or
  • County
  • Postcode
  • InternationalAddress can be true or false
BankAccount
String
  • Can be null
  • If the bank details record doesn’t exist in the body, then will return 200 but record will display as failed validation error
  • Valid Account Name is required
  • Account Number must be 8 digits long
  • Sort Code must be 6 digits long
  • If the key paymentMethod = “cheque” then bank details are not required can be left blank otherwise you will receive the following validation: You must provide a valid Payment method.
InternationalBankAccount
String
When InternationalBankAccount = true
  • Mandatory values
  • AccountName
  • IBAN
  • BIC
  • Optional values:
  • BankReference
  • BankName
All other fields are ignored regardless of entry.
When InternationalBankAccount = false
  • Mandatory values:
  • AccountName
  • SortCode
  • AccountNumber
  • Optional values:
  • BankReference
  • BankName
InternationalBankAccount details can only be provided when BACS is set as "NatWest Bankline International"
PensionSchemeMember
String
  • Can be null
  • If the pensionSchemeMember record not provided, system will use the default pension scheme set in the configuration
  • schemeReference can be null
  • In the event, the provided pension scheme reference does not exist, the system assigns the default pension scheme set under account configuration
IsWeek1
String
  • Cannot be null
  • Can be true or false
  • If isWeek1 = true then P45LeavingDate, P45Frequency, P45Period, P45YtdGross and P45YtdTax are not required
Apprentice
String
  • Cannot be null
  • Can be true or false
  • If apprentice = true then NI Letter must be H otherwise will create the record and fail validation
  • NI Letter is not H but Worker is an apprentice
HolidayScheme
String
  • Cannot be null
  • Can be left blank holidayScheme = “”

PAYE Worker Update

Method: 
BaseURL: {{publicApiUrl}}/Worker/{{accountReference}}/{{businessUnitReference}}
To update a PAYE worker using the public API you need to pass the account and business unit reference to the Base URL with the required objects in the body. Refer to  Appendix B⁠  containing a sample of the request body.

Contractor Workers

Contractor Worker Add

Method: 
BaseURL: {{publicApiUrl}}/Worker/{{accountReference}}/{{businessUnitReference}}
To add a contractor worker using the public API you need to pass the account and business unit reference to the URL with the required objects in the body. Refer to  Appendix C ⁠ containing a sample of the request body.
The key dependencies are: -
Users can add PayrollDataUK for contractors to add them as IR35
Sample PayrollDataUK - 
"payrollDataUK": {
"niLetter": "A",
"starterForm": "P45",
"employeeStatement": "A",
"taxCode": "1250L",
"isWeek1": false,
"p45LeavingDate": "2022-02-02T00:00:00",
"p45Frequency": "Week",
"p45Period": "2",
"p45YtdGross": 120.00,
"p45YtdTax": 12.00
}

Contractor worker Update

Method: 
BaseURL: {{publicApiUrl}}/Worker/{{accountReference}}/{{businessUnitReference}}
To update a contractor worker using the public API you need to pass the account and business unit reference to the Base URL with the required objects in the body. Refer to  Appendix D⁠  containing a sample of the request body.
Most of the key dependencies and validations are the same as the Worker ADD as described in previous sections.
Sample PayrollDataUK - 
"payrollDataUK": {
"niLetter": "A",
"starterForm": "P45",
"employeeStatement": "A",
"taxCode": "1250L",
"isWeek1": false,
"p45LeavingDate": "2022-02-02T00:00:00",
"p45Frequency": "Week",
"p45Period": "2",
"p45YtdGross": 120.00,
"p45YtdTax": 12.00
}

Supplied Workers (Agency & Umbrella)

Agency/Umbrella worker Add

Method: 
BaseURL: {{publicApiUrl}}/Worker/{{accountReference}}/{{businessUnitReference}}
To add an Agency or Umbrella worker record using the public API you need to pass the account and business unit reference to the BASE URL with the required objects in the body. Refer to  Appendix G⁠  containing a sample of the request body.
Note: A worker record can be created with or without contact and address objects
The key dependencies and validations are:

Agency/Umbrella worker Update

Method: 
BaseURL: {{publicApiUrl}}/Worker/{{accountReference}}/{{businessUnitReference}}
To update an Agency or Umbrella worker record using the public API you need to pass the account and business unit reference to the BASE URL with the required objects in the body. Refer to  Appendix H⁠  containing a sample of the request body.
A worker record can be updated with or without contact and address objects

Search

WorkerSearch

Method:
BaseURL: {{publicApiUrl}}/Worker/WorkerSearch?page=1&size=10
To search a worker using a specific search term. This parameter can also be used as a "Global Search" to search for the term across all accounts and business units (user has access to)
The key dependencies are:-

WorkerReferenceSearch

Method:
BaseURL: {{publicApiUrl}}/Worker/workerReferenceSearch
To search a worker using a worker reference. This endpoint can be used as "Global Search" across all business units within the specified account.
The key dependencies are: -

Transfers

Worker Transfer

Method:
BaseURL: {{publicApiUrl}}/Worker/TransferWorker
Users can transfer workers from one account to another.
For further information, please refer to our  🔄Worker Transfer⁠  guide.
The key dependencies are: -
For further information on worker transfers, please refer to our  🔄Worker Transfer⁠  guide.

Revert Worker Transfer

Method:
BaseURL: {{publicApiUrl}}/Worker/RevertTransferWorker
Users can transfer workers from one account to another.
For further information, please refer to our  Worker Transfer  guide.
The key dependencies are: -
For further information on worker transfers, please refer to our  🔄Worker Transfer⁠  guide.

Restart Worker

Method:
BaseURL: {{publicApiUrl}}/Worker/RestartWorker/{{accountReference}}
To restart a worker, users would need to pass the account and business unit reference to the base URL.
For further information on worker transfers, please refer to our  Worker Restart⁠  guide.

Payment After Leaving

Method:
BaseURL: {{publicApiUrl}}/Leaver/UpdateWorkerForPaymentAfterLeaving/{{accountReference}}/{{businessUnitReference}}?workerReference=Worker_REF
To enable payment after leaving for a left worker, users would need to pass the account and business unit reference to the base URL, along with the worker reference.
For further information on worker transfers, please refer to our  Payment After Leaving⁠  guide.

The contents of this document, along with any associated documents, are the property of PurePro Solutions Ltd. and are shared in strict confidence with the intended recipient. These materials may not be reproduced, shared, or used in any manner without prior written consent from PurePro Solutions Ltd. Unauthorized use or distribution is prohibited.