Hire, configure, pay, end, rehire.

00Who this is for

You are building software that manages people on someone else's payroll. Your customer runs Lightning Payroll, you hold an OAuth client, and you want your system to be the place an employee is hired, changed and ended, with Lightning Payroll kept in step automatically.

Everything here happens on the /api surface with a bearer token. There is one mental model to hold: an employee belongs to a company, a company belongs to your customer, and your token is scoped to that customer's data. You create the employee, you configure the pieces that make them payable, you keep them current, and one day you terminate them. Lightning Payroll turns that into compliant payroll: a final pay, the right leave payout, the right tax, and the right thing reported to the tax office.

What this guide covers

• Creating employees, including exactly which fields are mandatory in Australia and in New Zealand, and why that differs.
• The sub-resources that turn a record into a payable employee: bank accounts, superannuation or KiwiSaver, allowances.
• Reading and updating employees, and the identifiers you can key on.
• Termination, in both countries, including manual payout amounts and the figures that come back.
• Reinstatement, soft deletion and restoration, and which of them you actually want.
• The webhooks that tell you an employee changed, and how to reconcile if you miss one.

What it does not cover

Authentication is a guide of its own: see the OAuth Authentication Guide for the authorization code flow, token lifetimes and the scope catalogue, and the API Admin Setup and Management Guide for getting an API admin account and an OAuth client in the first place. Buying subscriptions on a customer's behalf is Partner Checkout. Registering webhook endpoints and rotating their secrets is the Webhooks Guide; this guide only covers the employee events themselves. Pushing hours in for a pay run is the timesheet integration guide.

01The lifecycle model

Four operations, two independent axes. Almost every integration bug in this area comes from treating them as one axis.

Employment state answers "does this person still work here". It moves with /terminate and /reinstate. A terminated employee is a former employee: they have a termination date, a final pay, and a cessation reported to the tax office. They stay fully visible, because payroll history does not disappear when someone leaves.

Record visibility answers "should this record show up in the payroll app". It moves with DELETE and /restore. A deleted employee is hidden from the day-to-day screens, and their pays, payslips and payroll number are all still there. Nothing is destroyed and nothing is reported.

The two axes compose, so a record can be terminated and deleted at once. Order does not matter, and undoing one does not undo the other. If you want a terminated employee gone from the customer's screens, terminate first so the final pay is right, then delete.

02Before you start

Five things worth knowing before your first write: how your token is scoped, how you address a company, what the rate limits are, what an error looks like, and why retries need your attention here.

Scopes

Every call on this surface needs a bearer token, and the token's scope decides what you can do. There is no separate employee or termination scope: payroll write covers all of it, terminations included.

A token carrying only checkout scopes cannot touch employees at all, and a token carrying payroll.write can terminate anyone on any company it can see. Scope your OAuth client to what your product actually does.

Scope is not the only gate. The four lifecycle operations (terminate, reinstate, delete and restore) also require the customer to hold an active subscription, and return 403 with "This customer has no active subscriptions and cannot update data." when it has lapsed. Creating an employee fails for a lapsed customer too, though by a different route: their employee allowance drops to zero, so the create is refused as a limit. Reads keep working throughout. If your integration suddenly starts getting 403s on a customer who worked yesterday, check their subscription before you check your token.

Addressing a company

Company-scoped endpoints take the company in the path, as /api/company/{company_id}/.... Employee-scoped endpoints take only the employee, as /api/employees/{employee_id}/..., and resolve the company themselves. There is no company header and no tenant query parameter.

A company_id your token cannot see is reported as not found rather than as forbidden, so probing ids tells an attacker nothing. Two shapes exist, depending on the endpoint. Create and update answer:

HTTP/1.1 404 Not Found
{
  "detail": "Company not found"
}

while the read and list endpoints answer:

HTTP/1.1 400 Bad Request
{
  "detail": "No company found with the given company_id"
}

Treat both as the same thing: the id does not exist in the data your token reaches. In particular do not read the 400 as a complaint about your request format.

Rate limits

The batch create and update endpoints take an array, so a migration of two hundred employees is a handful of requests rather than two hundred. Prefer batching over parallel single calls: it is faster, it is kinder to the limit, and you get one result row per employee either way.

Error shapes

Three shapes come back, and which one you get depends on where the request failed. Handle all three.

Schema validation, before your request reaches any business logic. A bad enum value, a malformed date, a negative amount, an unknown field name:

HTTP/1.1 422 Unprocessable Entity
{
  "status_code": 10422,
  "message": "[{'loc': ('body', 0, 'email_address'), 'msg': 'Invalid email format.', 'type': 'value_error'}]",
  "data": null
}

Business rules, the large majority of errors you will actually hit. The message is in detail, and it is written to be read:

