# InvoiceQuickly Public API (v1)

> **Status: live.** The public API is available in production at `https://invoicequickly.com/api/v1` for organizations on a paid plan (Pro and above). Owners and admins create keys on the **Developers** page. Free organizations get `403 upgrade_required`. Changes are recorded in the [Changelog](#changelog).
>
> **Zapier:** The InvoiceQuickly Zapier integration works today for organizations on a paid plan, through a private invite link: <https://zapier.com/developer/public-invite/248713/4b2160342981ef600cc2eee3f62e83fd/>. It is not listed in Zapier's public app directory while Zapier's public review is pending. See [Zapier integration (private)](#zapier-integration-private). No other app marketplace lists InvoiceQuickly, and this API does not provide or imply native sync with any accounting or time-tracking tool.

The InvoiceQuickly public API lets you read and create clients, create draft invoices, ask AI for an invoice proposal that is never saved, read invoices and read successful payments for one organization, using an API key sent as a Bearer token. It is a JSON over HTTPS API meant for server-to-server calls.

## At a glance

| Topic | Value |
| --- | --- |
| Base path | `/api/v1` on your InvoiceQuickly app origin |
| Plan | A paid plan: Pro and above, checked on every request. Free organizations get `403 upgrade_required`; their keys can still be listed and revoked |
| Authentication | `Authorization: Bearer iq_...` (API key) |
| Key format | `iq_` followed by 43 base64url characters (46 characters total) |
| Scopes | `clients:read`, `clients:write`, `invoices:read`, `invoices:write`, `payments:read` |
| Key expiry | 90 days by default, at most 365 days |
| Active keys | At most 20 per organization |
| Rate limit | 60 requests per key per clock minute, plus 120 requests per client IP per clock minute |
| Request body | JSON only, at most 128 KiB (131,072 bytes) |
| Page size | `limit` 1 to 100, default 25, newest first |
| POST requests | `Idempotency-Key` header required, replayed for 24 hours |
| `POST /invoices` | Creates `draft` invoices only; totals computed by the server |
| `POST /invoices/ai-draft` | Returns an AI invoice proposal for review. Never saves, sends or charges anything |
| Outbound webhooks | None. Poll list endpoints to detect new records. |

## Contents

- [Base URL and versioning](#base-url-and-versioning)
- [Authentication and API keys](#authentication-and-api-keys)
- [Managing API keys](#managing-api-keys)
- [Rate limits](#rate-limits)
- [Requests, responses and headers](#requests-responses-and-headers)
- [Pagination and filtering](#pagination-and-filtering)
- [Idempotent POST requests](#idempotent-post-requests)
- [Endpoints](#endpoints)
- [Errors](#errors)
- [Security notes](#security-notes)
- [Using the API with automation tools](#using-the-api-with-automation-tools)
  - [Zapier integration (private)](#zapier-integration-private)
- [Changelog](#changelog)

## Base URL and versioning

All public API endpoints live under `/api/v1` on the same origin as the InvoiceQuickly app. The examples below use a shell variable for the full base URL:

```bash
export IQ_API="https://YOUR-APP-ORIGIN/api/v1"
export IQ_API_KEY="iq_..."   # your key, never commit it
```

The version is part of the path. `GET /me` also reports `"apiVersion": "v1"`. There is no version header. Changes are recorded in the [Changelog](#changelog).

The API does not send CORS headers, so call it from a server or an automation tool, not from browser JavaScript on another site.

## Authentication and API keys

Send your key on every request in the `Authorization` header:

```http
Authorization: Bearer iq_EXAMPLEdoNotUseThisKey0000000000000000000xy
```

The header must match `Bearer ` (one space) followed by `iq_` and exactly 43 characters from `A-Z`, `a-z`, `0-9`, `-` and `_`, with nothing before or after. Any other value, a `Basic` header, or a missing header returns `401 unauthorized`.

### What a key belongs to

- Each key belongs to one organization and acts only on that organization's data. Records from other organizations are never returned and look like `404` responses.
- Each key records the user who created it. On every request the API looks up that user's **current** role in the organization.
- Only organization **owners** and **admins** can create, list and revoke keys.
- The organization needs a paid plan, Pro and above, to create keys and to call `/api/v1`. See [Plan requirement](#plan-requirement).

### Plan requirement

API access is included on every paid InvoiceQuickly plan: Pro, Business, and the legacy Business and Enterprise plans. A plan counts as paid while its subscription is active, trialing or past due. Free organizations, including those whose paid subscription has been canceled or has ended, cannot use the API.

The plan is checked on **every request**, not when the key is created. A downgrade takes effect on the next request, and so does an upgrade.

- **`/api/v1` calls:** every request made with a valid key returns `403 upgrade_required` with the message "A paid InvoiceQuickly plan is required for API access." This check runs after the key is authenticated (an invalid key still returns `401 unauthorized`) and before the scope, role and per-key rate-limit checks. A rejected request does not update the key's `lastUsedAt`.
- **Creating keys:** `POST /api/developer/keys` returns the same `403 upgrade_required`, so no new key can be created.
- **Listing and revoking keys:** still works after a downgrade. `GET /api/developer/keys` and `DELETE /api/developer/keys/{id}` do not check the plan, and the Developers page keeps showing the key list with **Revoke**.
- **Existing keys:** not revoked or changed. They stop working while the organization is on Free and work again after it upgrades, unless they have expired or been revoked in the meantime.

`upgrade_required` is not retryable. Upgrade the plan from **Billing** in the dashboard (`/dashboard/billing`); only the organization owner can change the plan.

### Scopes

A key has one to five scopes, chosen when it is created. Scopes cannot be changed later; create a new key instead.

| Scope | Allows |
| --- | --- |
| `clients:read` | `GET /clients`, `GET /clients/{id}` |
| `clients:write` | `POST /clients` |
| `invoices:read` | `GET /invoices`, `GET /invoices/{id}` |
| `invoices:write` | `POST /invoices` (draft invoices only) and `POST /invoices/ai-draft` (AI proposals, never saved) |
| `payments:read` | `GET /payments` |

`GET /me` needs no particular scope; any valid key can call it. A write scope does not imply the matching read scope. Calling an endpoint without its scope returns `403 insufficient_scope`.

### How the creator's role limits a key

A key can never do more than its creator is currently allowed to do in the organization:

| Creator's current role | Read endpoints and `GET /me` | Write endpoints (`POST`) |
| --- | --- | --- |
| Owner | Allowed (if the key has the scope) | Allowed (if the key has the scope) |
| Admin | Allowed | Allowed |
| Member | Allowed | Allowed |
| Viewer (or any unrecognized role) | Allowed | `403 forbidden` |
| No longer a member of the organization | `401 unauthorized` | `401 unauthorized` |

For example, if an owner creates a key with `clients:write` and is later changed to viewer, `POST /clients` with that key starts returning `403 forbidden` while `GET /clients` keeps working. Deleting the creator's user account deletes their keys.

### Expiry, revocation and last use

- **Expiry:** keys expire 90 days after creation unless you choose another expiry on the Developers page or pass `expiresAt` to the endpoint. A custom expiry must be in the future and no more than 365 days ahead. Expired keys return `401 unauthorized`.
- **Revocation:** revoking a key takes effect on the next request. Every request checks the database for the key's revoked and expiry state; nothing is cached.
- **`lastUsedAt`:** updated on each request that passes authentication, scope, role and the per-key rate limit. It is not updated by requests rejected with `401`, `403` or `429`. It is updated even if the request later fails validation.
- **Prefix:** the first 12 characters of the key (for example `iq_EXAMPLEdo`) are stored and listed so you can tell keys apart. The rest of the key is never shown again.

## Managing API keys

Manage keys on the **Developers** page of the InvoiceQuickly dashboard (`/dashboard/developers`). This is the normal way to create, review and revoke keys. You cannot manage keys with an API key.

### The Developers page

- **Who sees it:** the **Developers** item appears in the dashboard menu, after Integrations, only when the API is enabled (`PUBLIC_API_ENABLED` is `"true"`) and you are an organization **owner** or **admin**. With the API disabled the page returns 404. Members and viewers who open the URL directly see an access-denied message, and no key data is loaded.
- **Free plan:** owners and admins of a Free organization see **API access is part of the Pro plan** with a **See plans** link to `/dashboard/billing`.
  - With no keys, that message replaces the key list.
  - With keys left from a paid plan, the key list stays visible with **Revoke**, and the message explains that those keys don't work on Free. **Create API key** is hidden.
  - If the plan changes to Free while a key is being created, the create dialog closes and the message appears.
- **Create a key:** choose **Create API key**, then enter a **Name** (1 to 80 characters), tick one or more **Scopes** (each checkbox describes what it allows), and pick **Expires after**: 30, 90 (recommended, the default), 180 or 365 days. The 365-day option is sent as 365 days minus 10 minutes, so it stays inside the server's 365-day limit even if your computer's clock runs slightly ahead of the server's.
- **Copy the key once:** the full key appears a single time, in the **Your new API key** dialog, with a **Copy key** button. If copying fails, the key is selected so you can copy it by hand. After you choose **Done**, the key is never shown again, anywhere. If you lose it, revoke it and create a new one.
- **Key list:** every key in the organization, including expired and revoked ones, shows its name, prefix (for example `iq_EXAMPLEdo…`), scopes, created date, expiry date, last used date ("Never used" if it has not been used) and status: **Active**, **Expired** or **Revoked**. The page also shows how many of the 20 active keys are in use and disables **Create API key** at the limit.
- **Revoke a key:** choose **Revoke** on an active key and confirm. The dialog names the key and its prefix and warns that the key stops working immediately, that any integration using it loses access, and that revoking cannot be undone.

### Key management endpoints

The Developers page uses these endpoints. They authenticate with the app's session cookie, require the owner or admin role, and are not callable with an API key.

| Method and path | Purpose |
| --- | --- |
| `GET /api/developer/keys` | List all of the organization's keys, newest first, including revoked and expired keys |
| `POST /api/developer/keys` | Create a key and return the secret once |
| `DELETE /api/developer/keys/{id}` | Revoke a key |

`POST` and `DELETE` reject requests whose `Origin` header is present and differs from the app's own origin (`403 forbidden`).

`POST` also requires a paid plan and returns `403 upgrade_required` for Free organizations. `GET` and `DELETE` do not check the plan, so keys can still be listed and revoked after a downgrade, on the Developers page or through these endpoints.

### Create a key

Request body (`Content-Type: application/json`, unknown fields rejected):

| Field | Type | Rules |
| --- | --- | --- |
| `name` | string | Required, 1 to 80 characters after trimming |
| `scopes` | string array | Required, 1 to 5 unique values from the scope table |
| `expiresAt` | string | Optional ISO 8601 date-time with `Z` or an offset, in the future and at most 365 days ahead. Default: 90 days from now |

Limits on creation:

- At most **20 active keys** per organization (not revoked and not expired). Creating a 21st returns `409 api_key_limit`.
- At most **20 key creations per user per organization per clock hour**. More returns `429 rate_limited` with `Retry-After`.

Response `201 Created`:

```json
{
  "data": {
    "id": "00000000-0000-4000-8000-00000000a001",
    "name": "Zapier polling",
    "prefix": "iq_EXAMPLEdo",
    "scopes": ["clients:read", "invoices:read"],
    "expiresAt": "2027-01-26T10:00:00.000Z",
    "revokedAt": null,
    "lastUsedAt": null,
    "createdAt": "2026-10-28T10:00:00.000Z",
    "key": "iq_EXAMPLEdoNotUseThisKey0000000000000000000xy"
  }
}
```

The `key` field appears only in this response. InvoiceQuickly stores a SHA-256 hash of the key, so a lost key cannot be recovered; revoke it and create a new one.

`GET /api/developer/keys` returns `{ "data": [ ... ] }` with the same fields minus `key`.

### Revoke a key

`DELETE /api/developer/keys/{id}` returns `200` with `{ "data": { "id": "...", "revokedAt": "..." } }`. Revoking an already revoked key returns its original `revokedAt` and changes nothing. An unknown ID, or a key from another organization, returns `404 key_not_found`.

## Rate limits

Each API key may make **60 requests per clock minute**. Windows are fixed and aligned to the minute (for example 10:00:00 to 10:00:59), not rolling.

| Limit | Counted per | Applies | When exceeded |
| --- | --- | --- | --- |
| 120 requests per clock minute | Client IP (first `X-Forwarded-For` entry, else `X-Real-IP`) | Every public API request, before the key is checked | `429 rate_limited`, "Too many requests. Try again shortly." |
| 60 requests per clock minute | API key | After the key, scope and role checks pass | `429 rate_limited`, "API key rate limit reached." |
| 20 key creations per clock hour | User and organization | `POST /api/developer/keys` | `429 rate_limited` |
| 10 AI invoice drafts per clock minute | Organization, shared with AI invoice drafting in the dashboard | `POST /invoices/ai-draft`, after the checks above | `429 rate_limited`, "AI invoice draft rate limit reached." |

Rules worth knowing:

- Rejected requests still count. A request that gets `429` uses up a slot in the same window.
- Successful responses include `X-RateLimit-Limit` (60) and `X-RateLimit-Remaining`. Error responses do not include these two headers.
- `429` responses include `Retry-After` with the number of seconds until the current window ends (at least 1).
- Because windows are fixed, up to 120 requests from one key can succeed across a minute boundary. Do not rely on that; spread requests out.

## Requests, responses and headers

- **Request bodies** must be JSON with `Content-Type: application/json` (a `charset` parameter is fine). Other content types return `415 unsupported_media_type`. Invalid JSON or invalid UTF-8 returns `400 invalid_json`.
- **Body size** is capped at 128 KiB (131,072 bytes). Larger bodies return `413 body_too_large`.
- **Unknown fields** in request bodies and unknown query parameters are rejected with `400 invalid_request`.
- **Single records** are wrapped as `{ "data": { ... } }`. Lists are `{ "data": [ ... ], "pagination": { ... } }`.
- **Money and rates** are decimal strings with two decimal places, such as `"250.00"` and `"8.00"`. Parse them as decimals, not floats. The one exception is an AI proposal from `POST /invoices/ai-draft`, which uses JSON numbers because nothing has been calculated or saved yet.
- **Timestamps** are ISO 8601 strings in UTC, such as `"2026-10-28T10:00:00.000Z"`.
- **Caching:** every response has `Cache-Control: no-store`.

| Response header | When |
| --- | --- |
| `Cache-Control: no-store` | Always |
| `X-RateLimit-Limit`, `X-RateLimit-Remaining` | Successful responses |
| `Idempotent-Replayed: true` or `false` | Successful `POST` responses |
| `X-Request-Id` | Error responses (same value as `error.requestId`) |
| `Retry-After` | `429` responses |

## Pagination and filtering

List endpoints return records newest first (by `createdAt`, then `id`) and use an opaque cursor.

| Query parameter | Type | Rules |
| --- | --- | --- |
| `limit` | integer | 1 to 100, default 25 |
| `cursor` | string | The `nextCursor` value from the previous page. Opaque; do not build or edit it |
| `createdAfter` | string | ISO 8601 date-time with `Z` or an offset. Returns only records created strictly after this time |
| `email` | string | `GET /clients` only. Exact, case-insensitive match on the client's email |

Any other parameter (such as `page`, `offset` or `status`) returns `400 invalid_request`. A malformed or tampered cursor returns `400 invalid_cursor`. Passing `email` to `/invoices` or `/payments` returns `400 invalid_request`.

Response shape:

```json
{
  "data": [ { "id": "..." } ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "eyJpZCI6IjAwMDAwMDAwLTAwMDAtNDAwMC04MDAwLTAwMDAwMDAwMDEwMSIsImNyZWF0ZWRBdCI6IjIwMjYtMTAtMjdUMDk6MTU6MDAuMDAwWiJ9"
  }
}
```

When `hasMore` is `false`, `nextCursor` is `null`. To read everything, keep requesting with `cursor` set to the last `nextCursor` until `hasMore` is `false`. You can combine `cursor` with `createdAfter` and `limit`; keep the same filters on every page.

## Idempotent POST requests

Every `POST` to `/clients`, `/invoices` and `/invoices/ai-draft` **must** include an `Idempotency-Key` header. Retrying with the same key and the same body returns the original result instead of creating a duplicate or asking the AI again.

| Rule | Behaviour |
| --- | --- |
| Required | Missing or invalid header returns `400 idempotency_key_required` |
| Format | 1 to 128 characters from `A-Z`, `a-z`, `0-9`, `.`, `_`, `:` and `-` (no spaces) |
| Scope | Unique per organization and endpoint. Two API keys in the same organization share the key space |
| Retention | 24 hours from the first request that used the key |
| Same key, same body, within 24 hours | Returns the stored response (`201`, or `200` for `/invoices/ai-draft`) with `Idempotent-Replayed: true` |
| Same key, different body, within 24 hours | `409 idempotency_conflict` |
| Concurrent requests with the same key | Processed one at a time. The first one runs; the others wait and replay its result |
| The request fails | Nothing is stored for the key, so you can retry with the same key |
| Same key after 24 hours | Treated as new and creates another record |

"Same body" is compared after validation and normalization: field order, surrounding whitespace, currency letter case and omitted defaults do not make two bodies different. Replays still need a valid key with the right scope, a valid body, and count toward the rate limit.

Use one key per logical operation, for example `zap-8812:invoice:2026-10-28-001`, and reuse it only for retries of that operation.

## Endpoints

| Method | Path | Scope | Purpose |
| --- | --- | --- | --- |
| `GET` | `/me` | Any valid key | Check a key and see its organization and scopes |
| `GET` | `/clients` | `clients:read` | List clients |
| `POST` | `/clients` | `clients:write` | Create a client |
| `GET` | `/clients/{id}` | `clients:read` | Get one client |
| `GET` | `/invoices` | `invoices:read` | List invoices |
| `POST` | `/invoices` | `invoices:write` | Create a draft invoice |
| `POST` | `/invoices/ai-draft` | `invoices:write` | Get an AI invoice proposal for review (nothing is saved) |
| `GET` | `/invoices/{id}` | `invoices:read` | Get one invoice with line items |
| `GET` | `/payments` | `payments:read` | List successful payments |

No other methods exist. There is no update or delete for clients or invoices, no way to send an invoice, no way to charge a client, and no way to record a payment through this API.

### GET /me

Returns the key's organization and scopes. Use it to test a key.

```bash
curl -s "$IQ_API/me" -H "Authorization: Bearer $IQ_API_KEY"
```

```json
{
  "data": {
    "organization": { "id": "00000000-0000-4000-8000-0000000000a1", "name": "Example Studio" },
    "scopes": ["clients:read", "invoices:read"],
    "apiVersion": "v1"
  }
}
```

Status codes: `200`, `401`, `403`, `404` (API disabled), `429`.

### GET /clients

Lists the organization's clients, newest first. Supports `limit`, `cursor`, `createdAfter` and `email`.

```bash
curl -s "$IQ_API/clients?limit=2&email=ada@example.com" \
  -H "Authorization: Bearer $IQ_API_KEY"
```

```json
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000101",
      "name": "Ada Example",
      "email": "ada@example.com",
      "phone": null,
      "company": "Example Labs",
      "address": "1 Example Street",
      "city": "Exampleton",
      "state": null,
      "zip": "00000",
      "country": "US",
      "taxId": null,
      "notes": null,
      "createdAt": "2026-10-27T09:15:00.000Z",
      "updatedAt": "2026-10-27T09:15:00.000Z"
    }
  ],
  "pagination": { "hasMore": false, "nextCursor": null }
}
```

Status codes: `200`, `400`, `401`, `403`, `404` (API disabled), `429`.

### POST /clients

Creates a client. Requires `Idempotency-Key`.

| Field | Type | Rules |
| --- | --- | --- |
| `name` | string | Required, 1 to 200 characters after trimming |
| `email` | string | Optional, valid email or `""` |
| `phone` | string | Optional, up to 50 characters |
| `company` | string | Optional, up to 200 characters |
| `address` | string | Optional, up to 500 characters |
| `city` | string | Optional, up to 100 characters |
| `state` | string | Optional, up to 100 characters |
| `zip` | string | Optional, up to 20 characters |
| `country` | string | Optional, up to 100 characters |
| `taxId` | string | Optional, up to 100 characters |
| `notes` | string | Optional, up to 2,000 characters |

Strings are trimmed. Empty optional strings are stored as `null`. Any other field returns `400 invalid_request`. Client email is not required to be unique; use `GET /clients?email=` first if you want to avoid duplicates. If the organization's plan client limit is reached, the request returns `403 client_limit_reached`.

```bash
curl -s -X POST "$IQ_API/clients" \
  -H "Authorization: Bearer $IQ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-sync:client:ada-example" \
  -d '{"name":"Ada Example","email":"ada@example.com","company":"Example Labs","country":"US"}'
```

Response `201 Created` with `Idempotent-Replayed: false` (or `true` on a replay):

```json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000102",
    "name": "Ada Example",
    "email": "ada@example.com",
    "phone": null,
    "company": "Example Labs",
    "address": null,
    "city": null,
    "state": null,
    "zip": null,
    "country": "US",
    "taxId": null,
    "notes": null,
    "createdAt": "2026-10-28T10:00:00.000Z",
    "updatedAt": "2026-10-28T10:00:00.000Z"
  }
}
```

Status codes: `201`, `400`, `401`, `403`, `404` (API disabled), `409`, `413`, `415`, `429`.

### GET /clients/{id}

Returns one client. `{id}` must be a UUID; anything else returns `400 invalid_request`. A client that does not exist or belongs to another organization returns `404 client_not_found`.

```bash
curl -s "$IQ_API/clients/00000000-0000-4000-8000-000000000102" \
  -H "Authorization: Bearer $IQ_API_KEY"
```

Response `200`: `{ "data": { ...client } }` with the same fields as `POST /clients`.

Status codes: `200`, `400`, `401`, `403`, `404`, `429`.

### GET /invoices

Lists the organization's invoices, newest first, in every status. Estimates and credit notes are not included. List items do not include line items; use `GET /invoices/{id}` for those. Supports `limit`, `cursor` and `createdAfter`.

```bash
curl -s "$IQ_API/invoices?createdAfter=2026-10-01T00:00:00Z&limit=25" \
  -H "Authorization: Bearer $IQ_API_KEY"
```

```json
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000201",
      "number": "INV-0042",
      "documentType": "invoice",
      "clientId": "00000000-0000-4000-8000-000000000102",
      "status": "sent",
      "issueDate": "2026-10-20T00:00:00.000Z",
      "dueDate": "2026-11-19T00:00:00.000Z",
      "currency": "USD",
      "subtotal": "300.00",
      "discountRate": "10.00",
      "discountAmount": "30.00",
      "taxRate": "8.00",
      "taxAmount": "21.60",
      "total": "291.60",
      "amountPaid": "0.00",
      "notes": null,
      "terms": "Payment due in 30 days.",
      "toName": "Ada Example",
      "toEmail": "ada@example.com",
      "toAddress": null,
      "createdAt": "2026-10-20T08:30:00.000Z",
      "updatedAt": "2026-10-21T12:00:00.000Z"
    }
  ],
  "pagination": { "hasMore": false, "nextCursor": null }
}
```

`status` is a string set by the app, for example `draft`, `sent`, `viewed`, `paid`, `overdue` or `cancelled`. `number` uses the organization's invoice prefix and next number.

Status codes: `200`, `400`, `401`, `403`, `404` (API disabled), `429`.

### POST /invoices

Creates a **draft** invoice. It never sends email and never creates estimates or credit notes. Requires `Idempotency-Key`.

| Field | Type | Rules |
| --- | --- | --- |
| `items` | array | Required, 1 to 100 line items |
| `items[].description` | string | Required, 1 to 1,000 characters after trimming |
| `items[].quantity` | number | Required, greater than 0, at most 1,000,000 |
| `items[].unitPrice` | number | Required, 0 to 1,000,000,000 |
| `clientId` | UUID or `null` | Optional. Must be a client in your organization, else `404 client_not_found` |
| `issueDate` | string | Optional date `YYYY-MM-DD`. Default: the time of creation |
| `dueDate` | string | Optional date `YYYY-MM-DD`, not before `issueDate`. Default: none (`null`) |
| `currency` | string | Optional three-letter code, stored in upper case. Default `USD` |
| `taxRate` | number | Optional percentage 0 to 100. Default 0 |
| `discountRate` | number | Optional percentage 0 to 100. Default 0 |
| `notes` | string | Optional, up to 5,000 characters |
| `terms` | string | Optional, up to 5,000 characters |
| `fromName` | string | Optional, up to 200 characters. Default: organization name |
| `fromEmail` | string | Optional email or `""`. Default: organization email |
| `fromAddress` | string | Optional, up to 1,000 characters. Default: organization address |
| `toName` | string | Optional, up to 200 characters |
| `toEmail` | string | Optional email or `""` |
| `toAddress` | string | Optional, up to 1,000 characters |
| `sourceDocumentId` | UUID or `null` | Optional. Must be a document in your organization, else `404 source_not_found` |
| `status` | string | Optional. Only `"draft"` is accepted |
| `documentType` | string | Optional. Only `"invoice"` is accepted |

Numbers may also be sent as numeric strings such as `"2.5"`. Any other field, including `number`, `subtotal`, `total`, `amountPaid` or `organizationId`, returns `400 invalid_request`. `status: "sent"` or any `documentType` other than `"invoice"` also returns `400 invalid_request`.

**Totals are computed on the server** from the line items and rates. Any totals you have in your own system are not used.

1. Line `amount` = `quantity` x `unitPrice`
2. `subtotal` = sum of line amounts
3. `discountAmount` = `subtotal` x `discountRate` / 100
4. `taxAmount` = (`subtotal` - `discountAmount`) x `taxRate` / 100
5. `total` = `subtotal` - `discountAmount` + `taxAmount`

Each stored value is rounded to two decimal places, including `quantity` and `unitPrice`. Send quantities and prices with at most two decimals so the stored line values match what you sent. If any amount would exceed 9,999,999,999.99, the request returns `400 invalid_amount`.

**Client linking:** when `clientId` is omitted and `toEmail` or `toName` is given, the invoice is linked to an existing client with the same email (case-insensitive), or the same name if no email is given. If none matches, a new client is created from `toName`, `toEmail` and `toAddress`, which counts toward the plan's client limit (`403 client_limit_reached`). If the plan's invoice limit is reached, the request returns `403 invoice_limit_reached`.

```bash
curl -s -X POST "$IQ_API/invoices" \
  -H "Authorization: Bearer $IQ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: zap-8812:invoice:2026-10-28-001" \
  -d '{
    "clientId": "00000000-0000-4000-8000-000000000102",
    "issueDate": "2026-10-28",
    "dueDate": "2026-11-27",
    "currency": "usd",
    "discountRate": 10,
    "taxRate": 8,
    "items": [
      { "description": "Design work", "quantity": 2.5, "unitPrice": 100 },
      { "description": "Hosting", "quantity": 1, "unitPrice": 50 }
    ]
  }'
```

Response `201 Created`:

```json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000202",
    "number": "INV-0043",
    "documentType": "invoice",
    "clientId": "00000000-0000-4000-8000-000000000102",
    "status": "draft",
    "issueDate": "2026-10-28T00:00:00.000Z",
    "dueDate": "2026-11-27T00:00:00.000Z",
    "currency": "USD",
    "subtotal": "300.00",
    "discountRate": "10.00",
    "discountAmount": "30.00",
    "taxRate": "8.00",
    "taxAmount": "21.60",
    "total": "291.60",
    "amountPaid": "0.00",
    "notes": null,
    "terms": null,
    "toName": null,
    "toEmail": null,
    "toAddress": null,
    "createdAt": "2026-10-28T10:05:00.000Z",
    "updatedAt": "2026-10-28T10:05:00.000Z",
    "items": [
      { "id": "00000000-0000-4000-8000-000000000301", "description": "Design work", "quantity": "2.50", "unitPrice": "100.00", "amount": "250.00", "sortOrder": 0 },
      { "id": "00000000-0000-4000-8000-000000000302", "description": "Hosting", "quantity": "1.00", "unitPrice": "50.00", "amount": "50.00", "sortOrder": 1 }
    ]
  }
}
```

`fromName`, `fromEmail` and `fromAddress` are saved on the invoice but are not returned by the API.

Status codes: `201`, `400`, `401`, `403`, `404`, `409`, `413`, `415`, `429`.

### POST /invoices/ai-draft

Turns a plain-text description of work into a proposed invoice for a person to review. **It only proposes.** It never saves an invoice or client, never sends anything, and never charges anyone. To create the invoice, review the proposal, correct it, and send the reviewed fields to [`POST /invoices`](#post-invoices).

- **Scope:** `invoices:write`. The key's creator needs a role that can create records (owner, admin or member).
- **Plan:** a paid plan, like every `/api/v1` endpoint.
- **`Idempotency-Key`:** required. A retry with the same key and body within 24 hours returns the same proposal, with the same `proposalId`, without asking the AI again.
- **Usage:** each new proposal counts as one invoice AI draft, the same allowance used by AI drafts in the dashboard. It does not use premium AI operations. Replays do not count.

Request body (`Content-Type: application/json`, unknown fields rejected):

| Field | Type | Rules |
| --- | --- | --- |
| `prompt` | string | Required. 10 to 5,000 characters after trimming. Describe the client, the work and any prices you know |
| `currency` | string | Optional three-letter code, stored in upper case. Default `USD` |

The prompt is sent to OpenAI to write the proposal. Don't include passwords, card numbers or other secrets in it.

```bash
curl -s -X POST "$IQ_API/invoices/ai-draft" \
  -H "Authorization: Bearer $IQ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-sync:proposal:job-5521" \
  -d '{
    "prompt": "Invoice Example Labs (ada@example.com) for 6 hours of design work at 80 an hour, plus one hosting setup. Due in 30 days.",
    "currency": "usd"
  }'
```

Response `200 OK` with `Idempotent-Replayed: false` (or `true` on a replay):

```json
{
  "data": {
    "proposalId": "00000000-0000-4000-8000-00000000b001",
    "saved": false,
    "requiresReview": true,
    "invoice": {
      "toName": "Example Labs",
      "toEmail": "ada@example.com",
      "dueDate": "2026-11-27",
      "items": [
        { "description": "Design work", "quantity": 6, "unitPrice": 80 },
        { "description": "Hosting setup", "quantity": 1, "unitPrice": 0 }
      ],
      "taxRate": 0,
      "discountRate": 0,
      "notes": "",
      "terms": "Payment due in 30 days.",
      "missingFields": [],
      "confidence": 0.8,
      "currency": "USD",
      "fromName": "Example Studio",
      "fromEmail": "billing@example.com",
      "fromAddress": "1 Example Street, Exampleton, 00000"
    }
  }
}
```

| Field | Meaning |
| --- | --- |
| `proposalId` | A random ID for this proposal. It does not refer to any saved record and cannot be looked up later |
| `saved` | Always `false`. Nothing was created in the organization |
| `requiresReview` | Always `true`. A person must check every field before an invoice is created from it |
| `invoice.toName`, `invoice.toEmail` | The client the AI found in the prompt, or `""`. If the AI leaves the email empty, the server uses the first email address in the prompt when it is valid |
| `invoice.dueDate` | A date suggested by the AI, or `null`. Check that it is a real `YYYY-MM-DD` date before you send it to `POST /invoices` |
| `invoice.items` | 1 to 100 lines with `description`, `quantity` and `unitPrice`. Numbers are JSON numbers here, not decimal strings |
| `invoice.taxRate`, `invoice.discountRate` | Percentages from 0 to 100. Default 0 |
| `invoice.notes`, `invoice.terms` | Text from the prompt, or `""` |
| `invoice.missingFields` | Any of `client`, `clientEmail`, `amount` and `dueDate`, recalculated by the server from the values above |
| `invoice.confidence` | The AI's own estimate from 0 to 1 (0.5 if it gives none). It is not a check of accuracy |
| `invoice.currency` | The currency from the request |
| `invoice.fromName`, `invoice.fromEmail`, `invoice.fromAddress` | Your organization's name, email (or `""`) and address, copied from its settings |

There are no totals. The server calculates `subtotal`, tax, discount and `total` only when you create the invoice with `POST /invoices`.

**Unknown rates are 0 and must be reviewed.** The AI is told to use `0` for any price the prompt does not give and not to invent rates. In the example, "Hosting setup" has no price in the prompt, so its `unitPrice` is `0`. A zero line is easy to miss:

- `missingFields` lists `amount` only when **no** line has a price. In the example one line has a price, so `missingFields` is empty even though "Hosting setup" is `0`. Check every line's `unitPrice`.
- `POST /invoices` accepts a `unitPrice` of `0`, so an unreviewed zero line would be saved as a free line.
- Treat prices the AI did fill in as suggestions too, and confirm them against your own rates.

To create the invoice after review, send `toName`, `toEmail`, `dueDate`, `items`, `taxRate`, `discountRate`, `notes`, `terms`, `currency` and, if you want, the `from` fields to `POST /invoices`. Leave out `proposalId`, `saved`, `requiresReview`, `missingFields` and `confidence`; `POST /invoices` rejects unknown fields.

Errors specific to this endpoint, checked after authentication, the plan, scope and role, `Idempotency-Key` and body validation:

| Status | `code` | Meaning | What to do |
| --- | --- | --- | --- |
| 429 | `rate_limited` | More than 10 AI drafts in this clock minute for the organization | Wait `Retry-After` seconds, then retry with the same `Idempotency-Key` |
| 403 | `ai_draft_limit_reached` | The plan's invoice AI draft allowance is used up | Don't retry. Create the invoice with `POST /invoices` instead |
| 503 | `ai_not_configured` | AI drafting is not configured on this server | Don't retry. Contact the server operator |
| 502 | `ai_unavailable` | The AI service failed or took longer than 20 seconds | Retry later with the same `Idempotency-Key` |
| 502 | `invalid_ai_response` | The AI returned an empty proposal, invalid JSON, or values outside the allowed limits | Retry, or reword the prompt with clearer items and prices |

After any of these errors nothing is stored for the `Idempotency-Key`, so a retry with the same key asks the AI again.

Status codes: `200`, `400`, `401`, `403`, `404` (API disabled), `409`, `413`, `415`, `429`, `502`, `503`.

### GET /invoices/{id}

Returns one invoice with its line items in `items`. Sort items by `sortOrder`. `{id}` must be a UUID (else `400 invalid_request`). An invoice that does not exist, belongs to another organization, or is an estimate or credit note returns `404 invoice_not_found`.

```bash
curl -s "$IQ_API/invoices/00000000-0000-4000-8000-000000000202" \
  -H "Authorization: Bearer $IQ_API_KEY"
```

Response `200`: `{ "data": { ...invoice, "items": [ ... ] } }`, the same shape as the `POST /invoices` response.

Status codes: `200`, `400`, `401`, `403`, `404`, `429`.

### GET /payments

Lists payments with status `succeeded` on the organization's invoices, newest first by when the payment was recorded. Supports `limit`, `cursor` and `createdAfter`; there are no other filters. A payment that is later fully or partially refunded changes status and no longer appears in this list.

```bash
curl -s "$IQ_API/payments?limit=50" -H "Authorization: Bearer $IQ_API_KEY"
```

```json
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000401",
      "invoiceId": "00000000-0000-4000-8000-000000000201",
      "invoiceNumber": "INV-0042",
      "amount": "100.00",
      "refundedAmount": "0.00",
      "currency": "USD",
      "status": "succeeded",
      "method": "bank_transfer",
      "reference": "Example transfer 0001",
      "paidAt": "2026-10-26T14:00:00.000Z",
      "createdAt": "2026-10-26T14:01:00.000Z"
    }
  ],
  "pagination": { "hasMore": false, "nextCursor": null }
}
```

`currency` comes from the invoice. `method` is a string such as `bank_transfer`, `card`, `cash`, `check` or `other`. `paidAt` is when the payment was made; `createdAt` (used for ordering and `createdAfter`) is when it was recorded.

Status codes: `200`, `400`, `401`, `403`, `404` (API disabled), `429`.

## Errors

Every error uses the same JSON shape and sets `X-Request-Id` to the `requestId`:

```json
{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key requires the invoices:write scope.",
    "requestId": "00000000-0000-4000-8000-00000000e001"
  }
}
```

Validation errors add `details`, one entry per problem, with a dotted `path`:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed.",
    "details": [
      { "path": "items.0.quantity", "message": "Quantity must be greater than zero." },
      { "path": "dueDate", "message": "Due date cannot be before issue date." }
    ],
    "requestId": "00000000-0000-4000-8000-00000000e002"
  }
}
```

Branch on `code`, not on `message`; messages may change.

| Status | `code` | Meaning |
| --- | --- | --- |
| 400 | `invalid_request` | Body, query or path ID failed validation (see `details`), or `email` was used outside `/clients` |
| 400 | `invalid_json` | Body missing, not valid JSON, or not valid UTF-8 |
| 400 | `invalid_cursor` | `cursor` is malformed or was altered |
| 400 | `idempotency_key_required` | `POST` without a valid `Idempotency-Key` header |
| 400 | `invalid_amount` | An invoice amount exceeds 9,999,999,999.99 |
| 400 | `invalid_expiry` | Key management: `expiresAt` is in the past or more than 365 days ahead |
| 401 | `unauthorized` | Missing or malformed Bearer header; unknown, expired or revoked key; creator no longer in the organization. Key management: not signed in |
| 403 | `insufficient_scope` | The key lacks the scope this endpoint needs |
| 403 | `forbidden` | The key creator's current role cannot perform this action. Key management: not owner or admin, or cross-origin request |
| 403 | `organization_required` | Key management: the signed-in user has no organization |
| 403 | `upgrade_required` | The organization is on the Free plan. Checked on every request: API calls and key creation need a paid plan (Pro and above). Listing and revoking keys still work |
| 403 | `ai_draft_limit_reached` | `POST /invoices/ai-draft`: the plan's invoice AI draft allowance is used up |
| 403 | `client_limit_reached` | The plan's client limit is reached |
| 403 | `invoice_limit_reached` | The plan's invoice limit is reached |
| 404 | `not_found` | The public API is disabled on this server |
| 404 | `client_not_found` | Client does not exist in this organization |
| 404 | `invoice_not_found` | Invoice does not exist in this organization |
| 404 | `source_not_found` | `sourceDocumentId` does not exist in this organization |
| 404 | `key_not_found` | Key management: key does not exist in this organization |
| 409 | `idempotency_conflict` | `Idempotency-Key` was already used with a different body in the last 24 hours |
| 409 | `api_key_limit` | Key management: the organization already has 20 active keys |
| 413 | `body_too_large` | Body exceeds 128 KiB |
| 415 | `unsupported_media_type` | `Content-Type` is not `application/json` |
| 429 | `rate_limited` | A rate limit was exceeded, including the AI draft limit; wait `Retry-After` seconds |
| 500 | `internal_error` | Unexpected server error; retry later and quote the `requestId` |
| 502 | `ai_unavailable` | `POST /invoices/ai-draft`: the AI service failed or timed out; retry later |
| 502 | `invalid_ai_response` | `POST /invoices/ai-draft`: the AI's proposal was empty or failed validation; retry or reword the prompt |
| 503 | `ai_not_configured` | `POST /invoices/ai-draft`: AI drafting is not configured on this server |

Unknown paths and unsupported methods under `/api/v1` get the framework's default `404` or `405` response, not this JSON shape.

## Security notes

- **Treat keys like passwords.** Keep them in a secrets manager or your automation tool's credential store. Never put them in client-side code, URLs, logs or version control.
- **Keys cannot be recovered.** InvoiceQuickly stores only a SHA-256 hash of each key. If you lose one, revoke it and create a new one.
- **Use least privilege.** Give each integration its own key with only the scopes it needs. A polling job that only reads invoices needs only `invoices:read`. There is no proposal-only scope: `invoices:write` allows both AI proposals and draft invoices.
- **Rotate without downtime.** Create the new key, switch your integration to it, confirm it works with `GET /me`, then revoke the old key. Revocation is immediate.
- **Set short expiries** for experiments. Keys expire after 90 days by default and can never last more than 365 days.
- **Watch the last used date** (`lastUsedAt`) in the Developers page key list to find unused keys and revoke them.
- **Remember the creator link.** If the person who created a key leaves the organization, the key stops working. Plan rotations before offboarding.

## Using the API with automation tools

Any tool that can send HTTP requests with custom headers can use this API with your own key. Examples include Webhooks by Zapier, the HTTP modules in Make, and the HTTP Request node in n8n. Set the `Authorization: Bearer` header from the tool's credential storage and, for `POST`, add `Content-Type: application/json` and an `Idempotency-Key` built from a stable ID in the triggering record so retries do not create duplicates.

InvoiceQuickly also has a Zapier integration that works today through a private invite link, described in [Zapier integration (private)](#zapier-integration-private). It is not listed in Zapier's public app directory while Zapier's public review is pending. Without accepting the invite, use Webhooks by Zapier as described above. No other app marketplace lists InvoiceQuickly, and this API does not sync data with accounting or time-tracking tools on its own.

InvoiceQuickly does not send outbound webhooks or triggers from this API. To detect new records, poll a list endpoint on a schedule:

1. Store the `createdAt` of the newest record you have processed.
2. Call the list endpoint with `createdAfter` set to that value.
3. Follow `pagination.nextCursor` until `hasMore` is `false`, keeping the same `createdAfter`.
4. Process the records, then save the newest `createdAt` you saw.

Results are newest first, so collect all pages before you move your saved `createdAt` forward. Polling every few minutes stays well within the 60 requests per minute limit.

To have AI suggest an invoice from an automation, call `POST /invoices/ai-draft`, send the proposal to a person (for example by email or a chat message), and create the invoice with `POST /invoices` only after they approve it. Don't chain the proposal straight into `POST /invoices`: the AI is told to use `0` for prices the prompt didn't give, and every price it fills in is only a suggestion.

### Zapier integration (private)

InvoiceQuickly has a Zapier integration that organizations on a paid plan can use today. To get it, sign in to Zapier and accept the private invite at <https://zapier.com/developer/public-invite/248713/4b2160342981ef600cc2eee3f62e83fd/>; the app then appears as InvoiceQuickly in the Zap editor. It is not listed in Zapier's public app directory while Zapier's public review is pending.

It calls the live public API at `https://invoicequickly.com/api/v1` with an API key from the **Developers** page, so it works only for organizations on a paid plan. This section describes what the integration (`integrations/zapier`, version 0.0.0) does. Changes are recorded in the [Changelog](#changelog).

It is built only on the endpoints on this page:

| Integration item | Type | API call | Scope needed |
| --- | --- | --- | --- |
| Connect with an **API Key** | Authentication | `GET /me`, shown as the organization name | Any |
| New Client | Polling trigger | `GET /clients?limit=100` | `clients:read` |
| New Invoice | Polling trigger | `GET /invoices?limit=100` | `invoices:read` |
| New Payment | Polling trigger | `GET /payments?limit=100` | `payments:read` |
| Find Client | Search, by email | `GET /clients?limit=100&email=` | `clients:read` |
| Create Client | Action | `POST /clients` | `clients:write` |
| Create Draft Invoice | Action | `POST /invoices` with `status: "draft"` | `invoices:write` |
| Generate AI Invoice Proposal | Action | `POST /invoices/ai-draft`, returns the whole proposal | `invoices:write` |

What each item does:

- **Triggers:** each poll reads the newest 100 records, newest first, and returns them with their `id`, which Zapier uses to tell new records from ones it has already seen. New Invoice covers invoices in any status, but not estimates or credit notes, and New Payment covers successful payments, as the list endpoints do. Later pages, with `pagination.nextCursor`, are read only when Zapier asks for more, for example in the **Client ID** dropdown of Create Draft Invoice.
- **Find Client:** an exact, case-insensitive match on the email address. It returns the matching clients, up to 100 and newest first, because client email is not unique.
- **Create Client:** sends name (required), email, company, phone and notes. Empty fields are left out.
- **Create Draft Invoice:** always sends `status: "draft"` and `documentType: "invoice"`, whatever the Zap maps, so it never sends an invoice, emails a client or charges anyone. Fields: Client ID, client name and email, currency (required, default `USD`), issue and due dates (`YYYY-MM-DD`), line items (description, quantity and unit price), tax and discount rates, and notes. Empty fields are left out, so the API's defaults apply, and the server calculates the totals.
- **Generate AI Invoice Proposal:** sends the **Work Description** as `prompt` and a currency (required in Zapier, default `USD`) to `POST /invoices/ai-draft`. It returns `proposalId`, `saved: false`, `requiresReview: true` and the proposed `invoice`. It never saves the proposal: no invoice, client or line item is created, and nothing is sent or charged. The only thing recorded is usage: each new proposal counts as one invoice AI draft for the organization, and replays don't. The AI is told to use `0` for prices the description didn't give, so check every price. To bill from a proposal, add a step where a person reviews it, and only then a Create Draft Invoice step with the approved values.
- **Source Record ID (`sourceRecordKey`):** required on all three actions and never sent to the API as a field. The integration trims it, hashes it with SHA-256 and sends `zapier:<action>:<hex hash>` as the `Idempotency-Key`, where `<action>` is `client`, `invoice` or `ai-proposal`. Map it to a stable ID from the triggering record, such as the source app's record ID:
  - The same ID with the same fields within 24 hours replays the first result: no duplicate client or invoice, and for a proposal the same `proposalId` without asking the AI again.
  - The same ID with different fields within 24 hours fails with `409 idempotency_conflict`.
  - After 24 hours, the same ID creates a new record.
  - Because the action name is part of the key, one ID can be used in both a proposal step and a Create Draft Invoice step without one replaying the other.
  - An empty or blank ID, or one longer than 1,024 characters, fails the step before any request is sent.
- **Errors:** a `401` asks you to reconnect the account, and a `429` tells Zapier to wait for `Retry-After` seconds (60 if the header is missing). Other errors, such as `403 upgrade_required`, fail the step with the API's error.

## Changelog

- **2026-10-29:** The API is live in production at `https://invoicequickly.com/api/v1` for paid plans. The Zapier integration works through a private invite link; Zapier's public directory review is pending. Updated the status and Zapier wording only; endpoints, scopes, limits and errors are unchanged.
- **2026-10-28:** Updated the Zapier section. A private Zapier integration exists. It is not listed in the Zapier app directory and is not publicly available; access, if offered, is by invitation, and public availability depends on Zapier's review.
- **2026-10-28:** Added `POST /invoices/ai-draft` (scope `invoices:write`) for AI invoice proposals that are never saved, sent or charged. New error codes: `ai_draft_limit_reached`, `ai_unavailable`, `invalid_ai_response` and `ai_not_configured`. Documented the unpublished Zapier connector.
- **2026-10-28:** The paid-plan check runs on every request. Listing and revoking keys keep working after a downgrade, and the Developers page keeps the key list visible on Free.
- **2026-10-28:** API access requires a paid plan (Pro and above). Free organizations get `403 upgrade_required` on `/api/v1` and when creating keys.
- **2026-10-28:** Pre-release v1. API keys with scopes and expiry, clients (list, get, create), invoices (list, get, create draft), payments (list), cursor pagination, idempotent `POST` requests and per-key rate limits. Disabled unless `PUBLIC_API_ENABLED` is `"true"`.
