SpotDraft V2.1 Contract Approvals API

openapi: 3.2.0
info:
  title: SpotDraft V2.1 Contract Approvals 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 Approvals
  description: Review contract approvals, approvers, and approval actions across public API versions.
paths:
  /api/v2.1/public/contracts/approvals/{contract_id}/:
    get:
      operationId: v2.1_public_contracts_approvals_retrieve
      description: Returns the approval steps currently configured or in progress for the contract. Use this to show approval status, approvers, and progression before taking contract actions that depend on approvals.
      summary: Get Contract Approvals
      parameters:
      - in: path
        name: contract_id
        schema:
          type: string
        description: ID of the Contract. Should be of the form T-123 or H-123. T stands for Template contracts and H stands for Historical contracts.
        required: true
      tags:
      - V2.1 Contract Approvals
      security:
      - ClientId: []
        ClientSecret: []
      - OAuthBearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicContractApprovalListResponse'
          description: Success
      x-tagGroup: Contracts
    post:
      operationId: v2.1_public_contracts_approvals_create
      description: 'Create and send ad-hoc approvals for a contract.


        Notes:

        - This endpoint supports contracts on Approval V4.

        - Contracts configured for Approval V5 can fail with `SD_CONTRACT_APPROVALS_00001`.

        - The request can fail when another approval group is already in progress (`SD_CONTRACTS_00152`).'
      summary: Create and Send Adhoc Approvals
      parameters:
      - in: path
        name: contract_id
        schema:
          type: string
        description: ID of the Contract. Should be of the form T-123 or H-123. T stands for Template contracts and H stands for Historical contracts.
        required: true
      tags:
      - V2.1 Contract Approvals
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalCreateContractApprovalRequestList'
            examples:
              Example1:
                value:
                  approvals:
                  - name: Legal Approval
                    approver_user_id: 10324
                    notes: Please take a look need your approval.
                    order: 1
                  - name: Finance team Approval
                    approver_role_id: 60414
                    notes: Hi team need your approval on this contract.
                    order: 2
                summary: Example 1
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ExternalCreateContractApprovalRequestList'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ExternalCreateContractApprovalRequestList'
        required: true
      security:
      - ClientId: []
        ClientSecret: []
      - OAuthBearer: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalApprovalListResponse'
              examples:
                Example1:
                  value:
                  - id: 1001
                    contract_id: 211270
                    name: Legal Approval
                    approver_user_id: 10324
                    approver_role_id: null
                    is_sent: true
                    notes: Please take a look need your approval.
                    order: 1
                  - id: 1002
                    contract_id: 211270
                    name: Finance team Approval
                    approver_user_id: null
                    approver_role_id: 60414
                    is_sent: true
                    notes: Hi team need your approval on this contract.
                    order: 2
                  summary: Example 1
          description: Success
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                  status_code:
                    type: integer
                  code:
                    type: string
                  message:
                    type: string
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                  status_code:
                    type: integer
                  code:
                    type: string
                  message:
                    type: string
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                  status_code:
                    type: integer
                  code:
                    type: string
                  message:
                    type: string
          description: Not Found
      x-tagGroup: Contracts