HTTP/1.1 409 Conflict
{
  "detail": "Employee is already terminated. Use the reinstate endpoint to re-hire them."
}

Something broke on our side, which you should treat as retryable:

HTTP/1.1 500 Internal Server Error
{
  "error": "An unexpected error occurred. Please try again."
}

Read detail first, fall back to message, then error. A client that only reads one field will silently show your users nothing on two thirds of failures.

Retries and safety

Two habits make this a non-issue:

• Always send your own number on create. It is your employee code, and it must be unique across every company on the account. If a create times out, read the employee back by that number before retrying. Found means it worked; not found means it did not.
• Before retrying a termination, read it back. GET /api/employees/{id}/termination returns 404 if the employee has never been terminated, and the termination record if they have. That is a cheap, side-effect-free way to find out whether your first call landed.

Dates, money and lists

• Dates are YYYY-MM-DD. There are no timestamps in this part of the API, because payroll works in whole days.
• Money and hours are decimals. Send them as JSON strings ("6182.40") rather than floats, so nothing is lost turning your number into binary and back.
• List endpoints return a bare JSON array, not an object with a data key.

03Creating an employee

One endpoint, an array in and an array out, with per-employee results so a bad row cannot take a good one down with it.

Send an array even for one employee. You get back an array in the same order, one entry per employee you sent, each carrying either the created employee or the reason it failed. The status code tells you which case you are in:

That difference matters when you design a migration. Schema errors are all-or-nothing, so validate locally before you send. Business-rule errors, such as a duplicate payroll number, are per-employee, so a two hundred row import can come back 207 with one hundred and ninety eight created and two to fix.

A realistic payload

The minimum payload is in the field reference. This is what a real one tends to look like: identity and address, the tax declaration, how they are paid, their super fund, and the portal permissions their employer wants them to have.

[
  {
    "first_name": "Marguerite",
    "middle_name": "Rose",
    "last_name": "Abernethy",
    "honorific": "Ms",
    "gender": "FEMALE",
    "date_of_birth": "1986-03-11",
    "address1": "18 Kembla Street",
    "city": "Coorparoo",
    "state": "QLD",
    "country": "AU",
    "postcode": "4151",
    "email_address": "m.abernethy@example.com",
    "phone_mobile": "0412 355 118",

    // Employment. start_date and employment_status are both required.
    "start_date": "2019-02-04",
    "employment_status": "Full-time",
    "position": "Operations Manager",
    "department": "Operations",
    "number": "EMP-1004",

    // How they are paid.
    "pay_period": "FORTNIGHTLY",
    "pay_method": "DIRECT BANK ENTRY",
    "pay_rate_per_hour": "58.40",
    "standard_hours_per_day": "7.6",
    "standard_days_per_week": 5,

    // Australian tax declaration. All four booleans are required.
    "tax_file_number": "458201134",
    "is_foreign_resident": false,
    "is_closely_held": false,
    "has_claimed_tax_free_threshold": true,
    "has_stsl_liability": false,

    // Default super fund, by USI and member number.
    "default_employee_fund_usi": "STA0100AU",
    "default_employee_fund_member_number": "AS-4471902",

    // Employee portal access.
    "employee_portal_active": true,
    "allow_view_payslips": true,
    "allow_edit_timesheet": true,
    "allow_edit_leave_requests": true
  }
]

The response echoes the created employee, including the id you will use for everything that follows:

HTTP/1.1 201 Created
[
  {
    "employee": {
      "id": 8842,
      "company_id": 412,
      "number": "EMP-1004",
      "first_name": "Marguerite",
      "last_name": "Abernethy",
      "is_terminated": false,
      "is_deleted": false,
      // ... the full employee read model
    },
    "errors": {}
  }
]

The road to a payable employee

Creating the record is step one of a few. None of the rest are mandatory to hold a record, but a payroll clerk cannot pay someone without them.

lightningpayroll.com.au/admin/employees

04Field reference

One field set covers create and update. This is the whole of it, grouped the way a payroll officer thinks about it rather than the way it is stored.

Both PUT/api/company/{company_id}/employees/create and PATCH/api/company/{company_id}/employees/update validate against the same field set, so everything below applies to both. Creating an employee makes ten of these fields mandatory: first_name, last_name, date_of_birth, address1, city, state, country, postcode, start_date and employment_status. Every other field is optional on create. Update is pure PATCH semantics keyed on the employee's internal id (the only field it requires): send only the fields you want to change, and anything you omit is left exactly as it was. There is no way to blank a field by leaving it out. Both endpoints reject a key they do not recognise outright, an unknown or misspelled field name comes back as a 422 rather than being quietly dropped, because the payload model is built with extra="forbid". A dropped field fails silently; a rejected one fails loudly, and loud is what you want when the field controls tax or bank details.

