Usage and audit

Three server-to-server reads tell you where a company stands, what has been done to it, and how much of Payroo your partnership used. All three take your partner credential (x-api-key) and return identifiers, states and counts; never payroll values or personal data.

Company status

GET /v1/embedded/employers/{employerId}/status

readiness (the same five steps the Company setup component shows), currentPayrun { id, state, period } when one is open, and blockers with their nextAction. Use it for a dashboard of your customers' payroll state without minting a session. 403 employer_not_delegated for a company that is not yours.

Audit

GET /v1/embedded/employers/{employerId}/audit?from=&to=&cursor=

Newest first, 50 per page, five fields per row and nothing else: at, actorType (employer, employee, partner, payroo_support, system), operation (for example payruns.approve, employees.create, webhooks.config_write), resourceType, outcome (ok, denied, failed). Every call your sessions and your credential make is in it, with the refusals.

When you contact Payroo about a request, quote its X-Correlation-Id response header: it matches Payroo's own audit record for that request, which holds more than the five fields you see.

Payroo support can read a company's status and audit only under a support delegation: a time-boxed record (up to seven days) a Payroo administrator creates for one support person and one company, on your or the business's request. Those reads are audited with both parties.

Usage

GET /v1/embedded/usage?month=2026-11

Written nightly for the current and the previous month; 404 not_found until the first nightly run of a month. activeEmployers (delegations active at the time of the record), employeesPaid (distinct employees in pay runs published in the month), payrunsLodged (handed to the ATO channel) and payrunsAccepted, with computedAt. These are the figures Payroo's partner invoices are built from, so reconcile against them.

What you should see

After the sandbox walkthrough, status shows readiness.ready: true and no blockers; audit lists your provisioning, setup, employee and pay run calls with outcome: ok and the refusals you provoked with denied; usage for the month shows the company among activeEmployers and, after a lodgement, payrunsLodged: 1.

Errors you may see

Status and code Meaning Next action
403 employer_not_delegated the company is not delegated to you check the id; ask Payroo about the delegation
404 not_found on /usage the nightly has not written that month yet read the previous month or wait a day
422 validation_failed month not YYYY-MM, or a bad date range fix the query