Appearance
Retries and idempotency
A network failure can leave you unsure whether a request went through. Retrying a create blindly can make a duplicate.
The REST API has no general idempotency key — no Idempotency-Key header. The one exception is creating a payment message (v04 beta), which accepts an Idempotency-Key header: see Payment channels and Limits. Otherwise idempotency is endpoint-specific; this page collects what makes a retry safe.
Give your records your own id, and look before you create
Set your system's id on what you create, then search for it before creating again.
| Object | Your id goes in | Find it again with |
|---|---|---|
| Employment | info.sourceId | GET /v03/api/employments?$filter=externalId eq 'ID98765432' — sourceId is indexed as externalId |
For employments this also prevents a duplicate worker record: store info.workerAccountId from the first response and send it on any later employment for the same person — see Create employees.
Safe to repeat
- Re-reporting an invoice's current status is a safe no-op — see Invoices and payments.
- Reads (
GET) are always safe.
Never repeat blindly
- Committing a payroll for payment. A calculation that is already
paymentStartedcannot be committed again, and apaymentSucceededone is never paid twice — but check the status before you retry. See Set for payment.
On the MCP server
On the authenticated MCP server, calculation rows added with a sourceId replace rows added earlier with the same id — so repeating the same request does not double the rows. Employment default rows and rows added by hand are left alone.
Checklist
- Every object you create carries your own id where the API allows one.
- A retry after a timeout searches before it creates.
- Payment commits are checked by status before any retry.