One more thing worth knowing before you rely on any field below: a field you genuinely omit from a create payload does not necessarily arrive blank. Lightning Payroll applies its own configured default for that setting instead, the same one a new employee gets when added from the desktop app. The notes below call out the specific defaults that matter.

Identity and personal details

Address

Contact and next of kin

The employee's own contact details, plus an optional emergency contact.

Employment

Australian tax declaration

The first five rows below are, in practice, required for an ordinary Australian employee, but the requirement is enforced by a service-side check rather than by the payload schema. Leave one out and you get a 400 for that item once the rest of the payload has already passed validation, not a 422 for the whole request. If you do supply a value that is present but malformed (a tax file number that fails the ATO checksum, for instance), that still fails immediately as a 422.

New Zealand tax declaration

Pay and rates

Superannuation (AU)

KiwiSaver and ESCT (NZ)

Leave accrual settings

Bank details

These are the legacy inline fields on the employee record itself, a primary account that always exists and one optional secondary split. They are entirely separate from the newer, ranked multi-account sub-resource at GET/api/employees/{employee_id}/bank-accounts, which supports up to 10 accounts and is documented in its own section. Both mechanisms are live at the same time on this API, and nothing here cross-validates a caller who mixes the two.

Employee portal access and permissions

Whether an employee can use the online portal at all, and what they can see and edit once they are in, is controlled entirely by boolean flags: employee_portal_active, allow_edit_timesheet, allow_edit_timeclock, allow_edit_account_details, allow_edit_tax_settings, allow_edit_bank_accounts, allow_edit_super_details, allow_edit_leave_requests, allow_edit_leave_requests_when_negative, allow_view_holiday_leave_balance, allow_view_sick_leave_balance, allow_view_long_service_leave_balance and allow_view_payslips. All 13 are optional booleans, off unless you set them true.

Payslip display options

What appears on the employee's payslip is likewise mostly boolean flags: show_roster_summary_on_payslip, show_position_on_payslip, show_department_on_payslip, payslip_show_holiday_leave_balance, payslip_show_sick_leave_balance, payslip_show_lsl_balance, payslip_show_negative_leave_balances, payslip_show_custom_balances, payslip_show_hours_and_rate, payslip_show_allowance_units, payslip_show_base_ordinary_rate, payslip_show_super_ytd, payslip_show_ytd, payslip_show_zero_dollar_leave and payslip_time_non_decimal. All 15 are optional booleans, but they are not all off by default, and this is the group most likely to surprise you. Omit them on create and eight arrive switched on: show_position_on_payslip, payslip_show_holiday_leave_balance, payslip_show_negative_leave_balances, payslip_show_custom_balances, payslip_show_hours_and_rate, payslip_show_allowance_units, payslip_show_ytd and payslip_show_zero_dollar_leave. The rest default off. If your product promises a particular payslip layout, send every flag you care about explicitly rather than relying on an omitted field being false. Two remaining fields in this group are not booleans and are worth their own row:

Fields you cannot write

The Employee object you get back from a read carries a number of fields that are not part of the create or update payload at all. Sending any of them back, a common trap when you round-trip a fetched record straight into an update, is rejected with a 422 rather than silently ignored, under the same extra="forbid" rule covered above. If you build updates by fetching an employee, editing a few fields and PATCHing the whole object back, strip these first.

The leave-balance fields deserve special attention, since they are the ones integrators most often expect to be able to set directly and cannot. holiday_leave_hours, sick_leave_hours and lsl_leave_hours only ever change as a side effect of processing a pay: run a pay that accrues leave, or pays leave out, and the balance moves accordingly. There is no endpoint on this API for setting an opening balance directly. If you are migrating an employee from another system and need to seed their starting balance, the way to do it is to process a pay that lands them at the figure you want. The one exception is delete_non_rdo_and_toil_leave_items on update, which wipes every non-RDO, non-TOIL leave balance in a single call rather than setting any of them to a chosen value, useful for clearing a balance that was misconfigured rather than for seeding a real one.

Minimum viable payloads

The smallest payload that creates an Australian employee, sent as a single-item array to PUT/api/company/{company_id}/employees/create:

[
  {
    "first_name": "Alice",
    "last_name": "Smith",
    "date_of_birth": "1990-01-01",
    "address1": "123 Example Street",
    "city": "Sydney",
    "state": "NSW",
    "country": "AU",
    "postcode": "2000",
    "start_date": "2024-07-01",
    "employment_status": "Full-time",
    "tax_file_number": "111111111",
    "is_foreign_resident": false,
    "is_closely_held": false,
    "has_claimed_tax_free_threshold": true,
    "has_stsl_liability": false
  }
]

