Provision a company
Your backend creates a Payroo company for one of your customers in a single call. Payroo creates the organisation, its first admin user, the delegation that lets you act for it, and the defaults payroll needs, as one operation with eight steps you can watch and, if needed, finish later.
Credential: your partner credential (x-api-key). No session is involved.
The call
curl -X POST https://sandbox.payroo.com.au/api/v1/embedded/employers \
-H "x-api-key: $PAYROO_PARTNER_KEY" \
-H "content-type: application/json" \
-H "idempotency-key: $(uuidgen)" \
-d '{
"externalEmployerId": "acme-001",
"business": {
"name": "Acme Test Cafe",
"legalName": "Acme Test Cafe Pty Ltd",
"abn": "51824753556",
"address": { "line1": "1 Example St", "suburb": "Sydney", "state": "NSW", "postcode": "2000" }
},
"primaryUser": { "externalUserId": "user-42", "email": "owner+acme001@yourdomain.test", "firstName": "Ada", "lastName": "Owner", "phone": "0400000000" },
"prefill": { "frequency": "fortnightly", "defaultHoursPerWeek": 38 }
}'
| Field | Rule |
|---|---|
externalEmployerId |
your own id for the company, 1 to 200 characters. From now on you may address the company as ext:acme-001 wherever an employerId is expected |
business.abn |
11 digits with a valid check digit; on sandbox a generated test ABN |
primaryUser |
the person who will administer payroll for the company in your product; externalUserId is your id for them, email must be a mailbox they (on sandbox: you) control, phone becomes the employer contact for super |
prefill |
optional pay frequency and default hours, so Company setup starts filled in |
What you should see: 201 with provisioning { operationId, state, steps[] }. employerId appears once the organisation step succeeded and primaryUserId once membership_and_mapping did. The call runs the steps inline, so a healthy run answers with state: succeeded straight away.
A second call with the same externalEmployerId answers 200 with the existing result: the call is safe to retry and safe to run from a job that may restart.
The eight steps
| Step | What Payroo does | If it fails |
|---|---|---|
organisation |
creates the organisation with its address and the prefilled pay settings | 409 abn_exists_elsewhere means the ABN already belongs to another organisation: use another ABN (sandbox) or contact Payroo (production) |
membership_and_mapping |
creates the primary user, their administrator membership and the mapping from your externalUserId |
resume |
delegation |
records that your partner may act for this company | resume |
defaults |
default location and public holiday groups | resume |
identity_provider |
the user's identity at Payroo's identity provider; when Payroo has enabled it for your record, the invitation e-mail that lets them set a password | an e-mail failure never fails the step |
payments_account |
the payments account for salary payments; skipped where payments are off |
nothing to do |
features |
the modules the company uses (payments, timesheets, calendar) | resume |
notifications |
Payroo's internal event about the new company | non-fatal |
Watch and resume
curl https://sandbox.payroo.com.au/api/v1/embedded/operations/$OPERATION_ID -H "x-api-key: $PAYROO_PARTNER_KEY"
state is one of pending, running, succeeded, failed, needs_attention; each step carries its own state and, when failed, an error { code, message }.
When state is failed, call POST /operations/{operationId}/resume: only the steps not yet succeeded or skipped run again. 409 operation_not_resumable means the operation already succeeded or is running under a live lease (another resume is in flight): read it again a few seconds later. needs_attention is Payroo's to resolve; quote the operation id to support.
If you receive webhooks, employer.provisioned arrives when the operation succeeds and employer.provisioning_failed when it fails, so a background job need not poll.
The primary user's first sign-in
Everything your users do inside your product runs on sessions you mint; they never sign in to Payroo for day-to-day work. Four actions ask them to confirm with Payroo directly, in a Payroo dialog: changing a bank account, approving a pay run, lodging, and payouts (see Authentication and sessions). The first time, the primary user sets a Payroo password: from the invitation e-mail when Payroo has enabled it for your record, otherwise with Forgot password in that first dialog, pre-filled with their address. On sandbox, make sure the e-mail reaches a mailbox you can open.
Companies that already use Payroo
A business that already runs payroll on Payroo is not provisioned again. Payroo staff delegate the existing company to your partner record on the business's written authority, and map its administrator to your user id. Ask Payroo with the company's name and ABN and the authority you hold; afterwards you mint sessions for it exactly as for a company you created.
Errors you may see
| Status and code | Meaning | Next action |
|---|---|---|
401 invalid_credential |
wrong or revoked credential | check the secret on your server |
401 credential_expired |
a rotated credential past its overlap | switch to the new credential |
403 partner_inactive |
your partner record is suspended | contact Payroo |
409 abn_exists_elsewhere |
the ABN is taken by another organisation | another ABN, or ask Payroo to delegate the existing company |
409 idempotency_in_progress |
the same Idempotency-Key is still being processed |
wait and retry with the same key |
422 validation_failed |
a field is wrong; error.details.fields[] names it |
fix the field |