Contractbook Templates 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 Templates 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: Templates
paths:
  /templates:
    get:
      callbacks: {}
      deprecated: false
      description: Gets a list of templates
      operationId: get_templates
      parameters:
      - description: Exclude templates from Spaces
        in: query
        name: exclude_spaces
        schema:
          default: false
          example: 'true'
          type: boolean
      - description: Exclude templates not connected to an external application according to the given rules
        explode: true
        in: query
        name: integration_filter
        schema:
          properties:
            application:
              enum:
              - salesforce
              required: true
              type: string
            object_type:
              enum:
              - opportunity
              - account
              - contact
              type: string
            record_type:
              type: string
          type: object
        style: deepObject
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateIndexResponse'
          description: List of templates
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: Unauthorized
      summary: Get a list of templates
      tags:
      - Templates
  /templates/{id}:
    get:
      callbacks: {}
      deprecated: false
      description: Gets a template by ID
      operationId: get_template
      parameters:
      - description: Template ID
        in: path
        name: id
        required: true
        schema:
          example: 1e013958-867e-43fb-8210-c98ab139beb6
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateShowResponse'
          description: Template
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
      summary: Get a template
      tags:
      - Templates
components:
  schemas:
    NotFoundError:
      additionalProperties: false
      description: Not Found
      properties:
        error:
          additionalProperties: false
          properties:
            message:
              description: Error details message
              example: Not Found
              type: string
            type:
              description: HTTP error message
              example: not_found
              type: string
          readOnly: true
          required:
          - type
          - message
          type: object
      readOnly: true
      required:
      - error
      title: NotFoundError
      type: object
    TemplateShowResponse:
      additionalProperties: false
      description: Full template information
      properties:
        template:
          additionalProperties: false
          properties:
            attachments:
              description: Attached files
              items:
                additionalProperties: false
                description: Template attachment
                properties:
                  original:
                    description: URL of the attachment
                    format: uri
                    type: string
                  preview:
                    description: 'If the original is a template, this field will hold an list URL with image

                      previews of each page

                      '
                    items:
                      description: Preview URL
                      format: uri
                      type: string
                    type: array
                required:
                - original
                type: object
              type: array
            company_logo_url:
              description: The URL of the logo shown in the document
              format: uri
              type:
              - string
              - 'null'
            created_at:
              description: The date and time when the template was created
              format: date-time
              type: string
            data_fields:
              description: Data fields in the template
              items:
                description: Data field
                properties:
                  config:
                    additionalProperties: false
                    description: Additional config for this data field. Contains `options` for `select`, or `label` for `checkbox`.
                    properties:
                      label:
                        required: false
                        type:
                        - string
                        - 'null'
                      options:
                        items:
                          type: string
                        required: false
                        type: array
                    type: object
                  description:
                    description: Description
                    type:
                    - string
                    - 'null'
                  formatting:
                    additionalProperties: false
                    description: Formatting
                    properties:
                      fractional:
                        type:
                        - boolean
                        - 'null'
                      grouping:
                        enum:
                        - ''
                        - dot
                        - comma
                        - space
                        type:
                        - string
                        - 'null'
                    type:
                    - object
                    - 'null'
                  id:
                    description: Unique ID
                    format: uuid
                    pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                    type: string
                  name:
                    description: Name
                    type: string
                  required:
                    description: Whether this data field must be filled to send the document for signature
                    type: boolean
                  source:
                    description: Source of data for this data field
                    enum:
                    - drafter_questionnaire
                    - ai
                    - salesforce
                    type:
                    - string
                    - 'null'
                  source_mapping:
                    description: Integration data mapping for this data field. Revealed only when connected to the same integration instance.
                    type:
                    - string
                    - 'null'
                  source_sync_type:
                    description: Integration sync mode for this data field. Revealed only when connected to the same integration instance.
                    enum:
                    - downstream
                    - upstream
                    - bidirectional
                    type:
                    - string
                    - 'null'
                  type:
                    description: Type
                    enum:
                    - text
                    - number
                    - date
                    - select
                    - checkbox
                    type: string
                  value:
                    description: Value
                    type:
                    - string
                    - 'null'
                required:
                - id
                - value
                - formatting
                - description
                - config
                - name
                - type
                - required
                - source
                - source_mapping
                - source_sync_type
                title: DataField
                type: object
              type: array
            default_message:
              description: A default message that will get copied to the draft
              type: string
            description:
              description: Description of the template
              type: string
            id:
              description: Template ID
              format: uuid
              pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
              type: string
            language:
              description: Language
              type: string
            owned:
              description: Tells if the templates is owned by the requesting user
              type: boolean
            owner_id:
              description: Template owner ID
              format: uuid
              pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
              type: string
            parties:
              description: Parties and signees
              items:
                additionalProperties: false
                description: Party
                properties:
                  address:
                    description: Address
                    example: 123 Main Street
                    type:
                    - string
                    - 'null'
                  id:
                    description: Unique ID
                    format: uuid
                    pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                    type:
                    - string
                    - 'null'
                  name:
                    description: Name
                    example: Jane Doe
                    type:
                    - string
                    - 'null'
                  number:
                    description: Company's VAT number or CVR
                    type:
                    - string
                    - 'null'
                  reference:
                    description: How the party will be referred to in the document
                    example: Recipient
                    type:
                    - string
                    - 'null'
                  signees:
                    description: Party's signees
                    items:
                      additionalProperties: false
                      properties:
                        changes_requested_at:
                          description: Date and time when the signee requested changes to the document
                          format: date-time
                          readOnly: true
                          type:
                          - string
                          - 'null'
                        email:
                          description: Signee's email address
                          format: email
                          type:
                          - string
                          - 'null'
                        full_name:
                          description: Signee's full name
                          example: Jane Doe
                          type:
                          - string
                          - 'null'
                        id:
                          description: Unique ID
                          format: uuid
                          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                          type:
                          - string
                          - 'null'
                        opened_at:
                          description: Date and time when the signee opened the document
                          format: date-time
                          readOnly: true
                          type:
                          - string
                          - 'null'
                        order:
                          description: Signee's signing order. When the signing order mode is set to `grouped`, then this number represents the signee's group number.
                          minimum: 0
                          type: integer
                        rejected_at:
                          description: Date and time when the signee rejected the document
                          format: date-time
                          readOnly: true
                          type:
                          - string
                          - 'null'
                        signature_verification_methods:
                          description: List of allowed signature types for the signee
                          example:
                          - sms
                          - basic
                          - wet_signature
                          items:
                            enum:
                            - sms
                            - basic
                            - wet_signature
                            - criipto_dk_mitid_substantial
                            - criipto_dk_mitid_business
                            - criipto_no_bankid
                            - criipto_se_bankid_same_device
                            - criipto_se_bankid_another_device
                            - criipto_fi_bankid
                            - criipto_fi_bankid_mobile
                            type: string
                          type:
                          - array
                          - 'null'
                        signed_at:
                          description: Date and time when the signee signed the document
                          format: date-time
                          readOnly: true
                          type:
                          - string
                          - 'null'
                        title:
                          description: Signee's title
                          example: Software Engineer
                          type:
                          - string
                          - 'null'
                      type: object
                    type: array
                  type:
                    description: Type
                    enum:
                    - personal
                    - company
                    type: string
                type: object
              type: array
            signing_order_mode:
              description: The signing order mode. When it's set to grouped, each signee in `parties.signees`, should have the order field set to the group's number starting from 0.
              enum:
              - random
              - strict
              - grouped
              type:
              - string
              - 'null'
            slug:
              description: Template slug
              type:
              - string
              - 'null'
            template:
              description: Template content
              type: object
            title:
              description: Title
              type: string
            updated_at:
              description: The date and time of the last time the template was edited
              format: date-time
              type: string
          required:
          - attachments
          - company_logo_url
          - created_at
          - default_message
          - description
          - data_fields
          - id
          - language
          - owned
          - owner_id
          - parties
          - signing_order_mode
          - slug
          - title
          - updated_at
          type: object
      required:
      - template
      title: TemplateShowResponse
      type: object
    TemplateIndexResponse:
      additionalProperties: false
      description: List of template previews
      properties:
        templates:
          description: List of template previews
          items:
            additionalProperties: false
            properties:
              created_at:
                description: The date and time when the template was created
                format: date-time
                type: string
              description:
                description: Description of the template
                type: string
              id:
                description: Template ID
                format: uuid
                pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                type: string
              language:
                description: Language
                type: string
              location:
                properties:
                  id:
                    description: ID of location
                    pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$|^root$
                    type: string
                  name:
                    type: string
                  type:
                    description: Where the template is located
                    enum:
                    - none
                    - folder
                    - workspace
                    - category
                    type: string
                type: object
              owned:
                description: Tells if the templates is owned by the requesting user
                type: boolean
              owner_id:
                description: Template owner ID
                format: uuid
                pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                type: string
              slug:
                description: Template slug
                type:
                - string
                - 'null'
              title:
                description: Template title
                type:
                - string
                - 'null'
              updated_at:
                description: The date and time of the last time the template was edited
                format: date-time
                type: string
            required:
            - created_at
            - description
            - id
            - language
            - owned
            - owner_id
            - slug
            - title
            - updated_at
            type: object
          type: array
      required:
      - templates
      title: TemplateIndexResponse
      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
  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)