SpotDraft V2.1 Contract Metadata Definitions API

openapi: 3.2.0
info:
  title: SpotDraft V2.1 Contract Metadata Definitions API
  version: v1
  x-version: v1
  x-logo:
    url: https://cdn.spotdraft.com/assets/logo-black-new.png
    backgroundColor: transparent
    altText: SpotDraft Logo
    href: https://spotdraft.com
  x-favicon: https://cdn.spotdraft.com/assets/favicon.png
  x-footer: © SpotDraft Inc. All rights reserved.
  description: '# SpotDraft Public API


    Welcome to the **SpotDraft Public API**.'
servers:
- url: https://api.eu.spotdraft.com
  description: Europe
- url: https://api.in.spotdraft.com
  description: India
- url: https://api.us.spotdraft.com
  description: United States
- url: https://api.me.spotdraft.com
  description: Middle East
tags:
- name: V2.1 Contract Metadata Definitions
  description: List workspace-level or contract-type-level contract metadata definitions. Legacy API paths may still use key-pointer naming.
paths:
  /api/v2.1/public/key_pointers/:
    get:
      operationId: v2.1_public_key_pointers_retrieve
      description: Lists the contract metadata definitions configured for the workspace. These definitions describe which metadata fields exist; they do not return values for a specific contract. The underlying API paths still use legacy key-pointer naming for backward compatibility.
      summary: List Contract Metadata Definitions
      parameters:
      - in: query
        name: contract_type_id
        schema:
          type: integer
        description: ID of the Contract type.
        required: true
      - in: query
        name: is_external
        schema:
          type: boolean
        description: Set to True to get only key pointers from external sections.
      tags:
      - V2.1 Contract Metadata Definitions
      security:
      - ClientId: []
        ClientSecret: []
      - OAuthBearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyPointerListDomainModel'
          description: Contract metadata
      x-tagGroup: Workflow
  /api/v2.1/public/key_pointers/field-name-mapping/:
    post:
      operationId: v2.1_public_key_pointers_field_name_mapping_create
      description: Returns mappings between template **field names** and contract metadata **labels** for the workspace, optionally scoped by `contract_id` or `contract_type_id`. Used when renaming template variables or aligning metadata across versions.
      summary: Map Template Fields to Contract Metadata
      tags:
      - V2.1 Contract Metadata Definitions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListFieldNameMappingViewRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ListFieldNameMappingViewRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ListFieldNameMappingViewRequest'
      security:
      - ClientId: []
        ClientSecret: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldNameMappingListDomainModel'
          description: Field name mapping rows for the request filters.
      x-tagGroup: Workflow
