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

    Parameter name Value Description Additional
    businessId string Required

    Query parameters

    Parameter name Value Description Additional
    matchType string

    Possible values are:

    • None
    • Standard

    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

    Name Type Description
    anniversaryDate date-time Nullable
    applyRolledUpHolidayPay boolean Nullable
    appointmentEndDate date-time Nullable
    appointmentStartDate date-time Nullable
    assessmentDate date-time Nullable
    assessmentStatus string String
    automaticallyPayEmployee string String
    bankAccount1_AccountName string String
    bankAccount1_AccountNumber string String
    bankAccount1_AllocatedPercentage double Nullable
    bankAccount1_FixedAmount double Nullable
    bankAccount1_RollNumber string String
    bankAccount1_SortCode string String
    bankAccount2_AccountName string String
    bankAccount2_AccountNumber string String
    bankAccount2_AllocatedPercentage double Nullable
    bankAccount2_FixedAmount double Nullable
    bankAccount2_RollNumber string String
    bankAccount2_SortCode string String
    bankAccount3_AccountName string String
    bankAccount3_AccountNumber string String
    bankAccount3_AllocatedPercentage double Nullable
    bankAccount3_FixedAmount double Nullable
    bankAccount3_RollNumber string String
    bankAccount3_SortCode string String
    dateCreated date-time DateTime
    dateOfBirth date-time Nullable
    deferralDate date-time Nullable
    emailAddress string String
    emergencyContact1_Address string String
    emergencyContact1_AlternateContactNumber string String
    emergencyContact1_ContactNumber string String
    emergencyContact1_Name string String
    emergencyContact1_Relationship string String
    emergencyContact2_Address string String
    emergencyContact2_AlternateContactNumber string String
    emergencyContact2_ContactNumber string String
    emergencyContact2_Name string String
    emergencyContact2_Relationship string String
    employeePaidIrregularly string String
    employeeStarterType string String
    employeeStatement string String
    endDate date-time Nullable
    europeanEconomicAreaCitizen boolean Nullable
    excludeEarningsFromAppLevy boolean Nullable
    externalId string String
    firstName string String
    freeportQualifyingEndDate date-time Nullable
    gender string String
    hasPostGradLoan boolean Boolean
    hasStudentLoan boolean Boolean
    homePhone string String
    hoursPerWeek double Nullable
    id int32 Int32
    investmentQualifyingEndDate date-time Nullable
    isApprentice string String
    isCompanyDirector string String
    isEnabledForTimesheets string String
    isExemptFromMinimumWage string String
    isIR35Contractor boolean Boolean
    isSecondedEmployee boolean Nullable
    jobTitle string String
    leaveAccrualStartDateType string Nullable

    Possible values are:

    • EmployeeStartDate
    • SpecifiedDate
    • CalendarYear
    • CategorySpecificDate
    leaveTemplate string String
    leaveYearStart date-time Nullable
    locations string String
    middleName string String
    mobilePhone string String
    nationalInsuranceCalculationMethod string String
    nationalInsuranceCategory string String
    nationalInsuranceNumber string String
    occupationalPension boolean Nullable
    optInDate date-time Nullable
    overrideTemplateRate string String
    p6CodingNoticeSequenceNumber int64 Int64
    p9CodingNoticeSequenceNumber int64 Int64
    payConditionRuleSet string String
    payRateTemplate string String
    paySchedule string String
    paySlipNotificationType string String
    payrollId string String
    pensionAssessmentOption string String
    pensionContributionGroup string String
    pgl2CodingNoticeSequenceNumber int64 Int64
    pglCodingNoticeSequenceNumber int64 Int64
    postalAddressIsOverseas boolean Nullable
    postalAddressLine2 string String
    postalCity string String
    postalCountry string String
    postalCounty string String
    postalPostCode string String
    postalStreetAddress string String
    postponementOption string Nullable

    Possible values are:

    • DoNotPostpone
    • PostponeUsingPensionSchemePostponementRules
    • PostponeToFollowingDate
    preferredName string String
    previousEmployerContinueStudentLoanDeductions boolean Nullable
    previousEmployerLeavingDate date-time Nullable
    previousEmployerOfficeNumber string String
    previousEmployerReferenceNumber string String
    previousEmployerTaxCode string String
    previousEmployerTaxPeriodFrequency string String
    previousEmployerTaxPeriodNumber int32 Nullable
    previousEmployerTaxWithheld double Nullable
    previousEmployerTaxablePay double Nullable
    previousEmployerW1M1 boolean Nullable
    primaryLocation string String
    primaryPayCategory string String
    rate double Nullable
    rateUnit string String
    reportingDimensionValues string String
    residentialAddressIsOverseas boolean Nullable
    residentialAddressLine2 string String
    residentialCity string String
    residentialCountry string String
    residentialCounty string String
    residentialPostCode string String
    residentialStreetAddress string String
    rolledUpHolidayPayPercentage double Nullable
    rosteringNotificationChoices string String
    secondmentType string Nullable

    Possible values are:

    • InOutUK
    • Stay183DaysOrMore
    • StayLessThan183Days
    sl2CodingNoticeSequenceNumber int64 Int64
    slCodingNoticeSequenceNumber int64 Int64
    startDate date-time Nullable
    status string EmployeeStatusEnum

    Possible values are:

    • Active
    • Terminated
    • Incomplete
    studentLoanType string String
    surname string String
    tags string String
    taxCalculationMethod string String
    taxCode string String
    title string String
    veteransQualifyingEndDate date-time Nullable
    workPhone string String
    workTypes string String

    Response

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

    Status code Description Resource
    200 OK

    OK

    EmployeeUpdateResponseModel