> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hocdoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Read the offers of one HocDoc workspace and their timelines, and create, send and withdraw offers, over a JSON API.

## What the API offers

The HocDoc API gives your own systems access to the offers of one workspace. Use it to show the state of your offers in a CRM, a report or an automation tool, or to create and send offers from your own system.

Every key reads. A key with the permission **Read and write** also creates offers from templates, sends drafts and withdraws offers. The API cannot edit or delete offers.

These resources exist:

| Resource | Path | Content |
| - | - | - |
| Workspace | `GET /workspace` | The workspace the API key belongs to. Use it to check that a key works. |
| Offers | `GET /offers` | A paginated list of offers, newest first. Filter by `status`. |
| Offer | `GET /offers/{id}` | One offer. |
| Offer events | `GET /offers/{id}/events` | The timeline of one offer, oldest event first. |
| Files of an offer | `GET /offers/{id}/files` | The files the recipient uploaded with the onboarding form, oldest first. |
| One file | `GET /offers/{id}/files/{fileId}` | Redirects (`302`) to a link that is valid for 60 seconds. |
| Create an offer | `POST /offers` | Creates a draft from a template. Needs write permission. |
| Send an offer | `POST /offers/{id}/send` | Sends a draft. Needs write permission. |
| Withdraw an offer | `POST /offers/{id}/withdraw` | Withdraws a sent offer. Needs write permission. |

See the endpoint reference in the sidebar for every parameter and response.

## Base URL and versioning

All paths are relative to this base URL:

```text theme={null}
https://app.hocdoc.com/api/v1
```

The app shows the base URL too: open **Settings**, then the **Integrations** tab. The card **Public API** lists it under **Base URL** and links to the OpenAPI description (**OpenAPI description**).

The version is part of the path. New fields, new endpoints and new event types can be added to `/api/v1` at any time. Ignore fields and event types you do not know. Field names and their meaning do not change under `/api/v1`. A breaking change would be published under `/api/v2`.

The OpenAPI description (version 3.1) is available at `https://app.hocdoc.com/api/v1/openapi.json`. It needs no API key.

## Request and response format

