Get started

Register, take the key, call an endpoint. Three requests, and no conversation with us in between.

Do it in the browser instead

1. Register

No credential, because you do not have one yet. This is the only endpoint on the platform that works without one.

curl -X POST https://sandbox.droomwork.io/v1/registrations \\
  -H 'Content-Type: application/json' \\
  -d '{"organisation_name": "Acme Ltd", "email": "dev@acme.example", "password": "correct-horse-battery"}'

You get an organisation, a signed in session, and the organisation's first sandbox key:

{
  "object": "registration",
  "sandbox": true,
  "organisation": { "id": "org_...", "name": "Acme Ltd" },
  "session": { "token": "dwp_..." },
  "api_key": { "id": "key_...", "realm": "test", "key": "dw_test_..." }
}

The key is shown once. No endpoint returns it again. Keep it now. If you lose it, make another from your dashboard and revoke the old one.

One organisation per address. Register the same address twice and you get a conflict rather than a second organisation, so a form submitted twice does no harm.

2. Call an endpoint

The key goes in Droomwork-Api-Key. Every endpoint in the reference takes it.

curl https://sandbox.droomwork.io/v1/payroll/runs \\
  -H 'Droomwork-Api-Key: dw_test_...'

Anything that changes data also needs an Idempotency-Key, so a retry after a timeout cannot do the work twice:

curl -X POST https://sandbox.droomwork.io/v1/payroll/runs \\
  -H 'Droomwork-Api-Key: dw_test_...' \\
  -H 'Content-Type: application/json' \\
  -H "Idempotency-Key: $(uuidgen)" \\
  -d '{"period": "2026-09", "run_type": "regular"}'

3. Read the reference

Start with the module you bought: ANCHOR, PROOF, RAIL, FLOW, MATCH, RUN, REMIT, ROUTE. The platform underneath has its own pages: IAM, DELIVERY, LEDGER.

Direct HTTP, or the client library?

Everything above was direct HTTP: an address, a key, a JSON body. Every operation in the reference also has a sample that uses our client library in JavaScript, Python, PHP, Java, C# or Go, and a switch above the samples picks one; the choice is kept from page to page.

Direct when you want to own every byte, your language isn't one we ship a library for, you're calling one or two operations, or you already have an HTTP layer of your own. The library when you're integrating a whole module and want a wrong field caught before the API sees it. Same request, same answer, same rules either way: how to choose.

What your key can and cannot do

A first key carries every scope in the sandbox, so nothing you try first fails for the wrong reason. Scopes are per module and per action, run:read and run:write and run:approve, and a later key can carry fewer.

It is a sandbox key and it is only ever a sandbox key. You cannot use it against the live API, no money moves, no filing is made, and every response carries "mocked": true and "livemode": false, so you never mistake a mocked figure for a computed one.

When something is refused

Every refusal is a problem document with a code that is stable forever. Branch on the code, never on the message. The error index lists all of them, what each means, and which endpoints return it.