"111111111" is one of the ATO's recognised placeholder TFNs (new payee, no declaration yet), so it passes the checksum without belonging to a real person, handy for test data. For a super-only contractor, drop tax_file_number and add "is_super_only_contractor": true; the other four Australian booleans are still required.

The smallest payload for a New Zealand employee, on the same endpoint:

[
  {
    "first_name": "Alice",
    "last_name": "Smith",
    "date_of_birth": "1990-01-01",
    "address1": "123 Example Street",
    "city": "Auckland",
    "state": "AUK",
    "country": "NZ",
    "postcode": "1010",
    "start_date": "2024-07-01",
    "employment_status": "Full-time",
    "nz_tax_code": "M",
    "ird_number": "49091850"
  }
]

Drop ird_number entirely when nz_tax_code is "WT" or "ND", or when you send "no_declaration": true (which sets nz_tax_code to "ND" for you), for an 11-field minimum with no IRD number at all.

Where these fields end up

Every field above surfaces somewhere your customer can see it. It is worth knowing which screen, because that is where support questions come from: a clerk describes a screen, and you need to know which field they mean. Identity and address land on the Personal Details screen shown in section 03; the rest are below.

lightningpayroll.com.au/admin/employees/tax/tax_settings

lightningpayroll.com.au/admin/employees/pay_settings/pay_rates

lightningpayroll.com.au/admin/employees/leave/leave_settings

lightningpayroll.com.au/admin/employees/details/online_portal

05Bank accounts

An employee can hold up to ten accounts, ranked, with fixed amounts split off the top. There are two ways to write them, and you want the newer one.

Account identity differs by country

Which identity fields are required depends on the company's jurisdiction, not on the employee's country field. This is the one place in the employee lifecycle where the company decides.

Fields

Adding a split

A typical two-account setup: the whole net pay goes to an everyday account, except a fixed 450 dollars into savings.

// The everyday account. rank 0 makes it the default, so it takes the
// remainder and must not carry an amount.
{
  "account_name": "M R Abernethy",
  "bsb": "084-234",
  "account_number": "119043872",
  "rank": 0
}

// Then the split: secondary position 1, a fixed amount, its own reference.
{
  "account_name": "M R Abernethy Savings",
  "bsb": "064-158",
  "account_number": "220771904",
  "rank": 1,
  "amount": "450.00",
  "alt_transaction_reference": "Savings"
}

Rules worth coding for

• The first account is always the default, whatever rank you send, because an employee must always have exactly one account taking the remainder. Send "rank": 1 on an employee's very first account and it comes back as the default with a null rank. For the same reason, a rank of 1 or more is rejected on whichever account is currently the default: promote a different account instead, which demotes the old one for you.
• Ten accounts maximum. An eleventh is 409.
• No duplicate account numbers on the same employee, also 409.
• Deleting the default promotes the next account by rank, so an employee with more than one account is never left without a default. Deleting an employee's only account is allowed, and leaves them with none, matching what the payroll app permits. If your interface offers a delete button, that is the case to guard.
• The employee may own their own bank details. If your customer has given this employee permission to edit bank accounts in the employee portal, deleting one through the API returns 409. The employee is the source of truth while that permission is on. Check allow_edit_bank_accounts on the employee before you offer bank editing in your own interface.
• A partial update re-validates the whole identity. Sending just a new account_number re-checks it against the BSB, so a valid pair cannot become an invalid one.

lightningpayroll.com.au/admin/employees/details/bank_accounts

06Super and KiwiSaver

Retirement contributions are the one part of employee setup where the two countries barely resemble each other, and where the API deliberately does less than you might expect.

Deleting a fund is not always a hard delete. A fund that is the employee's default, or that already has contribution history behind it, is retired rather than removed, so past payments still reconcile. A fund with no history is removed outright. Either way the response is 200 and the fund stops being used.

lightningpayroll.com.au/admin/employees/super/superannuation_fund

07Allowances

Two kinds: one employee's own allowance, and a company-wide allowance attached to whoever should get it. Both are here.

A GET returns both buckets, so you can tell what belongs to the employee and what they inherited:

{
  "employee": [ /* this employee's own allowances */ ],
  "company": [ /* company allowances attached to them */ ]
}

Creating an employee allowance needs a description and an amount. For an Australian company it also needs a classified allowance_category, because the category is what gets reported:

{
  "description": "Tool allowance",
  "amount": "26.50",
  "allowance_category": "TD"
}

• Attaching a company allowance is idempotent. PUT the same allowance twice and the second call changes nothing, so you can converge on a desired state without tracking what you already did.
• Renaming an allowance can reach backwards. A PATCH takes an optional propagate_description_to_history flag which rewrites the description on past pays too. Leave it off unless you want payslips already issued to read differently.
• A company allowance in use will not delete. It returns 409 while any employee is attached, unless you pass force=true.
• Editing a company allowance replaces its whole attached set. If you send employee_ids, send every employee who should have it, not just the ones you are adding.

