API Documentation

Getting Started

Welcome to the Lightning Payroll API. We use the OAuth 2.0 Authorization Code flow so your app can access customer payroll data securely and in a way developers already know.

Environments

Getting API Access

To access the Lightning Payroll API, your company must first be granted access by our development team. This step ensures only approved clients can generate credentials for secure integration.

If you don’t yet have access, please contact our team here to get started.

Once access has been granted, you'll be able to visit the API Management section of your admin dashboard to create a Client ID and Client Secret. These are required to begin the OAuth 2.0 Authorisation Code flow described above.

Authorization Code Flow

GET {base}/api/oauth/authorize?
  client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fyourapp.com%2Foauth
  &state=xyz123
  &scope=openid%20payroll.write

POST {base}/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=THE_CODE_FROM_STEP_2&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
redirect_uri=https%3A%2F%2Fyourapp.com%2Foauth

{
  "access_token":  "…",
  "token_type":    "Bearer",
  "expires_in":    1800,
  "refresh_token": "…",
  "refresh_expires_in": 2592000
}

POST {base}/api/oauth/token
grant_type=refresh_token&
refresh_token=YOUR_REFRESH_TOKEN&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
redirect_uri=https%3A%2F%2Fyourapp.com%2Foauth

Token Lifetimes

Authentication Endpoint Reference

Scopes

Request scopes as a space-separated list in the scope query parameter of the authorize step. Ask only for what you need: the scope set is fixed at authorization time, so widening it later means sending the customer back through consent.

Partner Free Trials

If you are a reseller partner, you can start a client on a free one-month trial without placing a billed order. A trial creates no order, so it never reaches an invoice and is never renewed. When the trial ends you place the real order against the same client. Trial emails carry your own branding where you have white-label branding configured.

POST {base}/api/partner-checkout/trials
Authorization: Bearer YOUR_ACCESS_TOKEN
Idempotency-Key: 6f1c9a2e-trial-0001

{
  "customer": {
    "first_name": "Alice",
    "last_name": "Nguyen",
    "email": "alice@example.com",
    "phone": "+61 7 3000 0000"
  },
  "company": {
    "legal_name": "Sunrise Hospitality Pty Ltd",
    "abn": "10000000000"
  }
}

GET {base}/api/partner-checkout/trials?status=active

POST {base}/api/partner-checkout/orders
Idempotency-Key: 6f1c9a2e-order-0001

{
  "dry_run": false,
  "end_customer_id": 192601,
  "customer": { "email": "alice@example.com", ... },
  "company":  { "legal_name": "Sunrise Hospitality Pty Ltd",
                "abn": "10000000000" },
  "billing_address": { ... },
  "order": { "product_id": 243 }
}

Using Your Access Token

Once you have received an access_token, you can begin calling protected endpoints by including it in the Authorization header of your HTTP requests, using the Bearer scheme:

    Authorization: Bearer YOUR_ACCESS_TOKEN
    

This is required for all endpoints that need authentication. Make sure to replace YOUR_ACCESS_TOKEN with the actual token string you received in Step 3 above.

Webhooks

Rather than polling us for changes, register a URL and we will POST to it when a company, an employee or a completed pay is created, updated or deleted. Every delivery is signed, retried on failure, and recorded in a delivery log you can inspect. Webhook management requires an API admin account; a token whose customer is not an API admin gets 403 on every webhook endpoint.

Event Catalogue

Nine event types across three entities. Name each event you want; there is no wildcard. The authoritative list is returned as availableEvents by GET /api/webhooks, so read it at runtime if you want to pick up additions automatically.

• Pay events only fire for a completed pay, and which one you get depends on how it was completed. A pay inserted already complete in one operation arrives as pay.created; a pay saved as a draft and completed later arrives as pay.updated with no preceding pay.created. Subscribe to both. A draft pay produces nothing at all.
• A soft-deleted employee arrives as employee.deleted, not as an employee.updated that happens to flip a flag.
• Repeat changes to the same entity collapse into a single delivery carrying the latest state while that delivery is still undelivered, so expect fewer events than edits. There is no content-based deduplication though, so you can also be handed the same data twice and must tolerate it.

Registering an Endpoint

POST {base}/api/webhooks
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "url": "https://yourapp.example.com/hooks/lightning-payroll",
  "events": ["employee.created", "employee.updated", "pay.created", "pay.updated"],
  "description": "Production employee sync",
  "is_active": true
}

Your url must be an absolute http or https URL whose host resolves to a publicly routable address. Use https, because the payload carries payroll data. localhost, .local, .internal, loopback, private RFC1918 ranges and cloud-metadata addresses are rejected with 422 at registration, and the same check runs again on every send, so a host that later becomes unroutable simply fails that attempt and the reason appears in the delivery log. That means you cannot point a registered webhook at your own machine: use a public hostname or a tunnel.

The URL is lightly normalised before storage: surrounding whitespace is trimmed and < and > are stripped. It may be at most 512 characters, and anything longer is rejected with a 422 rather than truncated. description is your own routing note, never sent to your listener; it is trimmed the same way and may be at most 255 characters, likewise rejected rather than truncated.

Verifying a Delivery

