Skip to main content

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: See the endpoint reference in the sidebar for every parameter and response.

Base URL and versioning

All paths are relative to this base URL:
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 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.
  • 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.

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.
2

Store the key in your environment

3

Send your first request

The response looks like this:
To check only that a key works, call the workspace endpoint:

Resources

Workspace

string (uuid)
The workspace ID.
string
The workspace name.
string
IANA time zone, for example Europe/Berlin.
string
Default ISO 4217 currency code, for example EUR.

Offer

string (uuid)
The offer ID.
string
The offer title.
string
One of draft, sent, accepted, declined, expired, withdrawn. A sent offer whose expires_at has passed is reported as expired.
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.
string (timestamp)
When the offer was created.
string (timestamp)
When the offer was last updated.
string (timestamp) or null
When the offer was last sent. null for a draft.
string (timestamp) or null
Deadline for acceptance. null for a draft.
string (timestamp) or null
When the offer was accepted. null until the offer is accepted.
string (timestamp) or null
When the offer expired. Only set while status is expired, otherwise null.
integer or null
Number of the version that was last sent, starting at 1. null for a draft.
object
The person the offer was sent to, with name, company and email. Each can be null. All three are null for a draft.
object or null
The person who accepted the offer, with name and email. null until the offer is accepted.
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.
object or null
What the recipient chose in the version last sent: sections and totals, see 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:
  • 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

integer
Position of the event in the timeline of its offer, starting at 1. Stable.
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.
string (timestamp)
When the event happened.
integer or null
Number of the offer version the event refers to, if any.
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: Example response of GET /offers/{id}/events:

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.
string (uuid)
The file ID.
string
The file name as the recipient uploaded it, cleaned: no path, no control characters, at most 120 characters.
integer
Size in bytes.
string
Media type, determined from the content of the file.
string (timestamp)
When the file was checked and accepted.
string (timestamp)
When the recipient submitted the form.
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.
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. 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.
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.
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.
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. A PUT, PATCH or DELETE request returns 405. See Errors.

Next steps