Contractbook Attachments API

openapi: 3.2.0
info:
  description: '> **Note**

    >

    > Looking for documentation for **Public API v2**? Click here. >

    >

    > Please, provide your feedback via `#help-public-api` channel at Contractbook Friends

    > Slack or by sending an email at help-public-api@contractbook.dk. ## Table of Contents


    - Introduction

    - Migration from Public API v2

    - Authentication

    - Use cases

    - Scenario 1: Sending multiple contracts for signature

    - Scenario 2: Uploading attachments to a document

    - Scenario 3: Deleting a document

    - Scenario 4: Using data fields

    - Scenario 5: Downloading the contract as PDF

    - Scenario 6: Sharing a document with collaborators

    - Scenario 7: Receiving notifications for document life-cycle events

    - Appendix A: Enhancing the /v3/documents


    ## Introduction


    Contractbook turns static contracts into a database for your entire

    organization, unlocking the full value of your data while ensuring transparency

    and a seamless data flow between tools. Our API allows you to generate pre-filled drafts from any data source, stay

    updated on contract activity, and quickly export an overview of all contracts

    and drafts. > Note: Whenever your user needs to access the Contractbook editor, we expect

    > you to redirect their browser to the appropriate page. ## Migration from Public API v2


    Public API v3 introduces several breaking changes focused on simplifying the document and template structure. ### Restructured parties and signees


    The most significant change is the restructuring of document parties and signees. In v2, you had two separate but overlapping structures that created data redundancy:


    - `visible_parties`: Basic party info (name, address, type, reference, number)

    - `parties`: Signee details with redundant company/personal fields


    In v3, this has been unified and simplified:

    - **v2 `visible_parties`** → **v3 `parties`**: Contains essential party information

    - **v2 `parties`** → **v3 `signees`**: Nested within parties, contains only signee-related information


    **Field changes in the restructuring:**

    - `personal_title` (personal party) and `representative_title` (company party) → unified as `title` in signees

    - `company_representative` (company party) → `full_name` in signees

    - **Removed redundant fields**: `company_address`, `company_name`, `company_number`, `personal_number` (already available in the parent party)

    - **Removed internal references**: `user_id`, `profile_id`, `visible_party_id`


    **Signee structure** now contains only signee-related information:

    - `email`, `full_name`, `title`,`order`, `signature_verification_methods`

    - `signed_at`, `opened_at`, `rejected_at`, `changes_requested_at`


    ### Other removed attributes**


    **From documents:**

    - `folders` (folders are deprecated in favor of workspaces)


    **From templates:**

    - `target_shared_folder` (folders are deprecated in favor of workspaces)

    - Party structure follows the same pattern as documents


    ### Migration strategy


    When migrating from v2 to v3:


    1. **Update all endpoint URLs** by replacing `/v2/` with `/v3/`

    2. **Restructure party data** in your requests and response handling:

    - Map `visible_parties` to `parties`

    - Move signee information from old `parties` to `signees` array within each party

    3. **Remove deprecated fields** from your payloads (company_*, personal_*, representative_* fields)

    4. **Update response parsing** to handle the new nested signee structure

    5. **Test thoroughly** as the party/signee relationship is now more structured


    ## Authentication


    To use the API, you''ll need to get your own API key. For that, log into

    Contractbook and navigate to your profile settings. There you can create an API

    key which is going to be shown only once upon creation. There are two environments for API:


    * **staging**: this environment should

    only be used for testing purposes only. Here''s where you''ll be spending most of

    your time when developing new features for your app(s).'
  title: Contractbook Attachments API
  version: '3.0'
  x-logo:
    altText: Contractbook logo
    backgroundColor: '#FFFFFF'
    url: public/contractbook-logo.svg
servers:
- description: Production server
  url: https://api.contractbook.com/v3/
  variables: {}
- description: Staging server
  url: https://api-staging.contractbook.com/v3/
  variables: {}
security: []
tags:
- name: Attachments
paths:
  /upload:
    post:
      callbacks: {}
      deprecated: false
      description: Uploads an attachment
      operationId: create_attachment
      parameters: []
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/FileUploadRequest'
        description: Attachment data
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileUploadResponse'
          description: Attachment
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: Unauthorized
      summary: Upload an attachment
      tags:
      - Attachments
components:
  schemas:
    FileUploadResponse:
      additionalProperties: false
      description: Document attachment
      properties:
        original:
          description: URL of the attachment
          example: http://example.com/image.png
          format: uri
          type: string
        preview:
          description: 'If the original is a document, this field will hold an list URL with image

            previews of each page

            '
          items:
            example: http://example.com/image.png
            format: uri
            type: string
          type: array
      required:
      - original
      title: FileUploadResponse
      type: object
    UnauthorizedError:
      additionalProperties: false
      description: Unauthorized
      properties:
        error:
          additionalProperties: false
          properties:
            message:
              description: Error details message
              example: Unauthorized
              type: string
            type:
              description: HTTP error message
              example: unauthorized
              type: string
          readOnly: true
          required:
          - type
          - message
          type: object
      readOnly: true
      required:
      - error
      title: UnauthorizedError
      type: object
    FileUploadRequest:
      additionalProperties: false
      description: Payload with file
      properties:
        file:
          description: '**Accepted MIME types:**

            application/msword,

            application/pdf,

            application/vnd.ms-excel,

            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,

            application/vnd.openxmlformats-officedocument.wordprocessingml.document,

            application/zip,

            image/jpeg,

            image/png,

            text/csv,

            text/plain

            '
          format: binary
          type: string
      required:
      - file
      title: FileUploadRequest
      type: object
    BadRequestError:
      additionalProperties: false
      description: Bad Request
      properties:
        error:
          additionalProperties: false
          properties:
            failures:
              description: List of request errors
              items:
                additionalProperties: false
                description: Error description
                properties:
                  detail:
                    description: Details of the error
                    type: string
                  source:
                    additionalProperties: false
                    properties:
                      pointer:
                        description: Failing field name or reference
                        type: string
                    required:
                    - pointer
                    type: object
                  title:
                    description: Title of the error
                    type: string
                required:
                - title
                - detail
                type: object
              type: array
            message:
              description: Error details message
              example: Bad Request
              type: string
            type:
              description: HTTP error message
              example: bad_request
              type: string
          readOnly: true
          required:
          - type
          - message
          type: object
      readOnly: true
      required:
      - error
      title: BadRequestError
      type: object
  securitySchemes:
    authorization:
      scheme: bearer
      type: http
x-provenance:
  method: harvested
  publisher: Contractbook
  source: https://api.contractbook.com/v3/docs/public//v3/openapi-v3.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)