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:/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
GETrequests, write withPOSTrequests that carry a JSON body. Every response body is JSON (application/json; charset=utf-8). See Errors forHEAD,OPTIONSand 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 pagenext_cursorisnull. 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 withCache-Control: public, max-age=300. - The API sets no CORS headers. Call it from a server, not from a browser.
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
Resources
Workspace
Offer
One of
draft, sent, accepted, declined, expired, withdrawn. A sent offer whose expires_at has passed is reported as expired.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.The person the offer was sent to, with
name, company and email. Each can be null. All three are null for a draft.The person who accepted the offer, with
name and email. null until the offer is accepted.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.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_noteis 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 oftotals. choicebelongs to the version last sent. After the offer is sent again, it isnullagain.valuestays 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,valueis that price.valueandchoice.totalscan therefore differ in both directions:choice.totalscovers all pricing sections with a choice and every billing wording, but no fixed-price section.
Offer event
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.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.
The file name as the recipient uploaded it, cleaned: no path, no control characters, at most 120 characters.
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.
Writing
Writing needs a key with the permission Read and write. A key with Read only gets403 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.
sent can be withdrawn, otherwise the response is 409 with invalid_state. The webhook offer.withdrawn fires.
Idempotency-Key
Send the optional headerIdempotency-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:
409withidempotency_key_reused. If the first request is still running:409withidempotency_key_in_use. Wait briefly and retry. - An error does not bind the key. After
400,404,409or422, the same request with the same key runs again.
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.
PUT, PATCH or DELETE request returns 405. See Errors.
Next steps
- Authentication: create, send and revoke keys, and the permission of a key.
- Pagination: walk through long lists.
- Errors: error format and codes.
- Rate limits: limits and response headers.
- Webhooks: get events pushed to your server.