* Read with `GET` requests, write with `POST` requests that carry a JSON body. Every response body is JSON (`application/json; charset=utf-8`). See [Errors](https://docs.hocdoc.com/en/api/errors.md) for `HEAD`, `OPTIONS` and all other methods.
* Field names are English and in `snake_case`.
* A single resource comes back as `{ "data": { ... } }`.
* A list comes back as `{ "data": [ ... ], "next_cursor": "..." }`. On the last page `next_cursor` is `null`. See [Pagination](https://docs.hocdoc.com/en/api/pagination.md).
* IDs are UUIDs.
* Timestamps are ISO 8601 in UTC with milliseconds, for example `2026-10-06T08:15:30.123Z`. Values outside the years 0001 to 9999 are reported as the nearest edge of that range.
* Money amounts are integers in the smallest currency unit, for example cents. Currencies are ISO 4217 codes.
* Responses of the endpoints carry `Cache-Control: no-store`. The OpenAPI description is served with `Cache-Control: public, max-age=300`.
* The API sets no CORS headers. Call it from a server, not from a browser.

Errors have one shape. See [Errors](https://docs.hocdoc.com/en/api/errors.md).

## Quickstart

**1. Create an API key**

Open **Settings**, then the **Integrations** tab. Select **Create API key**. Enter a **Name** (for example the name of the system that will use the key). Optionally set **Valid until (optional)**. Select **Create**.

The dialog **API-Key erstellt** shows the key once. Select **Kopieren** and store it safely, then select **Fertig**. Only owners and admins can create keys. See [Authentication](https://docs.hocdoc.com/en/api/authentication.md).

**2. Store the key in your environment**

```bash theme={null}
export HOCDOC_API_KEY="hd_live_..."
```

**3. Send your first request**

```bash theme={null}
curl "https://app.hocdoc.com/api/v1/offers?status=sent&limit=2" \
  -H "Authorization: Bearer $HOCDOC_API_KEY"
```

The response looks like this:

```json theme={null}
{
  "data": [
    {
      "id": "0b0e7c1e-2f6a-4c3b-9d1e-5a4b3c2d1e0f",
      "title": "Website-Relaunch",
      "status": "sent",
      "language": "de",
      "created_at": "2026-10-06T08:15:30.123Z",
      "updated_at": "2026-10-06T08:20:00.000Z",
      "sent_at": "2026-10-06T08:20:00.000Z",
      "expires_at": "2026-10-20T21:59:59.999Z",
      "accepted_at": null,
      "expired_at": null,
      "version": 1,
      "recipient": {
        "name": "Vera Kundin",
        "company": "Kunde GmbH",
        "email": "vera@kunde.example"
      },
      "accepted_by": null,
      "value": { "amount": 480000, "currency": "EUR" },
      "choice": null
    }
  ],
  "next_cursor": null
}
```

To check only that a key works, call the workspace endpoint:

```bash theme={null}
curl "https://app.hocdoc.com/api/v1/workspace" \
  -H "Authorization: Bearer $HOCDOC_API_KEY"
```

```json theme={null}
{
  "data": {
    "id": "9f1c0a52-6d0e-4a6f-8f43-2f1d7f6a9b10",
    "name": "Studio Nord",
    "timezone": "Europe/Berlin",
    "currency": "EUR"
  }
}
```

## Resources

### Workspace

**id** `string (uuid)`

The workspace ID.

**name** `string`

The workspace name.

**timezone** `string`

IANA time zone, for example `Europe/Berlin`.

**currency** `string`

Default ISO 4217 currency code, for example `EUR`.

### Offer

**id** `string (uuid)`

The offer ID.

**title** `string`

The offer title.

**status** `string`

One of `draft`, `sent`, `accepted`, `declined`, `expired`, `withdrawn`. A sent offer whose `expires_at` has passed is reported as `expired`.

**language** `string`

Language of the offer, `de` or `en`. Everything the recipient sees follows it: the offer page, emails, PDF and certificate. It can be changed in a draft that was never sent and is fixed from the first send.

**created\_at** `string (timestamp)`

When the offer was created.

**updated\_at** `string (timestamp)`

When the offer was last updated.

**sent\_at** `string (timestamp) or null`

When the offer was last sent. `null` for a draft.

**expires\_at** `string (timestamp) or null`

Deadline for acceptance. `null` for a draft.

**accepted\_at** `string (timestamp) or null`

When the offer was accepted. `null` until the offer is accepted.

**expired\_at** `string (timestamp) or null`

When the offer expired. Only set while `status` is `expired`, otherwise `null`.

**version** `integer or null`

Number of the version that was last sent, starting at 1. `null` for a draft.

**recipient** `object`

The person the offer was sent to, with `name`, `company` and `email`. Each can be `null`. All three are `null` for a draft.

**accepted\_by** `object or null`

The person who accepted the offer, with `name` and `email`. `null` until the offer is accepted.

**value** `object`

`amount` (integer, smallest currency unit) and `currency`. The value of the preselected package of the first visible pricing section (the recommended package, otherwise the first one), plus the preselected add-ons with the same currency and the same billing wording as the package. As soon as the recipient has made a choice it is the value of that choice, by the same rule: the chosen package of the first visible pricing section plus the chosen add-ons with the same currency and the same billing wording as the package. That is when the offer is accepted, or with the first signature when several people sign (the offer is then still `sent`). If there is no package, it is 0.

**choice** `object or null`

What the recipient chose in the version last sent: `sections` and `totals`, see [Choice of the recipient](#choice-of-the-recipient). The field is always present. It is `null` if the offer has no pricing section with a choice (a single fixed price) or nothing has been chosen yet, and for a draft. With several signers it is set as soon as the first signer has signed, even though the offer is still `sent`.

#### Choice of the recipient

If an offer has several packages or add-ons to tick, the recipient chooses before accepting. `choice` tells you what was chosen. An accepted offer:

```json theme={null}
"value": { "amount": 150000, "currency": "EUR" },
"choice": {
  "sections": [
    {
      "section_id": "pricing-1",
      "label": "Your choice",
      "package": { "name": "Basic", "price": { "amount": 150000, "currency": "EUR" }, "billing_note": "one-time" },
      "add_ons": [
        { "name": "Support", "price": { "amount": 29000, "currency": "EUR" }, "billing_note": "per month" }
      ],
      "totals": [
        { "amount": 150000, "currency": "EUR", "billing_note": "one-time" },
        { "amount": 29000, "currency": "EUR", "billing_note": "per month" }
      ]
    }
  ],
  "totals": [
    { "amount": 150000, "currency": "EUR", "billing_note": "one-time" },
    { "amount": 29000, "currency": "EUR", "billing_note": "per month" }
  ]
}
```

| Field | Meaning |
| - | - |
| `sections` | One entry per pricing section with a choice, in the order of the offer |
| `sections[].section_id` | ID of the pricing section, as in `section_id` of the event `section_viewed` |
| `sections[].label` | Label of the choice as the recipient saw it |
| `sections[].package` | The chosen package: `name`, `price` (`amount`, `currency`, or `null`), `billing_note` |
| `sections[].add_ons` | The ticked add-ons, same fields as `package`. Empty if none |
| `sections[].totals` | Sums of this section: `amount`, `currency`, `billing_note` |
| `totals` | Sums across the sections listed in `sections` |

* Amounts are whole numbers in the smallest currency unit, like `value`.
* `billing_note` is the billing wording next to the price (for example "one-time" or "per month"). It is empty if there is none.
* There is one total per combination of currency and billing wording. A one-time price and a monthly price are never added up.
* Names, prices and wording are frozen at the time of the choice. They are the same as in the proof of acceptance and the certificate.
* A pricing section with a single fixed price has no entry in `sections`, and its price is not part of `totals`.
* `choice` belongs to the version last sent. After the offer is sent again, it is `null` again.
* `value` stays one number per offer. Once the choice is set (on acceptance, with several signers from the first signature on), it counts the chosen package of the first visible pricing section plus the chosen add-ons with the same currency and billing wording as that package. Before that it counts the preselected package and add-ons. If that section is a single fixed price, `value` is that price. `value` and `choice.totals` can therefore differ in both directions: `choice.totals` covers all pricing sections with a choice and every billing wording, but no fixed-price section.

### Offer event

**sequence** `integer`

Position of the event in the timeline of its offer, starting at 1. Stable.

**type** `string`

Event type. Known values: `created`, `edited`, `sent`, `viewed`, `section_viewed`, `calculator_used`, `summary_viewed`, `pdf_downloaded`, `code_requested`, `code_failed`, `code_verified`, `signed`, `accepted`, `declined`, `expired`, `withdrawn`, `follow_up_sent`, `follow_ups_stopped`, `onboarding_submitted`, `approval_requested`, `approval_granted`, `approval_step_granted`, `approval_rejected`, `approval_revoked`. New types may be added.

**occurred\_at** `string (timestamp)`

When the event happened.

**version** `integer or null`

Number of the offer version the event refers to, if any.

**data** `object`

Details that depend on `type`. Can be empty.

The fields in `data`. Every field is optional, so check that a field is present before you read it:

| Event type | Fields |
| - | - |
| `sent` | `recipient_email` |
| `section_viewed` | `section_id`, `duration_ms` |
| `expired` | `expires_at`: the deadline that passed, truncated to whole seconds. It can differ from `expires_at` of the offer in the milliseconds, so do not compare the two values as keys. |
| `signed` | `signer_email`, `signer_role` (`signer` or `countersigner`), `signing_order`, `signer_total` |
| `code_requested`, `code_failed`, `code_verified`, `accepted` | `signer_email` |
| All other types | None |

Example response of `GET /offers/{id}/events`:

```json theme={null}
{
  "data": [
    {
      "sequence": 1,
      "type": "sent",
      "occurred_at": "2026-10-06T08:20:00.000Z",
      "version": 1,
      "data": { "recipient_email": "vera@kunde.example" }
    },
    {
      "sequence": 2,
      "type": "viewed",
      "occurred_at": "2026-10-06T09:02:11.480Z",
      "version": 1,
      "data": {}
    },
    {
      "sequence": 3,
      "type": "section_viewed",
      "occurred_at": "2026-10-06T09:02:40.112Z",
      "version": 1,
      "data": { "section_id": "pricing-1", "duration_ms": 4200 }
    }
  ],
  "next_cursor": null
}
```

### Offer file

`GET /offers/{id}/files` returns the files of the submitted onboarding form, oldest first, at most 50 per offer and without pages. Read permission is enough. For an offer without a submitted form, or a form without files, `data` is empty.

**id** `string (uuid)`

The file ID.

**name** `string`

The file name as the recipient uploaded it, cleaned: no path, no control characters, at most 120 characters.

**size\_bytes** `integer`

Size in bytes.

**content\_type** `string`

Media type, determined from the content of the file.

**uploaded\_at** `string (timestamp)`

When the file was checked and accepted.

**submitted\_at** `string (timestamp)`

When the recipient submitted the form.

**question** `object`

The file question the file belongs to: `id` and `label` (the question as the recipient saw it, or `null`).

`GET /offers/{id}/files/{fileId}` redirects with `302` to a link of the storage that is valid for 60 seconds and delivers the file as a download. Fetch the link right away and do not store it.

```bash theme={null}
curl -L "https://app.hocdoc.com/api/v1/offers/<id>/files/<fileId>" \
  -H "Authorization: Bearer $HOCDOC_API_KEY" \
  -o file
```

Files have no webhook event and no entry in the timeline.

## Writing

Writing needs a key with the permission **Read and write**. A key with **Read only** gets `403` with the code `forbidden` on every write path. See [Authentication](https://docs.hocdoc.com/en/api/authentication.md).

A key acts as the person who created it. The offers count as that person's, also in the team reporting, and that person's role, the approval rules of the workspace, locked sections and the plan apply exactly as in the app. The request body is JSON (`Content-Type: application/json`) and at most 64 KiB. An unknown field is an error (`400`).

### Create an offer

`POST /offers` creates a draft from a template of the workspace.

```bash theme={null}
curl -X POST "https://app.hocdoc.com/api/v1/offers" \
  -H "Authorization: Bearer $HOCDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-deal-4711" \
  -d '{
    "template_id": "8b0f3c55-1d2e-4a7b-9c6d-2e4f6a8b0c1d",
    "recipient": { "name": "Vera Kundin", "email": "vera@kunde.example", "company": "Kunde GmbH" },
    "title": "Website-Relaunch",
    "language": "de",
    "variables": { "projekt": "Website-Relaunch" }
  }'
```

| Field | Meaning |
| - | - |
| `template_id` | A template of the workspace. A template of another workspace returns `404`. |
| `recipient` | `name` (1 to 200 characters), `email`, and optionally `company`. The draft stores the recipient, and the contact is created or completed. Fields maintained by hand stay. |
| `title` | Optional, otherwise the name of the template. Nothing is replaced in the title. `{{` and `}}` prevent sending later. |
| `language` | `de` or `en`, optional, otherwise the language of the template. |
| `variables` | Answers to the questions of the template, by variable name (at most 20, each up to 2000 characters). Only variables of the template, otherwise `400`. A question without an answer stays empty and prevents sending. |

The response is `201` with the draft as `{ "data": { ... } }`, in the format of the offer above. If an A/B test runs for the template, the database picks the variant as in the app. A draft created through the API stores the recipient, so `recipient` is filled for such drafts.

### Send a draft

`POST /offers/{id}/send` sends a draft like the send dialog of the app.

```bash theme={null}
curl -X POST "https://app.hocdoc.com/api/v1/offers/<id>/send" \
  -H "Authorization: Bearer $HOCDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-deal-4711-send" \
  -d '{ "expires_on": "2026-11-30" }'
```

| Field | Meaning |
| - | - |
| `expires_on` | Last day for acceptance (`YYYY-MM-DD`), valid until the end of that day in the time zone of the workspace. Optional, otherwise in 14 days. |
| `recipient` | Optional, otherwise the recipient from the creation. A draft created in the app needs it. |

Placeholders are filled, the document is checked and frozen as a version, the recipient gets the email and webhooks fire (`offer.sent`). Only drafts can be sent: an offer that was sent already returns `409` with `invalid_state`. Sending through the API has no personal message, no follow-ups and no further signers.

If the workspace requires an approval before sending for the person who created the key, the API does not send and returns `409` with `approval_required`. An approval cannot be requested or granted through the API.

### Withdraw an offer

`POST /offers/{id}/withdraw` withdraws an offer.

```bash theme={null}
curl -X POST "https://app.hocdoc.com/api/v1/offers/<id>/withdraw" \
  -H "Authorization: Bearer $HOCDOC_API_KEY"
```

Only offers with the status `sent` can be withdrawn, otherwise the response is `409` with `invalid_state`. The webhook `offer.withdrawn` fires.

### Idempotency-Key

Send the optional header `Idempotency-Key` on all three write paths to retry safely. It is up to 255 visible ASCII characters, for example a UUID or the ID in your own system, and applies per workspace.

* Same key, same content, within 24 hours: the same response as the first success, with the header `Idempotent-Replayed: true`. Nothing happens twice, also not for two requests at the same time.
* Same key, different content: `409` with `idempotency_key_reused`. If the first request is still running: `409` with `idempotency_key_in_use`. Wait briefly and retry.
* An error does not bind the key. After `400`, `404`, `409` or `422`, the same request with the same key runs again.

Without a key, a second request at the same time does not send twice either: only one draft is sent, and the second request gets `409` with `invalid_state`.

## What the API never returns

* The link to the offer for the recipient.
* The content of an offer: sections, texts and prices in detail. Packages and add-ons that were not chosen are not returned either. Of the content, only the choice of the recipient is returned (`choice`): the chosen package and add-ons with name, price and billing wording.
* IP addresses and browser identifiers of recipients.
* Templates, PDFs and certificates. The API creates and completes the contact of a recipient when you create an offer, but it does not return contacts.
* Anything from another workspace.

Editing, deleting, sending again and approvals are not possible through the API. To be told about changes instead of asking for them, use [Webhooks](https://docs.hocdoc.com/en/api/webhooks.md). A `PUT`, `PATCH` or `DELETE` request returns `405`. See [Errors](https://docs.hocdoc.com/en/api/errors.md).

## Next steps

* [Authentication](https://docs.hocdoc.com/en/api/authentication.md): create, send and revoke keys, and the permission of a key.
* [Pagination](https://docs.hocdoc.com/en/api/pagination.md): walk through long lists.
* [Errors](https://docs.hocdoc.com/en/api/errors.md): error format and codes.
* [Rate limits](https://docs.hocdoc.com/en/api/rate-limits.md): limits and response headers.
* [Webhooks](https://docs.hocdoc.com/en/api/webhooks.md): get events pushed to your server.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.