08Reading employees

Three ways in: the whole company, one employee by our id, one employee by your code.

Listing a company

The list endpoint takes one query parameter, status, and returns a bare array sorted by last name, then first name, then middle name.

Fetching one employee

By our id when you have stored it, which is the normal case after a create:

GET /api/employees/8842

Or by the number you assigned, which is useful when your own system is the system of record and you never stored our id:

GET /api/employees/payroll-number/EMP-1004

Both return the same shape. Because number is unique across the whole account, the second form does not need a company.

Deciding what changed

The read model has no version field and no updated timestamp, so there is nothing to compare against except the values themselves. If you need change detection, keep a hash of the fields you care about and compare on read. In practice most integrations only care about a dozen fields, and hashing those is cheaper and far less noisy than diffing the whole record.

09Updating an employee

A batch PATCH keyed on whichever identifier you have. Send only what changes.

This takes an array and returns one result per entry. Each entry needs an identifier and then only the fields you are changing. Anything you leave out is left alone, so there is no read-modify-write cycle and no risk of clobbering a field a payroll clerk changed while you were not looking.

[
  {
    "id": 8844,
    "position": "Senior Payroll Officer",
    "pay_rate_per_hour": "45.10"
  }
]

By default each entry is matched on id, our internal identifier. If you would rather key on your own code, add identifier_type=employee_number to the query string and put the code in number:

PATCH /api/company/412/employees/update?identifier_type=employee_number

[
  {
    "id": 8844,          // still required by the schema, ignored for matching
    "number": "EMP-1006",
    "position": "Senior Payroll Officer"
  }
]

What you cannot change this way

• Leave balances. Accrual settings are writable, balances are not. A balance is the arithmetic of processed pays and adjustments, and letting an integration set it directly would put an employee's entitlement out of step with the pays that produced it. The one exception is that RDO and time-off-in-lieu hours are writable, because they are tracked rather than accrued from a formula.
• Anything derived. Year-to-date figures, tax treatment codes, the readable form of a status. They are on the read model and rejected on write.
• Pay period, while a termination is pending. If a staged termination pay exists for this employee, pay_period is stripped from your payload and reported back as a per-field error, while every other field in the same entry still applies. The response is 207, not a top-level failure, so read errors.pay_period on the entry rather than assuming the whole update was refused. Finish or discard the termination first, otherwise the final pay would be calculated on one frequency and paid on another.

10Termination

The biggest call in this guide. One request ends the employment, builds the final pay, values the unused leave, taxes it under the right regime and reports the cessation.

Terminating is not a flag you set. The call creates a pay, attaches the termination to it, calculates every payout component, taxes the result and processes the pay, all in the one request. When it returns 200 the employee is terminated and the final pay exists. When it fails, no pay is left behind and the employee is untouched, so a rejected termination is safe to correct and retry.

Two dates, doing different jobs. termination_date is the last day of employment, and it is what leave is valued at. pay_date is the day the final pay is paid, and it decides which pay run the termination lands in and which tax year it is reported against. They are usually days apart, and getting them the wrong way round is the most common cause of a final pay that looks almost right.

Terminating inside a pay run

If you already create pays through the API, you do not need a separate termination call. PUT/api/company/{company_id}/pays/create accepts an optional termination block on each pay, taking the same fields and following the same rules. Use it when the final pay also carries ordinary hours for the last part-week worked, so the wages and the payout are priced together on one pay.

One consequence worth knowing: a percentage-based deduction on that pay is calculated against the whole final pay, payout included, not just the wages. That is correct, and it is usually a larger number than integrators expect.

Termination reference

Shared request fields

These fields apply to both countries, though a few are priced or gated differently depending on which one the employee belongs to.

Australian request fields

Each entry in tax_summaries is its own object:

New Zealand request fields

non_etp_amount (in the shared table above) needs a New Zealand-specific warning: outside manual mode, Lightning Payroll uses this exact field to hold the statutory 8% holiday pay owing since the employee's last anniversary. Send an amount of your own into it without is_manual_leave_amounts set and the request is rejected with 400 rather than letting your figure be silently overwritten by the statutory one.

Manual amounts

is_manual_leave_amounts is the API equivalent of "Show Advanced Settings" in the Australian termination wizard and "Enter leave amounts manually" on the New Zealand employment finish screen. Leave it false (the default) and Lightning Payroll works out every unused-leave payout from the employee's balances, which is almost always what you want. Set it true and it unlocks exactly these fields:

• unused_holiday_amount
• unused_leave_loading_amount (Australia)
• unused_alt_holiday_amount (New Zealand)
• unused_sick_amount (Australia)
• unused_lsl_pre_august_1978, unused_lsl_august_1978_to_august_1993, unused_lsl_post_august_1993 (Australia)
• normal_earnings (Australia)
• tax_summaries (Australia)