Each delivery arrives as a POST with Content-Type: application/json and four X-LP-* headers.

# Python
signed   = timestamp.encode() + b"." + raw_body   # raw_body exactly as received
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers["X-LP-Signature"]):
    abort(401)

Payload Shape

{
  "id": "9f2b1c84-6d1e-4a7f-9c0b-2e5d7a3f8b41",
  "type": "employee.updated",
  "createdAt": "2026-08-07T04:11:07.482913",
  "customerId": 192601,
  "entity": { "type": "employee", "id": 4412 },
  "data": { ... }
}

customerId is the end customer whose data changed, not your own partner account, so it is what you route on to attribute an event to the right client. data is built from the same model the REST API uses for that entity, but through a different serialiser, so parse it permissively: jurisdiction-specific fields are not pruned, and a record that fails strict validation falls back to a raw column dump.

Deduplicate on the pair (X-LP-Delivery-Id, payload id). The delivery id is stable across every retry, and a delivery we have already attempted is never re-armed with different data. A delivery that is still queued and untried can be replaced in place if the entity changes again, so in rare cases one delivery id carries a newer payload. Keying on the pair is safe in both cases: skip work only when both values match something you have already processed.

Delivery Statuses and Retries

Any 2xx response counts as delivered. Redirects are not followed, so a 301 or 302 is a failure. We wait up to 10 seconds, so acknowledge with a 2xx first and do your real work asynchronously.

pending sending delivered retry failed skipped

A failed delivery is retried with doubling backoff for a maximum of 8 attempts: 30s, 1m, 2m, 4m, 8m, 16m, then 32m between attempts. From the first attempt to the last is a little over one hour, after which the delivery is failed and never retried. Treat those times as lower bounds, since due deliveries are picked up on a short recurring sweep. skipped means the endpoint was deleted or deactivated between queueing and sending.

A delivery left in sending because a worker restarted mid-attempt is reclaimed automatically and resumes its remaining attempts, so every delivery settles as delivered or failed rather than stalling.

API Conventions

Cross-cutting behaviour that applies across the whole surface. Worth reading once before you write a client.

Rate Limits

Most endpoints share a general limit. Pay endpoints are much tighter and cheap lookups are looser. Limits are enforced per client.

Exceeding a limit returns 429 with {"error": "Rate limit exceeded: ..."}. A separate burst guard also returns 429 with {"detail": "Too Many Requests"} and a Retry-After header if you send a sharp spike from one IP. Under heavy load you may also see 503 with Retry-After: 5, which is a transient overload signal rather than a rate limit: retry with backoff.

Idempotency

The partner-checkout write endpoints take an Idempotency-Key header so a network failure cannot double-charge a client. It is required on POST /api/partner-checkout/trials, and on POST /api/partner-checkout/orders and /upgrades whenever dry_run is false.

Keys are scoped to your partner account, so they can never collide with another partner's, but they are shared across orders, upgrades and trials: reusing one key for a different endpoint still counts as a payload mismatch. Generate a fresh UUID per logical operation and keep it for the life of your retries. Do not rely on a key expiring, and do not rely on a key still replaying once your retry window has passed.

Error Shapes

Three different response shapes exist, and a client that only parses one will silently read undefined from the others.

Treat the message and detail strings as human-readable diagnostics rather than stable machine identifiers: branch on the HTTP status, and log the string.

Dates, Money and Lists

• Timestamps are ISO 8601 in UTC with no Z suffix and no offset, for example 2026-05-02T04:11:07. Parse them as UTC explicitly; most libraries will otherwise assume local time and shift your data.
• Money is a JSON number, not a string, and is not zero-padded to a fixed number of decimal places, so 0 and 1250.5 are both normal. Never compare amounts by string equality. Some request bodies accept either a number or a numeric string; responses are always numbers.
• Lists vary per endpoint, and there is no page parameter anywhere. Partner-checkout lists take limit plus offset (default 25, maximum 100). The webhook delivery log takes limit only (default 100, maximum 500) with no offset, so it always returns the newest rows and cannot be paged past 500; narrow it with its filters instead. Some list endpoints, including GET /api/company and the company employee list, are not paginated and return everything.

Companies and Access

Payroll endpoints identify the company by path parameter, as /api/company/{company_id}/.... There is no header-based company selector.

• Calling a company you do not have access to returns 403 with {"detail": "User does not have access to this company."}.
• A company id that does not exist returns 404 with {"detail": "Company not found."} on GET /api/company/{company_id}, but most other company-scoped endpoints return 400 with {"detail": "No company found with the given company_id"}. Treat both as company-not-found.
• GET /api/company silently omits companies you cannot access rather than failing, so treat its result as the definitive list of what you may act on. Note this includes omitting on a scope failure: a token with no payroll scope gets 200 and an empty array rather than a 403. If that list is unexpectedly empty, check your granted scopes before concluding the customer has no companies.
• Pass only records that belong to the company in the path. A record belonging to a different company is reported as not found rather than returned, and a 404 does not distinguish between a record that does not exist and one you may not see.
• AU only: the employee super-fund endpoints and the Single Touch Payroll endpoints apply to Australian payroll. They remain callable on the NZ host but are not part of NZ payday filing, so NZ integrations should ignore them.