components:
  schemas:
    KeyPointerListDomainModel:
      title: KeyPointerListDomainModel
      type: array
      items:
        title: KeyPointerDomainModel
        type: object
        properties:
          id:
            title: Id
            description: The ID of this Key Pointer. Globally unique.
            type: integer
          descriptors:
            title: Descriptors
            description: The list of descriptors clarifying what type of data this Key Pointer stores. Useful to ensure valid data is being passed.
            type: array
            items:
              title: CfPublicDescriptor
              description: 'A descriptor to describe the CommonForm blank.

                Used for the public API.'
              type: object
              properties:
                display_label:
                  title: Display Label
                  description: The label to be displayed to users
                  type: string
                variable:
                  title: Variable
                  description: The name of the variable. In case this is a nested variable, The name will include a `.`
                  type: string
                type:
                  title: CfPublicDescriptorType
                  description: The type of field. The type changes the values to be sent. See <a href='#operation/v2_public_contracts_create'>V2 Create Contract</a>
                  enum:
                  - string
                  - boolean
                  - int
                  - float
                  - array of strings
                  - array of options
                  - enum
                  - date
                  - repeating
                  - array of files
                  type: string
                help_text:
                  title: Help Text
                  description: Help text which can be shown to the user if needed.
                  type: string
                parent_variable:
                  title: Parent Variable
                  description: For nested variables, this is the name of the variable which should be an object with the values set in it
                  type: string
                options:
                  title: Options
                  description: For `enum` and `arrary of options` types, this is the list of options to be shown to the user.
                  type: array
                  items:
                    title: CfOption
                    type: object
                    properties:
                      label:
                        title: Label
                        description: The label of this Option as shown to the user.
                        type: string
                      value:
                        title: Value
                        description: The value of this Option as sent to the API.
                    required:
                    - label
                required:
                  title: Required
                  description: Describes if this variable is required. In case its nested (if `parent_variable` is set) the entire object can be unset if `parent_required` is unset or false
                  default: true
                  type: boolean
                parent_required:
                  title: Parent Required
                  description: Only set if `parent_variable` is set. If set to true then the parent variable is required. Thus the nested object for the parent should be set. The required-ness of the nested variables is based on the `required` field
                  type: boolean
                default_value:
                  title: Default Value
                  description: The default value for this field, if any
                parent_type:
                  title: Parent Type
                  description: The SpotDraft type of the parent variable this field is a child for, if any.
                  type: string
                child_variable:
                  title: Child Variable
                  description: The name of the child field. This is only set if this variable is a child field.
                  type: string
                question:
                  title: Question
                  description: Question for this attribute.
                  type: string
                attributes:
                  title: Attributes
                  description: Describes the shape of the object for repeating types. Only set when `type` is `repeating`.
                  type: array
                  items:
                    title: CfPublicDescriptorBase
                    type: object
                    properties:
                      display_label:
                        title: Display Label
                        description: The label to be displayed to users
                        type: string
                      variable:
                        title: Variable
                        description: The name of the variable. In case this is a nested variable, The name will include a `.`
                        type: string
                      type:
                        title: CfPublicDescriptorType
                        description: The type of field. The type changes the values to be sent. See <a href='#operation/v2_public_contracts_create'>V2 Create Contract</a>
                        enum:
                        - string
                        - boolean
                        - int
                        - float
                        - array of strings
                        - array of options
                        - enum
                        - date
                        - repeating
                        - array of files
                        type: string
                      help_text:
                        title: Help Text
                        description: Help text which can be shown to the user if needed.
                        type: string
                      parent_variable:
                        title: Parent Variable
                        description: For nested variables, this is the name of the variable which should be an object with the values set in it
                        type: string
                      options:
                        title: Options
                        description: For `enum` and `arrary of options` types, this is the list of options to be shown to the user.
                        type: array
                        items:
                          title: CfOption
                          type: object
                          properties:
                            label:
                              title: Label
                              description: The label of this Option as shown to the user.
                              type: string
                            value:
                              title: Value
                              description: The value of this Option as sent to the API.
                          required:
                          - label
                      required:
                        title: Required
                        description: Describes if this variable is required. In case its nested (if `parent_variable` is set) the entire object can be unset if `parent_required` is unset or false
                        default: true
                        type: boolean
                      parent_required:
                        title: Parent Required
                        description: Only set if `parent_variable` is set. If set to true then the parent variable is required. Thus the nested object for the parent should be set. The required-ness of the nested variables is based on the `required` field
                        type: boolean
                      default_value:
                        title: Default Value
                        description: The default value for this field, if any
                      parent_type:
                        title: Parent Type
                        description: The SpotDraft type of the parent variable this field is a child for, if any.
                        type: string
                      child_variable:
                        title: Child Variable
                        description: The name of the child field. This is only set if this variable is a child field.
                        type: string
                      question:
                        title: Question
                        description: Question for this attribute.
                        type: string
                    required:
                    - display_label
                    - variable
                    - type
              required:
              - display_label
              - variable
              - type
          section:
            title: Section
            type: object
            properties:
              id:
                title: Id
                description: The ID of this section. Gobally Unique.
                type: integer
              section_type:
                title: Section Type
                description: Defines what kind of section this is. SpotDraft has inbuilt sections and users can also define additional sections. Valid values are `USER_DEFINED` and `SYSTEM_DEFINED`
                type: string
              name:
                title: Name
                description: The name of the section as shown to users.
                type: string
            required:
            - id
            - section_type
            - name
            description: The section which this key pointer belongs to.
        required:
        - id
        - descriptors
        - section
    FieldNameMappingDomainModel:
      description: Domain model for field name mapping.
      properties:
        id:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          description: The ID of the field name mapping
          title: Id
        old_field_name:
          description: The original template field name
          title: Old Field Name
          type: string
        new_field_name:
          description: The new template field name
          title: New Field Name
          type: string
        tenant_workspace_id:
          description: The workspace ID this mapping belongs to
          title: Tenant Workspace Id
          type: integer
        contract_type_id:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          description: The contract type ID this mapping belongs to
          title: Contract Type Id
        created:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          default: null
          description: Creation timestamp
          title: Created
        modified:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          default: null
          description: Last modification timestamp
          title: Modified
        data_type:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: The data type of the key pointer which was linked to the old_field_name attribute
          title: Data Type
        new_field_name_label:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: New Field Name Label
      required:
      - old_field_name
      - new_field_name
      - tenant_workspace_id
      title: FieldNameMappingDomainModel
      type: object
    ListFieldNameMappingViewRequest:
      title: ListFieldNameMappingViewRequest
      type: object
      properties:
        contract_id:
          title: Contract Id
          description: Optional contract id to scope the mapping lookup to a specific contract instance.
          type: integer
        contract_type_id:
          title: Contract Type Id
          description: Optional contract type id to scope the mapping lookup to a specific workflow or template family.
          type: integer
        old_field_names:
          title: Old Field Names
          description: Optional list of legacy template field names to translate into current contract metadata labels.
          type: array
          items:
            type: string
        new_field_names:
          title: New Field Names
          description: Optional list of current template field names to map back to existing contract metadata labels.
          type: array
          items:
            type: string
    FieldNameMappingListDomainModel:
      description: Domain model for list of field name mappings.
      properties:
        items:
          items:
            $ref: '#/components/schemas/FieldNameMappingDomainModel'
          title: Items
          type: array
      title: FieldNameMappingListDomainModel
      type: object
  securitySchemes:
    ClickwrapId:
      type: apiKey
      in: header
      name: clickwrap-id
      description: Public clickwrap identifier header.
    ClientId:
      type: apiKey
      name: client-id
      in: header
    ClientSecret:
      type: apiKey
      name: client-secret
      in: header
    NativeIntegrationBasic:
      type: http
      scheme: basic
      description: HTTP Basic auth for supported native integrations. Send base64(client_id:client_secret) in the Authorization header.
    OAuthBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 bearer token for workspace user access.
    Origin:
      type: apiKey
      in: header
      name: Origin
      description: Browser origin header used for clickwrap domain validation.