Send any of them while is_manual_leave_amounts is false or omitted and the whole request is rejected with 422, because Lightning Payroll would otherwise recalculate every one of these from the employee's leave balances and overwrite whatever value you sent before it ever reached the payslip.

Enumerations

reason (termination reason):

EARLY_RETIREMENT is not accepted on the wire. Send an early retirement scheme payment as REDUNDANCY, which carries the same tax treatment; sending EARLY_RETIREMENT is rejected with a 422.

cessation_type_code (STP cessation type):

I (ill health), D (deceased) and R (redundancy) exist in the underlying column but are not accepted on the wire: they are derived automatically from reason (INVALIDITY sets I, any DEATH_* sets D, REDUNDANCY sets R) and cannot be chosen directly.

payment_in_lieu_type:

END_OF_NOTICE_DATE is not accepted on the wire. Send the notice you are actually paying, either as hours or as a lump sum.

etp_code (on each tax_summaries row):

What comes back

The response is pruned to match the employee's country before it is sent: an Australian company never sees a New Zealand field, and a New Zealand company never sees an Australian one, whether the termination is read back on its own or nested inside a pay.

Australia gets back its lump sums and ETP components: total_amount, total_etp_amount, total_non_etp_amount, unused_lsl_amount (the three long-service-leave eras summed), unused_lsl_tax_amount, unused_holiday_and_loading_tax_amount, lump_sum_a, lump_sum_b, lump_sum_d, etp_tax_withheld, etp_taxable_component, etp_tax_free_component, and the tax_summaries array itself, whether you supplied it or Lightning Payroll calculated it.

New Zealand gets back tax_amount and unused_holiday_and_loading_tax_amount as before, plus nz_extra_pay_tax_breakdown: a structured object with one entry per termination component, unused_holiday, alt_holiday, redundancy and other, each carrying its own amount, tax, a components map of the calculator's named tax and levy lines, and applied_personal_rate. The breakdown also carries total_tax and taxed_at_low_rate, the flag that sets the lump sum indicator on the Employment Information (payday) return.

Reading a termination back through the employee (GET/api/employees/{employee_id}/termination, or the response of POST/api/employees/{employee_id}/terminate itself) adds six fields on top of the plain termination: pay_id, pay_date, is_pay_processed, employee_id, employee_number and is_employee_terminated. The last two matter together: a New Zealand termination can come back with is_pay_processed: false and is_employee_terminated: false while its pay is still staged, because New Zealand only flags the employee terminated once that pay is processed.

How the two countries are calculated

Errors

A worked Australian example

A genuine redundancy, with notice paid as a lump sum and the leave payout amounts entered by hand. Every figure in the response below came back from this exact request.

{
  // Last day worked, and the pay run this is paid in.
  "termination_date": "2026-08-14",
  "pay_date": "2026-08-19",

  "reason": "REDUNDANCY",

  // Five weeks of notice, paid as a lump sum rather than as hours.
  "is_payment_in_lieu_paid": true,
  "payment_in_lieu_type": "NOTICE_LUMP_SUM",
  "notice_lump_sum": "7280.00",

  // The redundancy payment itself.
  "redundancy_amount": "24500.00",

  // Leave payout amounts supplied rather than calculated.
  "is_manual_leave_amounts": true,
  "is_unused_holiday_paid": true,
  "is_unused_leave_loading_paid": true,
  "unused_holiday_amount": "6182.40",
  "unused_leave_loading_amount": "1081.92",
  "unused_lsl_post_august_1993": "3894.00"
}

The response, abbreviated to the calculated fields. Note what the API worked out that the request never mentioned: the cessation type, the payment in lieu amount, the total, and the whole tax treatment.

// 200 OK
{
  "termination_date": "2026-08-14",
  "reason": "REDUNDANCY",
  "cessation_type_code": "R",          // derived from the reason
  "payment_in_lieu_amount": 7280,        // derived from notice_lump_sum
  "normal_earnings": 3891.2,             // derived, feeds the ETP cap

  "unused_holiday_amount": 6182.4,
  "unused_leave_loading_amount": 1081.92,
  "unused_lsl_amount": 3894,
  "redundancy_amount": 24500,

  "total_amount": 42938.32,
  "total_non_etp_amount": 11158.32,
  "total_etp_amount": 31780,

  // Tax, split by the component it belongs to.
  "tax_amount": 5900,
  "unused_holiday_and_loading_tax_amount": 2324,
  "unused_lsl_tax_amount": 1246,

  // Reported lump sums.
  "lump_sum_a": 11158.32,
  "lump_sum_b": 0,
  "lump_sum_d": 24500,

  "etp_taxable_component": 7280,
  "etp_tax_free_component": 0,
  "etp_tax_withheld": 2330,
  "tax_summaries": [
    { "etp_code": "R", "tax_withheld": 0, "taxable_component": 0, "tax_free_component": 0, "lump_sum_d": 24500 },
    { "etp_code": "O", "tax_withheld": 2330, "taxable_component": 7280, "tax_free_component": 0, "lump_sum_d": 0 }
  ],

  "pay_id": 2,
  "pay_date": "2026-08-20",
  "is_pay_processed": true,
  "employee_id": 9,
  "employee_number": "EMP-1013",
  "is_employee_terminated": true
}

