If an ID is passed or an existing employee is matched (according to the matchType parameter), it will be updated. Otherwise a new employee will be created.

MatchType parameter values:

Standard (default): attempts to match an existing employee - first, based on the external ID, then on Payroll ID, then National Insurance number and finally on first name + surname + date of birth + gender

None: do not attempt to match an existing employee (create a new one)

An employee may be created with a status of 'Incomplete' by specifying at least the minimum fields; firstName, surname, startDate, employeeStatement, NationalInsuranceNumber, NationalInsuranceCategory, NationalInsuranceCalculationMethod, TaxCode and TaxCalculationMethod.
For an employee record to be considered 'Complete' the following groups of data are required:

Basic Details (Name, Start Date, Date of Birth and Address Details)

National Insurance Record

Pay Run Defaults (Default Pay Category, Pay Cycle and Location)

Locations (at least one)

Bank Account/s (at least one)

Pension Details

If reporting dimensions are enabled for the business, add primary reporting dimension values using "|" as a separator between values.

Bypassing address validation:

By default we validate addresses when they are entered. If for any reason you want to skip this validation, please follow the steps below.

1. Set "ResidentialAddressIsOverseas" and "PostalAddressIsOverseas" to "true" (this needs to be a boolean in a string).
2. Set "ResidentialCountry" and "PostalCountry" to the country of the address (e.g. United Kingdom)
3. Now you can enter your address unrestricted in the normal fields.

Please note that when ResidentialAddressIsOverseas is set to "true", ResidentialCountry must be set and likewise with PostalAddressIsOverseas and PostalCountry.

Request

POST https://api.yourpayroll.co.uk/api/v2/business/{businessId}/employee/unstructured

Path parameters

Query parameters

Request body

The request body takes a complete UkUnstructuredEmployeeModel resource, containing the following writable properties:

{
    "anniversaryDate": "date-time",
    "applyRolledUpHolidayPay": "boolean",
    "appointmentEndDate": "date-time",
    "appointmentStartDate": "date-time",
    "assessmentDate": "date-time",
    "assessmentStatus": "string",
    "automaticallyPayEmployee": "string",
    "bankAccount1_AccountName": "string",
    "bankAccount1_AccountNumber": "string",
    "bankAccount1_AllocatedPercentage": "double",
    "bankAccount1_FixedAmount": "double",
    "bankAccount1_RollNumber": "string",
    "bankAccount1_SortCode": "string",
    "bankAccount2_AccountName": "string",
    "bankAccount2_AccountNumber": "string",
    "bankAccount2_AllocatedPercentage": "double",
    "bankAccount2_FixedAmount": "double",
    "bankAccount2_RollNumber": "string",
    "bankAccount2_SortCode": "string",
    "bankAccount3_AccountName": "string",
    "bankAccount3_AccountNumber": "string",
    "bankAccount3_AllocatedPercentage": "double",
    "bankAccount3_FixedAmount": "double",
    "bankAccount3_RollNumber": "string",
    "bankAccount3_SortCode": "string",
    "dateCreated": "date-time",
    "dateOfBirth": "date-time",
    "deferralDate": "date-time",
    "emailAddress": "string",
    "emergencyContact1_Address": "string",
    "emergencyContact1_AlternateContactNumber": "string",
    "emergencyContact1_ContactNumber": "string",
    "emergencyContact1_Name": "string",
    "emergencyContact1_Relationship": "string",
    "emergencyContact2_Address": "string",
    "emergencyContact2_AlternateContactNumber": "string",
    "emergencyContact2_ContactNumber": "string",
    "emergencyContact2_Name": "string",
    "emergencyContact2_Relationship": "string",
    "employeePaidIrregularly": "string",
    "employeeStarterType": "string",
    "employeeStatement": "string",
    "endDate": "date-time",
    "europeanEconomicAreaCitizen": "boolean",
    "excludeEarningsFromAppLevy": "boolean",
    "externalId": "string",
    "firstName": "string",
    "freeportQualifyingEndDate": "date-time",
    "gender": "string",
    "hasPostGradLoan": "boolean",
    "hasStudentLoan": "boolean",
    "homePhone": "string",
    "hoursPerWeek": "double",
    "id": "int32",
    "investmentQualifyingEndDate": "date-time",
    "isApprentice": "string",
    "isCompanyDirector": "string",
    "isEnabledForTimesheets": "string",
    "isExemptFromMinimumWage": "string",
    "isIR35Contractor": "boolean",
    "isSecondedEmployee": "boolean",
    "jobTitle": "string",
    "leaveAccrualStartDateType": "string",
    "leaveTemplate": "string",
    "leaveYearStart": "date-time",
    "locations": "string",
    "middleName": "string",
    "mobilePhone": "string",
    "nationalInsuranceCalculationMethod": "string",
    "nationalInsuranceCategory": "string",
    "nationalInsuranceNumber": "string",
    "occupationalPension": "boolean",
    "optInDate": "date-time",
    "overrideTemplateRate": "string",
    "p6CodingNoticeSequenceNumber": "int64",
    "p9CodingNoticeSequenceNumber": "int64",
    "payConditionRuleSet": "string",
    "payRateTemplate": "string",
    "paySchedule": "string",
    "paySlipNotificationType": "string",
    "payrollId": "string",
    "pensionAssessmentOption": "string",
    "pensionContributionGroup": "string",
    "pgl2CodingNoticeSequenceNumber": "int64",
    "pglCodingNoticeSequenceNumber": "int64",
    "postalAddressIsOverseas": "boolean",
    "postalAddressLine2": "string",
    "postalCity": "string",
    "postalCountry": "string",
    "postalCounty": "string",
    "postalPostCode": "string",
    "postalStreetAddress": "string",
    "postponementOption": "string",
    "preferredName": "string",
    "previousEmployerContinueStudentLoanDeductions": "boolean",
    "previousEmployerLeavingDate": "date-time",
    "previousEmployerOfficeNumber": "string",
    "previousEmployerReferenceNumber": "string",
    "previousEmployerTaxCode": "string",
    "previousEmployerTaxPeriodFrequency": "string",
    "previousEmployerTaxPeriodNumber": "int32",
    "previousEmployerTaxWithheld": "double",
    "previousEmployerTaxablePay": "double",
    "previousEmployerW1M1": "boolean",
    "primaryLocation": "string",
    "primaryPayCategory": "string",
    "rate": "double",
    "rateUnit": "string",
    "reportingDimensionValues": "string",
    "residentialAddressIsOverseas": "boolean",
    "residentialAddressLine2": "string",
    "residentialCity": "string",
    "residentialCountry": "string",
    "residentialCounty": "string",
    "residentialPostCode": "string",
    "residentialStreetAddress": "string",
    "rolledUpHolidayPayPercentage": "double",
    "rosteringNotificationChoices": "string",
    "secondmentType": "string",
    "sl2CodingNoticeSequenceNumber": "int64",
    "slCodingNoticeSequenceNumber": "int64",
    "startDate": "date-time",
    "status": "string",
    "studentLoanType": "string",
    "surname": "string",
    "tags": "string",
    "taxCalculationMethod": "string",
    "taxCode": "string",
    "title": "string",
    "veteransQualifyingEndDate": "date-time",
    "workPhone": "string",
    "workTypes": "string"
}

Properties

Response

The following HTTP status codes may be returned, optionally with a response resource.