Direct HTTP or the client library

Two ways to call the API, both first class

Every operation on the reference pages has two samples: one that uses nothing but your language's own HTTP client, and one that uses our client library. They send the same request and get the same answer. The switch above the samples picks one, and the choice is kept from page to page.

Direct HTTP

The API as it is: an address, a bearer token, a JSON body, and for anything that changes data an Idempotency-Key header. Choose it when:

• you want to see exactly what goes over the wire, and own every byte of it;
• your language or runtime isn't one we ship a library for, or you can't add a dependency;
• you're calling one or two operations, and a library is more than the job needs;
• you already have an HTTP layer with its own retries, logging and tracing, and you'd rather the API fit into it than sit beside it.

You get no help from types, and you handle the envelope yourself: check code on an error, read has_more on a list, and keep the Idempotency-Key you sent so a retry is the same request.

The client library

The same calls in your language's own shapes: a typed request, a typed response, the base address and the token set once, the idempotency key generated for you. Choose it when:

• you're integrating a whole module rather than one call, and want the compiler or the IDE to catch a wrong field before the API does;
• you'd rather write api.payrollRunsCreate(...) than assemble a request by hand;
• you want new operations to arrive as a version bump instead of new code.

The library is generated from the same documents these pages are rendered from, so it never knows an operation the API doesn't, and it never lags a field.

Either way, the rules are the same

The sandbox key you hold is a sandbox key in both. Every write needs an idempotency key in both. Every error carries a stable code in both. Pick one per project rather than per call.