x-logo:
  url: https://cdn.spotdraft.com/assets/logo-black-new.png
  backgroundColor: transparent
  altText: SpotDraft Logo
  href: https://spotdraft.com
x-tagGroups:
- name: Contracts
  tags:
  - V2.1 Contract APIs
  - V2 Contract APIs
  - V1 Contract APIs
  - V2.1 Contract Approvals
  - V2 Contract Approvals
  - V2.1 Contract Activity
  - V2 Contract Activity
  - V2.1 Contract Invitations
  - V2 Contract Invitations
  - V2.1 Contract Metadata Values
  - V2 Contract Metadata Values
  - V2.1 Contract External Metadata
  - V2.1 Contract Notes
  - V2 Contract Notes
  - V2.1 Contract Obligations
  - V2.1 Contract Facets
  - V2.1 Contract Versions
  - V2 Contract Versions
  - V2.1 Recipients
  - V2 Recipients
- name: Clickwrap
  tags:
  - V2.1 Clickwrap
- name: Legal Intake
  tags:
  - V1 Legal Intake
- name: Workflow
  tags:
  - V2.1 Contract Metadata Definitions
  - V2 Contract Metadata Definitions
  - V2.1 Contract Types
  - V2 Contract Types
  - V2.1 Templates
  - V2 Templates
  - V1 Templates
- name: Platform
  tags:
  - V2.1 Users
  - V2 Users
  - V1 Users
  - V2.1 Counterparties
  - V2 Counterparties
  - V2.1 Organizations
  - V2 Organizations
  - V1 Obligation Types
  - V1 Native Integrations
  - V2.1 Workspace Files
  - V2.1 Tasks and Reminders
  - V2 Tasks and Reminders
  - V2.1 Webhooks
  - V1 Webhooks
  - V1 Emails
  - V2.1 Analytics Query
  - V2.1 Workspaces
  - V2.1 Workspace Tags
- name: Sidebar
  tags:
  - V2.1 Sidebar