It is worth following the money, because the split is the part integrators most often get wrong:

• The three unused leave amounts (6182.40 + 1081.92 + 3894.00) add up to 11,158.32, which is the non-ETP total and is reported as Lump Sum A, because unused leave paid on a redundancy is taxed at a flat rate rather than as ordinary income.
• The redundancy payment of 24,500 falls inside the tax-free limit for this employee's service, so it lands in Lump Sum D as an ETP with an R code and no tax withheld.
• The notice lump sum of 7,280 is not part of the redundancy. It is an ETP with an O code, taxable in full, and 2,330 was withheld from it.
• The ETP total of 31,780 is the redundancy plus the notice. Add the non-ETP 11,158.32 and you get the total_amount of 42,938.32.

A New Zealand example

An ordinary finish with notice paid in lieu and a redundancy component, leaving the leave amounts for Lightning Payroll to value from the employee's record. Notice how much shorter it is: there is no reason, no cessation type, and no leave payout flags, because New Zealand does not use them.

{
  "termination_date": "2026-09-11",
  "pay_date": "2026-09-17",
  "is_payment_in_lieu_paid": true,
  "payment_in_lieu_amount": "1200.00",
  "redundancy_amount": "4000.00"
}

The response carries nz_extra_pay_tax_breakdown in place of every Australian lump sum and ETP field, with the tax attributed to each component of the payout:

// 200 OK, abbreviated
{
  "termination_date": "2026-09-11",
  "payment_in_lieu_amount": 1200,
  "redundancy_amount": 4000,
  "unused_holiday_amount": 2884.6,
  "unused_alt_holiday_amount": 412.08,
  "non_etp_amount": 631.55,        // the statutory 8% owing since the last anniversary
  "total_amount": 9128.23,
  "tax_amount": 2830.75,
  "nz_extra_pay_tax_breakdown": {
    "components": {
      "unused_holiday": 894.23,
      "alt_holiday": 127.74,
      "redundancy": 1240,
      "other": 568.78
    },
    "total_tax": 2830.75,
    "taxed_at_low_rate": false
  },
  "is_employee_terminated": true
}

taxed_at_low_rate is worth surfacing in your own interface: it is what sets the lump sum indicator on the Employment Information return, so it tells you how the payout was treated for payday filing.

11Reinstate, delete and restore

The three ways back. Two of them undo something, and the third undoes the other thing.

Reinstating a rehire

The body is optional. Send a start_date for the new period of employment, or send nothing and today is used.

{
  "start_date": "2026-09-01"
}

That last one surprises people. The termination that happened really did happen: it produced a final pay and it was reported. Reinstating does not rewrite history, so GET /api/employees/{id}/termination keeps returning that record afterwards, with is_employee_terminated now false. Read that field, not the presence of the record, to decide whether someone currently works there.

Two rules will reject a reinstatement:

• The new start date cannot be earlier than the termination date. Employment cannot resume before it ended.
• An unprocessed termination pay sitting on the employee blocks it with 409. Deal with that pay first, then reinstate.

Deleting and restoring a record

Delete is a soft delete returning 204 with no body. The record leaves the ordinary lists, and its pays, payslips, history and payroll number all stay exactly where they were. It is reversible with /restore, which returns the employee.

The payroll number staying reserved is deliberate: a deleted employee still holds their number, so reusing it for someone else is refused. If you are cleaning up a bad import and want the codes back, restore the record and renumber it rather than expecting the code to free itself.

Restore re-checks the customer's employee limit, because bringing a record back adds to the count. If they have filled their allowance since the delete, restore fails with 403 and the fix is a plan change, not a retry.

lightningpayroll.com.au/admin/employees/reinstate

12Employee webhooks

Register a URL once and we tell you when an employee changes, whoever changed it: your integration, the payroll clerk in the app, or the employee in their portal.

Every write to an employee record can raise a webhook delivery: creates, edits, terminations, reinstatements, restores and deletes all flow through the same three event types. There is no separate event per action, so knowing what actually happened means reading the payload, not just the event name.

The three employee events

What a delivery looks like