components:
  schemas:
    PublicContractApprovalListResponse:
      title: PublicContractApprovalListResponse
      type: object
      properties:
        results:
          title: Results
          type: array
          items:
            title: PublicContractApprovalExpandedResponse
            type: object
            properties:
              approval_actions:
                title: Approval Actions
                type: array
                items:
                  title: ContractApprovalAction
                  type: object
                  properties:
                    status:
                      title: ContractApprovalV2Status
                      description: Status of this approval action
                      enum:
                      - APPROVED
                      - REJECTED
                      - SUGGESTED
                      - SKIPPED
                      type: string
                    notes:
                      title: Notes
                      description: Notes for this approval action
                      type: string
                    created:
                      title: Created
                      description: Datetime at which this action was taken
                      type: string
                      format: date-time
                    latest:
                      title: Latest
                      description: This will be True if this is latest approval action
                      type: boolean
                  required:
                  - status
                  - created
                  - latest
              approval:
                title: PublicContractRequiredApprovalResponse
                type: object
                properties:
                  id:
                    title: Id
                    description: Id of the approval
                    type: integer
                  contract_id:
                    title: Contract Id
                    description: Id of contract to which this approval belongs
                    type: integer
                  approval_name:
                    title: Approval Name
                    description: Approval Name
                    type: string
                  approval_type:
                    title: ApprovalV2Type
                    description: Type of approval
                    enum:
                    - PRE_SEND
                    - PRE_SIGN
                    - AD_HOC
                    - APPROVAL_V5
                    type: string
                  org_user:
                    title: Org User
                    type: object
                    properties:
                      id:
                        title: Id
                        description: Id of the user
                        type: integer
                      name:
                        title: Name
                        description: Name of the user
                        type: string
                      email:
                        title: Email
                        description: Email of the user
                        type: string
                    required:
                    - id
                    - name
                    - email
                    description: User who is supposed to approve this approval
                  sent_for_approval:
                    title: Sent For Approval
                    description: Whether this apporval has been sent or not
                    type: boolean
                  last_sent_at:
                    title: Last Sent At
                    description: Datetime when this approval was last sent at
                    type: string
                    format: date-time
                  notes:
                    title: Notes
                    description: Notes for this approval
                    type: string
                  created_by_org_user:
                    title: Created By Org User
                    type: object
                    properties:
                      id:
                        title: Id
                        description: Id of the user
                        type: integer
                      name:
                        title: Name
                        description: Name of the user
                        type: string
                      email:
                        title: Email
                        description: Email of the user
                        type: string
                    required:
                    - id
                    - name
                    - email
                    description: User who created this approval
                  status:
                    title: RequiredApprovalStatus
                    description: Current status of this approval
                    enum:
                    - NOT_STARTED
                    - PENDING
                    - REJECTED
                    - SUGGESTED
                    - APPROVED
                    - SKIPPED
                    type: string
                required:
                - id
                - contract_id
                - approval_name
                - approval_type
                - sent_for_approval
                - created_by_org_user
                - status
            required:
            - approval_actions
            - approval
      required:
      - results
    ExternalApprovalListResponse:
      title: ExternalApprovalListResponse
      type: array
      items:
        title: ExternalApprovalResponse
        type: object
        properties:
          id:
            title: Id
            type: integer
          contract_id:
            title: Contract Id
            description: The id of the contract to which the approval belongs.
            type: integer
          name:
            title: Name
            description: The name that will be used to represent the approval in Spotdraft.
            type: string
          approver_user_id:
            title: Approver User Id
            description: The ID of the user who has to take action on this Approval. Either `approver_user_id` or `approver_role_id` will always be set, but not both.
            type: integer
          approver_role_id:
            title: Approver Role Id
            description: The ID of the role that has to take action on this Approval. Either `approver_user_id` or `approver_role_id` will always be set, but not both.
            type: integer
          is_sent:
            title: Is Sent
            description: Set to true when the approval request has been sent to the approver.
            type: boolean
          notes:
            title: Notes
            description: The message that will be sent to the approver along with the approval request.
            type: string
          order:
            title: Order
            description: The order denotes the sequence in which the approval requests will be sent to the approver of each approval. Lower values of order are sent before higher values of order. Approvals with same order will be sent to the approver at the same time.
            type: integer
        required:
        - id
        - contract_id
        - name
        - is_sent
      examples:
      - - id: 1001
          contract_id: 211270
          name: Legal Approval
          approver_user_id: 10324
          approver_role_id: null
          is_sent: true
          notes: Please take a look need your approval.
          order: 1
        - id: 1002
          contract_id: 211270
          name: Finance team Approval
          approver_user_id: null
          approver_role_id: 60414
          is_sent: true
          notes: Hi team need your approval on this contract.
          order: 2
    ExternalCreateContractApprovalRequestList:
      title: ExternalCreateContractApprovalRequestList
      type: object
      properties:
        approvals:
          title: Approvals
          description: List of information that needs to be provided in order to create multiple Approvals.
          type: array
          items:
            title: ExternalCreateContractApprovalRequest
            type: object
            properties:
              name:
                title: Name
                description: The name that will be used to represent the approval in Spotdraft.
                type: string
              approver_user_id:
                title: Approver User Id
                description: The ID of the user who has to take action on this Approval. Either `approver_user_id` or `approver_role_id` must be set, but not both. Use the [Get User List](#tag/v21-users/GET/api/v2.1/public/auth/users/) API to get the user ID.
                type: integer
              approver_role_id:
                title: Approver Role Id
                description: The ID of the role that has to take action on this Approval. Either `approver_user_id` or `approver_role_id` must be set, but not both. Use the [Get Active Roles](#tag/v21-users/GET/api/v2.1/public/auth/roles/) API to get the role ID.
                type: integer
              notes:
                title: Notes
                description: The message that will be sent to the approver along with the approval request.
                type: string
              order:
                title: Order
                description: The order denotes the sequence in which the approval requests will be sent to the approver of each approval. Lower values of order are sent before higher values of order. Approvals with same order will be sent to the approver at the same time.
                type: integer
            required:
            - name
            - notes
      required:
      - approvals
      examples:
      - approvals:
        - name: Legal Approval
          approver_user_id: 10324
          notes: Please take a look need your approval.
          order: 1
        - name: Finance team Approval
          approver_role_id: 60414
          notes: Hi team need your approval on this contract.
          order: 2
  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