> ## 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 the events of an offer

> The timeline of the offer, oldest first (by `sequence`). Use `next_cursor` to page.



## OpenAPI

````yaml /api-reference/openapi.json get /offers/{id}/events
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/{id}/events:
    get:
      tags:
        - Offers
      summary: List the events of an offer
      description: >-
        The timeline of the offer, oldest first (by `sequence`). Use
        `next_cursor` to page.
      operationId: listOfferEvents
      parameters:
        - name: id
          in: path
          required: true
          description: ID of the offer.
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          required: false
          description: Page size, 1 to 200.
          schema:
            default: 50
            type: integer
            minimum: 1
            maximum: 200
        - 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 events.
          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/OfferEventListResponse'
              examples:
                accepted_offer:
                  summary: Timeline of an accepted offer
                  value:
                    data:
                      - sequence: 1
                        type: created
                        occurred_at: '2026-09-28T09:00:12.481Z'
                        version: null
                        data: {}
                      - sequence: 2
                        type: sent
                        occurred_at: '2026-09-29T10:15:00.642Z'
                        version: 1
                        data:
                          recipient_email: john@example.com
                      - sequence: 3
                        type: viewed
                        occurred_at: '2026-09-29T11:02:11.480Z'
                        version: 1
                        data: {}
                      - sequence: 4
                        type: section_viewed
                        occurred_at: '2026-09-29T11:02:40.112Z'
                        version: 1
                        data:
                          section_id: pricing-1
                          duration_ms: 4200
                      - sequence: 5
                        type: code_requested
                        occurred_at: '2026-10-02T14:06:58.320Z'
                        version: 1
                        data:
                          signer_email: john@example.com
                      - sequence: 6
                        type: code_verified
                        occurred_at: '2026-10-02T14:07:31.775Z'
                        version: 1
                        data:
                          signer_email: john@example.com
                      - sequence: 7
                        type: accepted
                        occurred_at: '2026-10-02T14:07:45.912Z'
                        version: 1
                        data:
                          signer_email: john@example.com
                    next_cursor: null
                expired_offer:
                  summary: Timeline of an expired offer
                  value:
                    data:
                      - sequence: 1
                        type: created
                        occurred_at: '2026-09-01T07:30:00.000Z'
                        version: null
                        data: {}
                      - sequence: 2
                        type: sent
                        occurred_at: '2026-09-02T08:00:11.205Z'
                        version: 1
                        data:
                          recipient_email: alex@example.com
                      - sequence: 3
                        type: expired
                        occurred_at: '2026-09-15T22:00:00.250Z'
                        version: 1
                        data:
                          expires_at: '2026-09-15T21:59:59.000Z'
                    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.
        '404':
          description: >-
            Resource not found. The response is the same for an unknown ID, an
            ID of another workspace and an ID in the wrong form.
          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:
                not_found:
                  value:
                    error:
                      code: not_found
                      message: Resource not found.
        '405':
          description: >-
            Method not allowed. Sent for `POST`, `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, 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:
    OfferEventListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/OfferEvent'
          description: The events of this page, oldest 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 events of one offer.
    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.
    OfferEvent:
      type: object
      properties:
        sequence:
          type: integer
          minimum: 1
          description: >-
            Position of the event in the timeline of its offer, starting at 1.
            Stable.
        type:
          type: string
          description: >-
            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, clients must ignore types they do not know.
          examples:
            - sent
        occurred_at:
          type: string
          format: date-time
          examples:
            - '2026-10-06T08:15:30.123Z'
          description: When the event happened.
        version:
          type:
            - integer
            - 'null'
          minimum: 1
          description: Number of the offer version the event refers to, if any.
        data:
          $ref: '#/components/schemas/OfferEventData'
      required:
        - sequence
        - type
        - occurred_at
        - version
        - data
      description: One entry in the timeline of an offer.
    OfferEventData:
      type: object
      properties:
        recipient_email:
          description: Event `sent`.
          type: string
        section_id:
          description: Event `section_viewed`.
          type: string
        duration_ms:
          description: Event `section_viewed`.
          type: integer
          minimum: 0
        expires_at:
          description: >-
            Event `expired`: the deadline that passed, truncated to whole
            seconds. It can differ from `expires_at` of the offer in the
            milliseconds.
          examples:
            - '2026-10-20T21:59:59.000Z'
          type: string
          format: date-time
        signer_email:
          description: >-
            Events `code_requested`, `code_failed`, `code_verified`, `signed`,
            `accepted`.
          type: string
        signer_role:
          description: >-
            Event `signed`: `signer` for a signer on the recipient side,
            `countersigner` for the sender. New values may be added.
          examples:
            - signer
          type: string
        signing_order:
          description: >-
            Event `signed`: position of this signature in the signing order,
            starting at 1.
          type: integer
          minimum: 1
        signer_total:
          description: 'Event `signed`: number of signatures the offer needs in total.'
          type: integer
          minimum: 1
      description: >-
        Details of an event. Which fields are present depends on `type`. May be
        empty.
  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.