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 IRD number, then based on first name + surname + date of birth

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, employmentType, taxCodeDeclaration_IrdNumber, taxCodeDeclaration_EsctRate, kiwiSaver_EnrollmentStatus.
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)

Tax Code Declaration (Tax Code and Employment Type)

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

Locations (at least one)

Bank Account/s (at least one)

Kiwi Saver Contribution Plan

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

Request

POST https://api.nzpayroll.co.nz/api/v2/business/{businessId}/employee/unstructured

Path parameters

Query parameters

Request body

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

{
    "adjustedLeaveEntitlementDate": "date-time",
    "anniversaryDate": "date-time",
    "automaticallyPayEmployee": "string",
    "bankAccount1_AccountCode": "string",
    "bankAccount1_AccountName": "string",
    "bankAccount1_AccountNumber": "string",
    "bankAccount1_AccountParticulars": "string",
    "bankAccount1_AllocatedPercentage": "double",
    "bankAccount1_BankCode": "string",
    "bankAccount1_FixedAmount": "double",
    "bankAccount2_AccountCode": "string",
    "bankAccount2_AccountName": "string",
    "bankAccount2_AccountNumber": "string",
    "bankAccount2_AccountParticulars": "string",
    "bankAccount2_AllocatedPercentage": "double",
    "bankAccount2_BankCode": "string",
    "bankAccount2_FixedAmount": "double",
    "bankAccount3_AccountCode": "string",
    "bankAccount3_AccountName": "string",
    "bankAccount3_AccountNumber": "string",
    "bankAccount3_AccountParticulars": "string",
    "bankAccount3_AllocatedPercentage": "double",
    "bankAccount3_BankCode": "string",
    "bankAccount3_FixedAmount": "double",
    "dateCreated": "date-time",
    "dateOfBirth": "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",
    "employingEntityId": "string",
    "employingEntityNZBN": "string",
    "employmentType": "string",
    "endDate": "date-time",
    "externalId": "string",
    "firstName": "string",
    "gender": "string",
    "homePhone": "string",
    "hoursPerDay": "double",
    "hoursPerWeek": "double",
    "id": "int32",
    "isEnabledForTimesheets": "string",
    "jobTitle": "string",
    "kiwiSaver_EmployeeContribution": "int32",
    "kiwiSaver_EmployerContribution": "double",
    "kiwiSaver_EnrollmentStatus": "string",
    "kiwiSaver_IneligibilityReason": "string",
    "kiwiSaver_LateOptOutReason": "string",
    "kiwiSaver_LateOptOutReasonOtherExplanation": "string",
    "kiwiSaver_OptOutDate": "date-time",
    "kiwiSaver_PreviouslyReported": "boolean",
    "kiwiSaver_SavingsSuspensionFromDate": "date-time",
    "kiwiSaver_SavingsSuspensionToDate": "date-time",
    "leaveAccrualStartDateType": "string",
    "leaveTemplate": "string",
    "leaveWithoutPayAweAdjustmentType": "string",
    "leaveYearStart": "date-time",
    "locations": "string",
    "middleName": "string",
    "mobilePhone": "string",
    "overrideTemplateRate": "string",
    "payConditionRuleSet": "string",
    "payRateTemplate": "string",
    "paySchedule": "string",
    "paySlipNotificationType": "string",
    "postalAddressIsOverseas": "boolean",
    "postalAddressLine2": "string",
    "postalCountry": "string",
    "postalPostCode": "string",
    "postalState": "string",
    "postalStreetAddress": "string",
    "postalSuburb": "string",
    "preferredName": "string",
    "previousSurname": "string",
    "primaryLocation": "string",
    "primaryPayCategory": "string",
    "rate": "double",
    "rateUnit": "string",
    "reportingDimensionValues": "string",
    "residentialAddressIsOverseas": "boolean",
    "residentialAddressLine2": "string",
    "residentialCountry": "string",
    "residentialPostCode": "string",
    "residentialState": "string",
    "residentialStreetAddress": "string",
    "residentialSuburb": "string",
    "rosteringNotificationChoices": "string",
    "startDate": "date-time",
    "status": "string",
    "surname": "string",
    "tags": "string",
    "taxCodeDeclaration_DateSigned": "date-time",
    "taxCodeDeclaration_ElectedExtraPayRate": "double",
    "taxCodeDeclaration_EsctRate": "double",
    "taxCodeDeclaration_FtcOverseasSuperOrPension": "boolean",
    "taxCodeDeclaration_IncomeAppliedToTestedBenefit": "boolean",
    "taxCodeDeclaration_IncomeBand": "int32",
    "taxCodeDeclaration_IrdNumber": "string",
    "taxCodeDeclaration_IrregularEmployment": "boolean",
    "taxCodeDeclaration_IsNonDisclosed": "boolean",
    "taxCodeDeclaration_IsPrimaryIncome": "boolean",
    "taxCodeDeclaration_MeetsMainIncomeMeansTest": "boolean",
    "taxCodeDeclaration_NewZealandResident": "boolean",
    "taxCodeDeclaration_RegisteredForGST": "boolean",
    "taxCodeDeclaration_SpecialTaxCode": "string",
    "taxCodeDeclaration_SpecialTaxCodeRate": "double",
    "taxCodeDeclaration_SpecialTaxCodeRateEndDate": "date-time",
    "taxCodeDeclaration_StudentLoan": "boolean",
    "taxCodeDeclaration_StudentLoanRate": "double",
    "taxCodeDeclaration_StudentLoanRateEndDate": "date-time",
    "taxCodeDeclaration_TaxCode": "string",
    "terminationReason": "string",
    "title": "string",
    "workPhone": "string",
    "workTypes": "string"
}

Properties

Response

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