Every delivery is one JSON object, the same envelope regardless of event type:

// Envelope wrapping every webhook payload
{
  "id": "3fa8a3d2-9e35-4d9a-9d3b-9d8f7a2b6c1e",
  "type": "employee.updated",
  "createdAt": "2026-08-20T03:14:07.512331",
  "customerId": 40213,
  "entity": { "type": "employee", "id": 8842 },
  "data": { ... }
}

data is the full employee read model, the same shape returned by GET/api/employees/{employee_id}, not a partial diff of the fields that changed. A soft delete does not arrive as an employee.updated payload with a flag flipped inside it: it is reclassified to employee.deleted before it ever reaches your endpoint, so filtering on the event type alone is enough to catch it. Note that the envelope's own id is refreshed every time the payload is (re)built, including when a queued delivery is coalesced with newer state (see below); it is not stable the way the X-LP-Delivery-Id header is.

Coalescing

A webhook delivery represents an employee's state at a point in time, not a row in an audit log. Two collapsing rules apply before anything reaches your endpoint:

• Create immediately followed by update, in the same commit. If an employee row is created and then edited again before that transaction commits, only one event is raised, employee.created, carrying the state after the edit. The intermediate "just created" state is never delivered as its own event.
• Repeated edits before the previous delivery has been attempted. If an employee changes again while an earlier delivery for that employee is still queued and unsent, the queued delivery is rewritten in place with the newer state rather than a second delivery being queued behind it. This collapsing is matched on the event type as well as the employee, so it only merges repeated changes that raise the same event. A create still waiting to be sent when the same employee is edited in a later commit leaves you with two unsent deliveries, one employee.created and one employee.updated, rather than one merged delivery. Once a delivery has been attempted at least once, this no longer applies: further changes queue as their own, separate delivery, so you can legitimately receive more than one delivery for the same employee if an earlier attempt already went out.

The consequence for an integrator: do not build a per-change audit trail on top of webhooks. It is not one. A gap between two deliveries' data can hide any number of intermediate edits, and one delivery is not guaranteed to correspond to one user action. Treat each delivery as "this employee's state as of now"; if you need a full history of what changed and when, keep it in your own change log rather than inferring it from webhook traffic.

Verifying a delivery

Every delivery carries these headers:

The signed string is {timestamp}.{raw body}, a literal dot joining the exact value of X-LP-Timestamp to the exact bytes of the request body, HMAC-SHA256'd with your endpoint's secret:

# timestamp and raw_body must be the exact header value and exact request body bytes as received
import hmac
import hashlib

def verify_signature(secret: str, timestamp: str, raw_body: bytes, signature: str) -> bool:
    signed = timestamp.encode("utf-8") + b"." + raw_body
    expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

The critical detail is raw body. Verify against the exact bytes your server received, before any JSON parsing or re-encoding. Re-serializing the parsed body, even with logically identical data, produces a different key order, whitespace or escaping, and therefore a different byte string and a signature mismatch.

Retries

A delivery gets up to 8 attempts. Any 2xx response is the only thing that counts as success; a non-2xx response, a network error, or no response inside the 10 second request timeout all count as a failed attempt and schedule a retry. Redirects are not followed.

The wait before each attempt doubles, starting at 30 seconds:

If attempt 8 fails, the delivery is marked failed and nothing further is sent. Total elapsed time across all 8 attempts is a little over an hour, so a listener that is briefly unavailable (a deploy, a restart) has roughly that long to come back before the delivery gives up on it.

A delivery's status is one of:

Reconciliation

If your integration only reacts to webhooks, three shipped behaviours can leave you holding stale or incomplete state: nothing enforces a replay window on our end, so a delivery can still land and look valid well after the change it describes; deliveries coalesce, so intermediate states are silently skipped rather than delivered; and a delivery that never gets a 2xx inside its 8 attempts simply stops, with nothing ever reaching you for that particular change.

The reliable pattern is to treat a webhook purely as a prompt to look, not as the update itself: on receipt, call GET/api/employees/{employee_id} and use that response as your source of truth, rather than acting on data in the payload for anything that matters downstream. This also sidesteps ordering problems: if two deliveries for the same employee ever arrive out of sequence, reading the employee back gives you its current state regardless of which delivery triggered the read.

Registering an endpoint, choosing which events it receives, rotating its secret, and pausing it without losing delivery history are covered in the Webhooks Guide.

lightningpayroll.com.au/admin/manage-api

13Endpoint reference

Every employee lifecycle endpoint on the partner surface, with the scope each one needs.

This table is a quick reference. The OpenAPI schema at /openapi.json is authoritative and machine readable: use it to generate a client, confirm a field name, or check a response shape rather than this page.

14Related guides

This guide assumes you already have a token and stops where payroll processing begins. These pick up the rest.