Reonic Signature Requests API

openapi: 3.1.0
info:
  title: Reonic REST Api v3 Activities Signature Requests API
  description: 'The Reonic REST API v3 provides programmatic access to create and manage resources. The API follows REST principles and returns responses in JSON format. Authentication is required via an API key passed in the X-Authorization header.


    ## Errors


    All endpoints return errors with the same JSON shape:


    ```json

    { "message": "human-readable description" }

    ```


    `400` responses additionally include an `errors` field with per-field validation details.


    The HTTP status code identifies the cause:


    | Status  | Meaning | When |

    |--------|---------|------|

    | `400` | Bad Request | Path params, query string, or request body failed validation. Inspect `errors` for the field-level breakdown. |

    | `401` | Unauthorized | The `X-Authorization` header is missing, malformed, does not match an active API key, or belongs to a different API version. The response never indicates which check failed; check that the key matches the endpoint version. API v3 endpoints require a v3 key with the `rnc_v3_` prefix. |

    | `403` | Forbidden | The API key is read-only and the request targeted a write endpoint (`POST`). Issue a key with write access. |

    | `404` | Not Found | A resource referenced by a path id does not exist or is not visible to your workspace. |

    | `429` | Too Many Requests | The per-client rate limit was exceeded. See **Rate limiting** below. |

    | `500` | Internal Server Error | Unexpected failure. Safe to retry once; if it persists, contact support. |

    | `503` | Service Unavailable | A backing dependency is temporarily unavailable. Retry with exponential backoff. |


    ## Rate limiting


    Limits are shared across all API keys you hold and reset on a 1-minute window. Two buckets:


    | Bucket | Limit | Applies to |

    |--------|-------|------------|

    | `cached` | 500 / min | `GET` requests served from the response cache |

    | `uncached` | 30 / min | Cache misses, `GET` requests sent with `Reonic-Cache-Control: no-cache`, and all `POST` requests |


    Every response includes:


    - `X-RateLimit-Bucket` — `cached` or `uncached`

    - `X-RateLimit-Limit` — the bucket''s ceiling (`500` or `30`)

    - `X-RateLimit-Remaining` — calls left in the current window

    - `X-RateLimit-Reset` — Unix epoch seconds at which the window resets

    - `X-RateLimit-Policy` — `<limit>;w=60`


    `429` responses additionally set `Retry-After` (in seconds). Wait at least that long before retrying.


    ## Caching and Reonic-Cache-Control


    `GET` responses are cached for up to 1 hour. Identical requests (same path and query) on the same API key return the cached result. To force a fresh read, send `Reonic-Cache-Control: no-cache`; the response is then refreshed and re-cached. Forced refreshes count against the `uncached` rate-limit bucket.


    The standard `Cache-Control` header is not honored. Use `Reonic-Cache-Control` to control caching behavior.


    ## Authentication


    Every request must include your API key in the `X-Authorization` header:


    ```

    X-Authorization: <your-api-key>

    ```


    API keys are issued from the Reonic web app and look like `rnc_v3_…`. Send the full value, including the prefix.

    '
  version: 3.2.0
  contact:
    email: kontakt@reonic.de
    url: https://reonic.com
    name: Reonic GmbH
servers:
- url: '{apiBaseUrl}/rest/v3/'
security:
- X-Authorization: []
tags:
- name: Signature Requests
  description: Requests sent to a customer to sign a residential project's offer. Each carries the offer PDF for every variant the customer can choose between, available even before signing, plus the signed document once completed.
paths:
  /residentialProjects/{projectId}/signatureRequests:
    get:
      summary: List residential projects signature requests
      description: 'List all signature requests of a residential project, each including the offer PDF for every variant/payment option sent for signing. Signature requests are created once the project reaches the offer stage and its offer is sent out for signature.


        **Allowed API keys:** Read-only, Read and Write'
      tags:
      - Signature Requests
      parameters:
      - schema:
          type: string
          format: uuid
        required: true
        name: projectId
        in: path
      - schema:
          type: string
          example: no-cache
        required: false
        name: Reonic-Cache-Control
        in: header
        description: Set to 'no-cache' to bypass the 1-hour response cache and force a fresh read. The fresh response is then written back to the cache for subsequent callers. Forced refreshes count against the uncached rate-limit bucket (30/min); only cache hits count against the cached bucket (500/min).
      responses:
        '200':
          description: The project's signature requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ResidentialProjectSignatureRequest'
                    description: List of items
                required:
                - data
