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

# List offers

> Newest first (by `created_at`). Use `next_cursor` to page.



## OpenAPI

````yaml /api-reference/openapi.json get /offers
openapi: 3.1.0
info:
  title: HocDoc API
  version: 1.0.0
  description: >-
    API for offers and their timeline. Every key reads. A key with write
    permission also creates offers from templates, sends and withdraws them.


    Send an API key as `Authorization: Bearer <key>`. A key belongs to one
    workspace and only reaches its data. Create keys in the app under
    Einstellungen, Integrationen, with the permission read or read and write.


    Writes act on behalf of the person who created the key: offers count as
    theirs, and their role, the approval rules of the workspace, locked sections
    and the plan apply exactly as in the app. Send `Idempotency-Key` to retry a
    write safely.


    Timestamps are ISO 8601 in UTC with milliseconds. Values outside the years
    0001 to 9999 are clamped to that range.


    Limits: 120 requests per minute per key and 300 requests per minute per IP
    address. Writes: 30 per minute per key and 60 per minute per workspace
    across all of its keys. Request bodies up to 64 KiB. See the `RateLimit-*`
    headers of each response.


    Compatibility: new fields, endpoints and event types may be added at any
    time, so ignore what you do not know. Breaking changes come under a new path
    (`/api/v2`).


    Webhooks: HocDoc can send a signed `POST` request to up to 5 HTTPS endpoints
    per workspace when something happens to an offer or when the status of a
    custom domain changes. Add endpoints in the app under Einstellungen,
    Integrationen. Each endpoint has its own secret (`whsec_…`), shown once.
    Requests are signed following the Standard Webhooks specification, see the
    `webhook-*` headers. A delivery succeeds with any 2xx status within 10
    seconds. Otherwise it is retried, 8 attempts over about a day. After 5
    deliveries in a row that failed for good, the endpoint is paused. Order is
    not guaranteed and an event can arrive more than once: use `webhook-id` to
    ignore duplicates.
servers:
  - url: https://app.hocdoc.com/api/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Workspace
    description: The workspace of the API key.
  - name: Offers
    description: Offers and their timeline.
  - name: Webhooks
    description: Requests HocDoc sends to your endpoints.
