Contractbook Automations 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 Automations 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: Automations
paths:
  /automations:
    get:
      callbacks: {}
      deprecated: false
      description: ''
      operationId: list_automations
      parameters:
      - description: ''
        in: query
        name: trigger_type
        required: true
        schema:
          enum:
          - webhook_trigger
          - hubspot_contractbook_automation_triggered
          - hubspot_deal_stage_changed
          - contract_signed
          - contract_verified_ai
          - contract_viewed
          - data_field_date_reached
          - data_field_updated
          - draft_created
          - draft_updated
          - drafter_questionnaire_completed
          - sent_for_signature
          - task_due_date_reached
          - task_is_done
          - pipedrive_deal_stage_changed
          - salesforce_flow_executed
          - salesforce_opportunity_stage_changed
          type: string
      - description: ''
        in: query
        name: trigger_filter
        schema:
          properties:
            object_type:
              example: Opportunity
              type: string
            record_type_id:
              example: 0060900000FpKajAAF
              type: string
          type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationIndexResponse'
          description: List of automations
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableContentError'
          description: Unprocessable request
      summary: Get a list of automations
      tags:
      - Automations
  /automations/{id}/run:
    post:
      callbacks: {}
      deprecated: false
      description: 'Note: Currently for this endpoint we only support those automations that have "Salesforce flow is executed" as a trigger'
      operationId: run_automation
      parameters:
      - description: Automation ID
        in: path
        name: id
        required: true
        schema:
          example: 1e013958-867e-43fb-8210-c98ab139beb6
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutomationRunRequest'
        description: Automation run parameters
        required: false
      responses:
        '204':
          content:
            application/json: {}
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableContentError'
          description: Unprocessable request
      summary: Runs a specific automation
      tags:
      - Automations
components:
  schemas:
    ForbiddenError:
      additionalProperties: false
      description: Forbidden
      properties:
        error:
          additionalProperties: false
          properties:
            message:
              description: Error details message
              example: Forbidden
              type: string
            type:
              description: HTTP error message
              example: forbidden
              type: string
          readOnly: true
          required:
          - type
          - message
          type: object
      readOnly: true
      required:
      - error
      title: ForbiddenError
      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
    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
    AutomationRunRequest:
      additionalProperties: false
      description: Payload that will be passed to the automation when running it
      properties:
        attachments:
          description: Publicly accesible links to files
          example:
          - https://contractbook.com/file.pdf
          items:
            type: string
          type: array
        contacts:
          description: List of Salesforce Contact IDs
          example:
          - 0030900000Ujt0BAAR
          - 0030900000Ujt0GAAR
          items:
            type: string
          type: array
        object_id:
          example: 0060900000FpKajAAF
          type: string
        object_type:
          example: Opportunity
          type: string
      required:
      - object_type
      - object_id
      title: AutomationRunRequest
      type: object
    AutomationIndexResponse:
      additionalProperties: false
      description: A list of automations
      properties:
        automations:
          items:
            additionalProperties: false
            description: Preview of an automation
            properties:
              id:
                description: Automation ID
                example: 6b6314b6-56f9-4454-869a-84c96682cea9
                format: uuid
                maxLength: 36
                minLength: 36
                pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                type: string
              inserted_at:
                description: Date and time when the automation was created
                format: date-time
                type: string
              name:
                description: Automation Name
                example: Generate Employment agreement
                type: string
              published:
                description: Is automation published?
                example: true
                type: boolean
              updated_at:
                description: Date and time when the automation was las updated
                format: date-time
                type: string
            title: AutomationPreview
            type: object
          type: array
      title: AutomationIndexResponse
      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
    UnprocessableContentError:
      additionalProperties: false
      description: Unprocessable Content
      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: Unprocessable Content
              type: string
            type:
              description: HTTP error message
              example: unprocessable_entity
              type: string
          readOnly: true
          required:
          - type
          - message
          type: object
      readOnly: true
      required:
      - error
      title: UnprocessableContentError
      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)