components:
  schemas:
    ResidentialProjectSignatureRequest:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
        projectId:
          type: string
          format: uuid
          description: Reference to [**Residential Projects**](#tag/residential-projects)
          example: 123e4567-e89b-12d3-a456-426614174000
        status:
          type: string
          enum:
          - awaitingSignature
          - signed
          - expired
          - withdrawn
          - revokedByCustomer
        offerDocuments:
          type: array
          items:
            type: object
            properties:
              variantId:
                type: string
                format: uuid
                description: The offer variant this document was generated for.
                example: 123e4567-e89b-12d3-a456-426614174000
              paymentOptionId:
                type:
                - string
                - 'null'
                format: uuid
                description: The payment option this document was generated for. `null` for legacy/default-payment documents.
                example: 123e4567-e89b-12d3-a456-426614174000
              pdfUrl:
                type: string
                format: uri
                description: This variant/payment option's offer PDF, as shown to the customer for signing. URL valid 24 hours.
            required:
            - variantId
            - paymentOptionId
            - pdfUrl
          description: Offer documents sent for signature, one per variant/payment option the customer can choose between.
        signedVariantId:
          type:
          - string
          - 'null'
          format: uuid
          description: The offer variant the customer signed. `null` until the request is signed.
          example: 123e4567-e89b-12d3-a456-426614174000
        signedPaymentOptionId:
          type:
          - string
          - 'null'
          format: uuid
          description: The payment option the customer signed. `null` until signed, or for legacy/default-payment documents.
          example: 123e4567-e89b-12d3-a456-426614174000
        signedPdfUrl:
          type:
          - string
          - 'null'
          format: uri
          description: Countersigned offer document; `null` until signed. After the customer revokes (`revokedByCustomer`), points to that document, stamped to reflect the revocation. URL valid 24 hours.
        revocationPdfUrl:
          type:
          - string
          - 'null'
          format: uri
          description: The customer's separate revocation declaration, if one was recorded. `null` otherwise — a revocation doesn't always include a separate declaration; the revoked contract itself is `signedPdfUrl`. URL valid 24 hours.
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type:
          - string
          - 'null'
          format: date-time
        signedAt:
          type:
          - string
          - 'null'
          format: date-time
        withdrawnAt:
          type:
          - string
          - 'null'
          format: date-time
          description: When your team withdrew a still-pending request (status `withdrawn`); `null` otherwise. For customer revocation of a signed contract, see `revokedByCustomerAt`.
        revokedByCustomerAt:
          type:
          - string
          - 'null'
          format: date-time
          description: When the customer revoked an already-signed contract (status `revokedByCustomer`); `null` otherwise.
      required:
      - id
      - projectId
      - status
      - offerDocuments
      - signedVariantId
      - signedPaymentOptionId
      - signedPdfUrl
      - revocationPdfUrl
      - createdAt
      - expiresAt
      - signedAt
      - withdrawnAt
      - revokedByCustomerAt
  securitySchemes:
    X-Authorization:
      type: apiKey
      in: header
      name: X-Authorization
x-tagGroups:
- name: People
  tags:
  - Contacts
  - Users
  - Teams
- name: Projects
  tags:
  - Residential Projects
  - Commercial Projects
- name: Working on a project
  tags:
  - Notes
  - Tasks
  - Files
  - File Folders
  - Activities
  - Time Tracking
  - Checklists
  - Checklist Templates
  - Signature Requests
- name: Calendar
  tags:
  - Calendars
  - Calendar Categories
  - Appointments
- name: Catalog
  tags:
  - Components
  - Planning Templates
  - Planning Packages
  - Offer Templates
- name: Workspace setup
  tags:
  - Kanban Boards
  - Kanban Columns
  - Tags
  - Lead Sources
- name: Wiki
  tags:
  - Wiki
- name: Services
  tags:
  - Photogrammetry
- name: API helpers
  tags:
  - Upload
  - Links
- name: Integrations
  tags:
  - Webhooks
- name: Guides
  tags:
  - Migrating from API v2 to v3
  - Changelog