paths:
  /offers:
    get:
      tags:
        - Offers
      summary: List offers
      description: Newest first (by `created_at`). Use `next_cursor` to page.
      operationId: listOffers
      parameters:
        - name: status
          in: query
          required: false
          description: Only offers with this status.
          schema:
            type: string
            enum:
              - draft
              - sent
              - accepted
              - declined
              - expired
              - withdrawn
        - name: limit
          in: query
          required: false
          description: Page size, 1 to 100.
          schema:
            default: 25
            type: integer
            minimum: 1
            maximum: 100
        - name: cursor
          in: query
          required: false
          description: Opaque cursor from `next_cursor` of the previous page.
          schema:
            type: string
            minLength: 1
            maxLength: 512
      responses:
        '200':
          description: A page of offers.
          headers:
            RateLimit-Limit:
              description: Requests allowed per window for this API key.
              required: true
              schema:
                type: integer
            RateLimit-Remaining:
              description: Requests left in the current window.
              required: true
              schema:
                type: integer
            RateLimit-Reset:
              description: Seconds until the current window ends.
              required: true
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfferListResponse'
              examples:
                page:
                  summary: A page with a next page
                  value:
                    data:
                      - id: 0b0e7c1e-2f6a-4c3b-9d1e-5a4b3c2d1e0f
                        title: Website relaunch
                        status: sent
                        language: en
                        created_at: '2026-10-06T08:15:30.123Z'
                        updated_at: '2026-10-06T08:20:04.317Z'
                        sent_at: '2026-10-06T08:20:04.317Z'
                        expires_at: '2026-10-20T21:59:59.999Z'
                        accepted_at: null
                        expired_at: null
                        version: 2
                        recipient:
                          name: Jane Doe
                          company: Example GmbH
                          email: jane@example.com
                        accepted_by: null
                        value:
                          amount: 480000
                          currency: EUR
                        choice: null
                      - id: 5d2c8a40-7b19-4e6f-a3d8-1c9e0f7b2a64
                        title: Brand identity package
                        status: accepted
                        language: en
                        created_at: '2026-09-28T09:00:12.481Z'
                        updated_at: '2026-10-02T14:07:46.001Z'
                        sent_at: '2026-09-29T10:15:00.642Z'
                        expires_at: '2026-10-13T21:59:59.999Z'
                        accepted_at: '2026-10-02T14:07:45.912Z'
                        expired_at: null
                        version: 1
                        recipient:
                          name: John Smith
                          company: Sample AG
                          email: john@example.com
                        accepted_by:
                          name: John Smith
                          email: john@example.com
                        value:
                          amount: 1250000
                          currency: EUR
                        choice:
                          sections:
                            - section_id: pricing-1
                              label: Your choice
                              package:
                                name: Complete
                                price:
                                  amount: 1150000
                                  currency: EUR
                                billing_note: one-time
                              add_ons:
                                - name: Workshop
                                  price:
                                    amount: 100000
                                    currency: EUR
                                  billing_note: one-time
                                - name: Support
                                  price:
                                    amount: 29000
                                    currency: EUR
                                  billing_note: per month
                              totals:
                                - amount: 1250000
                                  currency: EUR
                                  billing_note: one-time
                                - amount: 29000
                                  currency: EUR
                                  billing_note: per month
                          totals:
                            - amount: 1250000
                              currency: EUR
                              billing_note: one-time
                            - amount: 29000
                              currency: EUR
                              billing_note: per month
                    next_cursor: >-
                      eyJjIjoiMjAyNi0wOS0yOFQwOTowMDoxMi40ODEwMDBaIiwiaSI6IjVkMmM4YTQwLTdiMTktNGU2Zi1hM2Q4LTFjOWUwZjdiMmE2NCJ9
                last_page:
                  summary: The last page
                  value:
                    data:
                      - id: c7a91e3d-48b2-4f05-86de-3a1b5c7d9e02
                        title: Campaign retainer
                        status: expired
                        language: de
                        created_at: '2026-09-01T07:30:00.000Z'
                        updated_at: '2026-09-15T22:00:00.250Z'
                        sent_at: '2026-09-02T08:00:11.205Z'
                        expires_at: '2026-09-15T21:59:59.999Z'
                        accepted_at: null
                        expired_at: '2026-09-15T21:59:59.999Z'
                        version: 1
                        recipient:
                          name: Alex Example
                          company: Placeholder Ltd
                          email: alex@example.com
                        accepted_by: null
                        value:
                          amount: 90000
                          currency: EUR
                        choice: null
                    next_cursor: null
        '400':
          description: >-
            Invalid query parameter, or a query string longer than 1024
            characters (`invalid_request`).
          headers:
            RateLimit-Limit:
              description: >-
                Requests allowed per window for this API key. Not sent when the
                query string is too long.
              required: false
              schema:
                type: integer
            RateLimit-Remaining:
              description: >-
                Requests left in the current window. Not sent when the query
                string is too long.
              required: false
              schema:
                type: integer
            RateLimit-Reset:
              description: >-
                Seconds until the current window ends. Not sent when the query
                string is too long.
              required: false
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_parameter:
                  value:
                    error:
                      code: invalid_request
                      message: Invalid value for query parameter "limit".
                      param: limit
                query_too_long:
                  value:
                    error:
                      code: invalid_request
                      message: Query string too long.
        '401':
          description: >-
            Missing or invalid API key. The response is the same for a missing,
            malformed, unknown, revoked or expired key.
          headers:
            RateLimit-Limit:
              description: >-
                Requests allowed per window for this API key. Not sent when the
                key is missing or malformed.
              required: false
              schema:
                type: integer
            RateLimit-Remaining:
              description: >-
                Requests left in the current window. Not sent when the key is
                missing or malformed.
              required: false
              schema:
                type: integer
            RateLimit-Reset:
              description: >-
                Seconds until the current window ends. Not sent when the key is
                missing or malformed.
              required: false
              schema:
                type: integer
            WWW-Authenticate:
              description: The authentication scheme the API expects. Always `Bearer`.
              required: true
              schema:
                type: string
                examples:
                  - Bearer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  value:
                    error:
                      code: unauthorized
                      message: Missing or invalid API key.
        '405':
          description: >-
            Method not allowed. Sent for `PUT`, `PATCH` and `DELETE` on this
            path. No API key is needed and the rate limit headers are not sent.
          headers:
            Allow:
              description: The methods this path accepts.
              required: true
              schema:
                type: string
                examples:
                  - GET, HEAD, POST, OPTIONS
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                method_not_allowed:
                  value:
                    error:
                      code: method_not_allowed
                      message: Method not allowed.
        '429':
          description: >-
            Too many requests. Either the limit per API key or the limit per IP
            address was reached.
          headers:
            RateLimit-Limit:
              description: >-
                Requests allowed per window for this API key. Not sent when the
                limit per IP address was reached.
              required: false
              schema:
                type: integer
            RateLimit-Remaining:
              description: >-
                Requests left in the current window. Not sent when the limit per
                IP address was reached.
              required: false
              schema:
                type: integer
            RateLimit-Reset:
              description: >-
                Seconds until the current window ends. Not sent when the limit
                per IP address was reached.
              required: false
              schema:
                type: integer
            Retry-After:
              required: true
              description: Seconds to wait before the next request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                rate_limited:
                  value:
                    error:
                      code: rate_limited
                      message: Too many requests.
        '500':
          description: Internal server error.
          headers:
            RateLimit-Limit:
              description: Requests allowed per window for this API key.
              required: true
              schema:
                type: integer
            RateLimit-Remaining:
              description: Requests left in the current window.
              required: true
              schema:
                type: integer
            RateLimit-Reset:
              description: Seconds until the current window ends.
              required: true
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  value:
                    error:
                      code: internal_error
                      message: Internal server error.
