# Using the API
Source: https://www.desktopaccountingapi.com/docs/api/

> Base URL, versioning, headers, request IDs, response formats and the OpenAPI document behind the Desktop Accounting API reference.

The [API reference](https://www.desktopaccountingapi.com/docs/api/reference/) documents every operation, parameter and field. It is generated from the same schema that validates live requests, so it cannot drift from what the API accepts. This page covers what applies to every call.

## Base URL

```
https://api.desktopaccountingapi.com/v1
```

HTTPS only. QuickBooks Desktop operations live under `/v1/quickbooks-desktop/`; platform resources (`/v1/end-users`, `/v1/auth-sessions`, `/v1/requests`, `/v1/webhook-endpoints`) live directly under `/v1/`.

## Versioning

The major version is in the path. Within `v1` we only add: new operations, new optional request fields, new response fields, new enum values, new error codes and new webhook event types. Build clients that ignore unknown fields and handle unknown enum values; the SDKs already do. A breaking change would ship as `/v2`, and `/v1` would keep working for at least 12 months after that. The [changelog](https://www.desktopaccountingapi.com/docs/platform/changelog/) lists every change.

## Request headers

| Header | Used on | Meaning |
| --- | --- | --- |
| `Authorization: Bearer sk_...` | Every call | Your secret key. See [Authentication](https://www.desktopaccountingapi.com/docs/get-started/authentication/). |
| `Daapi-End-User-Id` | `/v1/quickbooks-desktop/*` | The end user whose company file to use. |
| `Idempotency-Key` | `POST` and `DELETE` | Makes retries safe. See [Idempotency](https://www.desktopaccountingapi.com/docs/guides/idempotency/). |
| `Daapi-Timeout-Seconds` | QuickBooks calls | How long a sync call waits, 1 to 300 seconds. Default 90, health check 60. |
| `Prefer: respond-async` | QuickBooks calls | Return `202` at once instead of waiting. See [Request lifecycle](https://www.desktopaccountingapi.com/docs/guides/request-lifecycle/#async-mode). |
| `Daapi-Queue-Ttl-Seconds` | Async QuickBooks calls | Latest time the request may still be sent, 10 to 86400 seconds. Default 3600. |
| `Content-Type: application/json` | Calls with a body | Passthrough also accepts `application/xml`. |

Unknown `Daapi-*` headers are rejected with `400 UNKNOWN_HEADER`, so a typo such as `Daapi-Timeout` fails instead of silently using the default.

## Response headers

| Header | Meaning |
| --- | --- |
| `Daapi-Request-Id` | `req_...` on every response, including errors. Log it; support and the dashboard find requests by it. |
| `Daapi-Should-Retry` | `true` or `false` on every error. Whether the same request can succeed later. |
| `Retry-After` | Seconds to wait, on `429` and some `503` responses. |
| `Daapi-Idempotent-Replayed` | `true` when the body is a stored replay of an earlier call with the same idempotency key. |
| `Daapi-Warnings` | Number of QuickBooks warnings recorded on the request, plus values read leniently from damaged data. Details are on the request resource. |
| `Location`, `Preference-Applied` | On `202` async responses: the request URL, and `respond-async`. |
| `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `RateLimit-Policy` | The project's rate-limit window, on every authenticated response. See [Rate limits](https://www.desktopaccountingapi.com/docs/guides/rate-limits/). |

## Formats

- JSON in and out, `camelCase` fields, `snake_case` enum values, `null` for empty values, `[]` for empty lists.
- Money as decimal strings, dates as `YYYY-MM-DD`, QuickBooks timestamps with the customer computer's UTC offset.
- Strict request bodies: unknown fields are rejected.

Details are in [Money, dates and data conventions](https://www.desktopaccountingapi.com/docs/quickbooks/conventions/).

## Status codes

| Status | Meaning |
| --- | --- |
| `200`, `201` | Success. `201` for creates. |
| `202` | Accepted in async mode. |
| `400`, `410`, `413`, `422` | Invalid request; nothing changed. |
| `401`, `403` | Authentication or permission problem. |
| `402` | Billing blocks production data requests. |
| `404` | Unknown resource, or a QuickBooks record that does not exist. |
| `409` | Conflict: stale revision, duplicate name, setup not finished, request no longer cancelable. |
| `429` | Rate or queue limit. Retry after `Retry-After`. |
| `500`, `502`, `503`, `504` | Our problem, the customer's connection, or a timeout. Check `retryable` and `outcome`. |

Every error has the same body. See [Error handling](https://www.desktopaccountingapi.com/docs/guides/error-handling/) and the [error code reference](https://www.desktopaccountingapi.com/docs/errors/).

## OpenAPI document

The OpenAPI 3.1 document behind the reference and the SDKs is published at [/docs/openapi.json](https://www.desktopaccountingapi.com/docs/openapi.json). Use it to generate a client in another language, import the API into an HTTP tool, or give an AI assistant the full schema. The error catalog is at [/docs/errors.json](https://www.desktopaccountingapi.com/docs/errors.json). A plain-text index of these docs for language models is at [/docs/llms.txt](https://www.desktopaccountingapi.com/docs/llms.txt).

The document carries a few extensions:

| Extension | Meaning |
| --- | --- |
| `x-daapi-pagination` | `cursor` or `none` on list operations. See [Pagination](https://www.desktopaccountingapi.com/docs/guides/pagination/). |
| `x-daapi-qbxml` | The qbXML message an operation uses, and its minimum qbXML version. |
| `x-daapi-open-enum` | The enum can gain values; handle unknown ones. |
| `x-daapi-runtime-header` | A header the SDK runtimes set for you. |
| `x-daapi-format: date-or-date-time` | A filter that accepts a date or a date-time. |
| `x-tagGroups` | How tags are grouped in the reference navigation. |

## Reading the reference

The reference groups operations by area: **Platform** (end users, auth sessions, requests, webhooks, health check, passthrough), **Transactions**, **Lists**, **Items** and **Reports**. Each resource has an overview page and one page per operation with its parameters, request body, responses, errors and a `curl` example. Use search (press <kbd>/</kbd>) to jump to any operation or field.