components:
  schemas:
    OfferListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Offer'
          description: The offers of this page, newest first.
        next_cursor:
          description: Pass as `cursor` to fetch the next page. Null on the last page.
          type:
            - string
            - 'null'
      required:
        - data
        - next_cursor
      description: A page of offers.
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - unauthorized
                - not_found
                - invalid_request
                - method_not_allowed
                - rate_limited
                - internal_error
                - forbidden
                - body_too_large
                - unsupported_media_type
                - idempotency_key_reused
                - idempotency_key_in_use
                - invalid_state
                - draft_changed
                - approval_required
                - recipient_required
                - open_placeholders
                - invalid_document
                - invalid_template
                - locked_section
              description: Stable, machine-readable error code.
            message:
              type: string
              description: Human-readable message. May change, do not parse.
            param:
              description: >-
                The query parameter, header or body field that was rejected.
                Body fields as a path, for example `recipient.email`.
              type: string
          required:
            - code
            - message
      required:
        - error
      description: Every error of the API has this shape.
    Offer:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID of the offer.
        title:
          type: string
          description: Title of the offer.
        status:
          $ref: '#/components/schemas/OfferStatus'
        language:
          type: string
          enum:
            - de
            - en
          description: >-
            Language of the offer. Everything the recipient sees follows it: the
            offer page, emails, PDF and certificate. Fixed when the offer is
            first sent.
          examples:
            - en
        created_at:
          type: string
          format: date-time
          examples:
            - '2026-10-06T08:15:30.123Z'
          description: When the offer was created.
        updated_at:
          type: string
          format: date-time
          examples:
            - '2026-10-06T08:15:30.123Z'
          description: When the offer was last changed.
        sent_at:
          type:
            - string
            - 'null'
          format: date-time
          examples:
            - '2026-10-06T08:15:30.123Z'
          description: When the offer was last sent. Null for a draft.
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          examples:
            - '2026-10-06T08:15:30.123Z'
          description: Deadline for acceptance. Null for a draft.
        accepted_at:
          type:
            - string
            - 'null'
          format: date-time
          examples:
            - '2026-10-06T08:15:30.123Z'
          description: When the offer was accepted. Null until it is accepted.
        expired_at:
          type:
            - string
            - 'null'
          format: date-time
          examples:
            - '2026-10-06T08:15:30.123Z'
          description: When the offer expired. Only set while `status` is `expired`.
        version:
          type:
            - integer
            - 'null'
          minimum: 1
          description: Number of the version that was last sent. Null for a draft.
        recipient:
          $ref: '#/components/schemas/Recipient'
        accepted_by:
          anyOf:
            - $ref: '#/components/schemas/Signer'
            - type: 'null'
          description: The person who accepted the offer. Null until it is accepted.
        value:
          allOf:
            - $ref: '#/components/schemas/Money'
          description: >-
            Value of the offer: the chosen package of the first visible pricing
            section (before a choice is saved: the recommended package,
            otherwise the first one) plus the chosen add-ons with the same
            currency and billing wording as the package, otherwise 0.
        choice:
          anyOf:
            - $ref: '#/components/schemas/OfferChoice'
            - type: 'null'
          description: >-
            What the recipient chose in the version last sent. Null if the offer
            has no pricing section with a choice or nothing has been chosen yet.
            With several signers it is set as soon as the first signer has
            signed.
      required:
        - id
        - title
        - status
        - language
        - created_at
        - updated_at
        - sent_at
        - expires_at
        - accepted_at
        - expired_at
        - version
        - recipient
        - accepted_by
        - value
        - choice
      description: An offer with its status, dates, recipient and value.
    OfferStatus:
      type: string
      enum:
        - draft
        - sent
        - accepted
        - declined
        - expired
        - withdrawn
      description: >-
        Current status of an offer. A sent offer whose `expires_at` has passed
        is reported as `expired`.
    Recipient:
      type: object
      properties:
        name:
          description: Name of the recipient.
          type:
            - string
            - 'null'
        company:
          description: Company of the recipient.
          type:
            - string
            - 'null'
        email:
          description: Email address of the recipient.
          type:
            - string
            - 'null'
      required:
        - name
        - company
        - email
      description: >-
        The person the offer was sent to. For a draft: the recipient given when
        the draft was created through the API, otherwise all fields are null.
    Signer:
      type: object
      properties:
        name:
          type: string
          description: Name the signer entered.
        email:
          type: string
          description: Email address of the signer.
      required:
        - name
        - email
      description: The person who accepted the offer.
    Money:
      type: object
      properties:
        amount:
          type: integer
          minimum: 0
          description: Amount in the smallest currency unit (for example cents).
          examples:
            - 480000
        currency:
          type: string
          description: ISO 4217 currency code.
          examples:
            - EUR
      required:
        - amount
        - currency
      description: An amount of money.
    OfferChoice:
      type: object
      properties:
        sections:
          type: array
          items:
            $ref: '#/components/schemas/OfferChoiceSection'
          description: >-
            One entry per pricing section with a choice, in the order of the
            offer.
        totals:
          type: array
          items:
            $ref: '#/components/schemas/OfferChoiceTotal'
          description: >-
            Sums across all sections: one entry per combination of currency and
            billing wording.
      required:
        - sections
        - totals
      description: >-
        What the recipient chose: one package per pricing section, add-ons and
        totals. Names, prices and wording are frozen at the time of the choice.
    OfferChoiceSection:
      type: object
      properties:
        section_id:
          type: string
          description: >-
            ID of the pricing section, as in `section_id` of the event
            `section_viewed`.
          examples:
            - pricing-1
        label:
          type: string
          description: Label of the choice as the recipient saw it.
          examples:
            - Your choice
        package:
          $ref: '#/components/schemas/OfferChoiceItem'
        add_ons:
          type: array
          items:
            $ref: '#/components/schemas/OfferChoiceItem'
          description: The add-ons the recipient ticked. Empty if none.
        totals:
          type: array
          items:
            $ref: '#/components/schemas/OfferChoiceTotal'
          description: >-
            Sums of this section: one entry per combination of currency and
            billing wording.
      required:
        - section_id
        - label
        - package
        - add_ons
        - totals
      description: The choice in one pricing section.
    OfferChoiceTotal:
      type: object
      properties:
        amount:
          type: integer
          minimum: 0
          description: Sum in the smallest currency unit (for example cents).
          examples:
            - 1250000
        currency:
          type: string
          description: ISO 4217 currency code.
          examples:
            - EUR
        billing_note:
          type: string
          description: Billing wording the summed prices share. Empty if they have none.
          examples:
            - one-time
      required:
        - amount
        - currency
        - billing_note
      description: >-
        Sum of the chosen prices that share currency and billing wording. Prices
        with different wording are never added up.
    OfferChoiceItem:
      type: object
      properties:
        name:
          type: string
          description: Name of the package or add-on as the recipient saw it.
          examples:
            - Complete
        price:
          anyOf:
            - $ref: '#/components/schemas/Money'
            - type: 'null'
          description: Price. Null if the item has no price.
        billing_note:
          type: string
          description: >-
            Billing wording next to the price, for example "one-time" or "per
            month". Empty if there is none.
          examples:
            - one-time
      required:
        - name
        - price
        - billing_note
      description: A package or add-on the recipient chose, as it was at that time.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: API key, for example `hd_live_…`.

````

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