SpotDraft V2.1 Clickwrap API

openapi: 3.2.0
info:
  title: SpotDraft V2.1 Clickwrap 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 Clickwrap
  description: Clickwrap agreement preview, consent status, and contract creation endpoints.
paths:
  /api/v2.1/public/clickwrap/{clickwrap_id}/agreements/preview/:
    post:
      operationId: v2.1_public_clickwrap_agreements_preview_create
      description: 'Generates an HTML preview of a clickwrap agreement for the given clickwrap.


        Exposed on the **public** API so custom scripts can run under the clickwrap/CSP domain instead of the main app domain.'
      summary: Preview Clickwrap Agreement
      parameters:
      - in: path
        name: clickwrap_id
        schema:
          type: integer
        description: Numeric id of the clickwrap.
        required: true
      tags:
      - V2.1 Clickwrap
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClickwrapAgreementPreviewRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ClickwrapAgreementPreviewRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ClickwrapAgreementPreviewRequest'
        required: true
      security:
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                type: string
          description: Rendered HTML preview (`text/html`).
      x-tagGroup: Clickwrap
  /api/v2.1/public/clickwrap/{clickwrap_public_id}/:
    get:
      operationId: v2.1_public_clickwrap_retrieve
      description: Returns the clickwrap corresponding to the clickwrap public id
      summary: Get Clickwrap
      parameters:
      - in: path
        name: clickwrap_public_id
        schema:
          type: string
          format: uuid
        description: Public Id of Clickwrap
        required: true
      tags:
      - V2.1 Clickwrap
      security:
      - ClickwrapId: []
        Origin: []
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClickwrapPublicGetAPIResponse'
          description: Success
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Clickwrap agreement not found
          description: Not Found
      x-tagGroup: Clickwrap
  /api/v2.1/public/clickwrap/{clickwrap_public_id}/consent_status/:
    post:
      operationId: v2.1_public_clickwrap_consent_status_create
      description: 'Used to know if a particular user has given consent to a specific clickwrap.


        Returns one of the following values as consent status for the user.


        Status field value

        Details


        NOT_ACCEPTED

        When the user hasn’t accepted this clickwrap before.


        ACCEPTED_OLDER_VERSION

        When the user has accepted the clickwrap, but a new published version exists.


        ACCEPTED_LATEST_VERSION

        When the user has accepted the latest published version of the clickwrap.'
      summary: Get Consent Status
      parameters:
      - in: path
        name: clickwrap_public_id
        schema:
          type: string
          format: uuid
        description: Public Id of Clickwrap
        required: true
      tags:
      - V2.1 Clickwrap
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicGetClickwrapConsentStatusRequestData'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PublicGetClickwrapConsentStatusRequestData'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PublicGetClickwrapConsentStatusRequestData'
        required: true
      security:
      - ClientId: []
        ClientSecret: []
      - ClickwrapId: []
        Origin: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicClickwrapConsentStatusResponse'
          description: Success
      x-tagGroup: Clickwrap
  /api/v2.1/public/clickwrap/{clickwrap_public_id}/execute/:
    post:
      operationId: v2.1_public_clickwrap_execute_create
      description: Creates the clickwrap contract
      summary: Create Clickwrap Contract
      parameters:
      - in: path
        name: clickwrap_public_id
        schema:
          type: string
          format: uuid
        description: Public Id of Clickwrap
        required: true
      tags:
      - V2.1 Clickwrap
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateClickwrapContractRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateClickwrapContractRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateClickwrapContractRequest'
        required: true
      security:
      - ClickwrapId: []
        Origin: []
      - {}
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractMinimalResponseV2'
          description: Created
      x-tagGroup: Clickwrap
components:
  schemas:
    ContractMinimalResponseV2ContractKindEnum:
      enum:
      - TEMPLATE
      - TEMPLATE_EDITABLE
      - UPLOAD_EDITABLE
      - UPLOAD_SIGN
      - UPLOAD_EXECUTED
      - EXPRESS_TEMPLATE
      - CLICKWRAP
      - HISTORICAL_CLICKWRAP
      type: string
    WorkflowStatusEnum:
      enum:
      - DRAFT
      - INVITE_CLIENT
      - INFO_COLLECTION
      - CONTRACT_APPROVAL
      - CONTRACT_DRAFT_APPROVAL
      - CONTRACT_APPROVAL_REJECTED
      - REVIEW
      - SIGN
      - COMPLETING
      - COMPLETED
      - TEMPLATE_PRE_SIGN_APPROVAL
      type: string
    ClickwrapWithVersionGetAPIResponse:
      properties:
        id:
          title: Id
          type: integer
        name:
          minLength: 1
          title: Name
          type: string
        status:
          anyOf:
          - $ref: '#/components/schemas/ClickwrapAgreementVersionStatusType'
          - type: 'null'
          default: null
        modified_by_org_user_at:
          title: Modified By Org User At
          type: string
        version_number:
          title: Version Number
          type: integer
        sub_version_number:
          title: Sub Version Number
          type: integer
        public_url:
          anyOf:
          - format: uri
            minLength: 1
            type: string
          - type: 'null'
          default: null
          title: Public Url
        full_version_number:
          minLength: 1
          readOnly: true
          title: Full Version Number
          type: string
      required:
      - id
      - name
      - modified_by_org_user_at
      - version_number
      - sub_version_number
      - full_version_number
      title: ClickwrapWithVersionGetAPIResponse
      type: object
    CreateClickwrapContractRequest:
      title: CreateClickwrapContractRequest
      type: object
      properties:
        clickwrap_public_id:
          title: Clickwrap Public Id
          description: Public clickwrap id that identifies the clickwrap experience.
          type: string
          format: uuid
        user_identifier:
          title: User Identifier
          description: Your stable identifier for the end user accepting the clickwrap, such as an email address or application user id.
          type: string
        clickwrap_id:
          title: Clickwrap Id
          description: Internal clickwrap id resolved by SpotDraft for the requested public clickwrap.
          type: integer
        first_name:
          title: First Name
          description: Optional first name for the accepting user.
          type: string
        last_name:
          title: Last Name
          description: Optional last name for the accepting user.
          type: string
        user_email:
          title: User Email
          description: Optional email address for the accepting user.
          type: string
        ip_address:
          title: Ip Address
          description: IP address captured for the acceptance event.
          type: string
        additional_custom_information:
          title: Additional Custom Information
          description: Optional custom key-value metadata to store alongside the acceptance record.
          type: object
        key_pointer_information:
          title: Key Pointer Information
          description: Optional structured values to populate contract metadata fields during clickwrap contract creation.
          type: object
        agreements:
          title: Agreements
          description: Agreement versions the user is accepting as part of this clickwrap execution.
          minItems: 1
          type: array
          items:
            title: CreateClickwrapContractAgreementVersionRequest
            type: object
            properties:
              id:
                title: Id
                description: Agreement id included in the clickwrap execution request.
                type: integer
              version_id:
                title: Version Id
                description: Published agreement version id the user is accepting.
                type: integer
              has_clicked:
                title: Has Clicked
                description: Whether the user opened or interacted with this agreement before acceptance.
                default: false
                type: boolean
            required:
            - id
            - version_id
        external_metadata:
          title: External Metadata
          description: Optional external-system metadata to associate with the created clickwrap contract.
          type: object
      required:
      - clickwrap_public_id
      - user_identifier
      - clickwrap_id
      - agreements
    ClickwrapConsentStatus:
      enum:
      - NOT_ACCEPTED
      - ACCEPTED_OLDER_VERSION
      - ACCEPTED_LATEST_VERSION
      title: ClickwrapConsentStatus
      type: string
    ClickwrapAgreementVersionStatusType:
      enum:
      - PUBLISHED
      - DRAFT
      - PAST_PUBLISHED
      title: ClickwrapAgreementVersionStatusType
      type: string
    EditorClientEnum:
      enum:
      - ONLY_OFFICE_NATIVE
      - WOPI
      - UNSET
      type: string
    AgreementClickwrapGetAPIResponse:
      properties:
        id:
          title: Id
          type: integer
        current_version:
          $ref: '#/components/schemas/ClickwrapWithVersionGetAPIResponse'
      required:
      - id
      - current_version
      title: AgreementClickwrapGetAPIResponse
      type: object
    PublicGetClickwrapConsentStatusRequestData:
      examples:
      - user_identifier: 10f9a299-9e9a-4bc9-9299-5b89bc06d370
      properties:
        user_identifier:
          description: An identifier for the user whose consent status is being queried.
          minLength: 1
          title: User Identifier
          type: string
      required:
      - user_identifier
      title: PublicGetClickwrapConsentStatusRequestData
      type: object
    OrgUserMinimalDomainModel:
      properties:
        id:
          title: Id
          type: integer
        name:
          title: Name
          type: string
        email:
          title: Email
          type: string
        designation:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Designation
        auth_user_id:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Auth User Id
      required:
      - id
      - name
      - email
      title: OrgUserMinimalDomainModel
      type: object
    ContractMinimalResponseV2:
      title: ContractMinimalResponseV2
      description: "Minimal response model for a contract.\nAttributes:\n    id (ContractId): The ID of the contract.\n    public_id (str): Public ID of the contract.\n    contract_name (str): Name of the contract.\n    contract_type_id (ContractTypeId): ID of the contract type.\n    contract_template_id (Optional[int], optional): ID of the associated contract template.\n    status (str): Status of the contract.\n    display_status (ContractDisplayStatus): Display status of the contract.\n    display_status_without_on_hold_check (ContractDisplayStatus):\n        Display status of the contract without on-hold check.\n    workflow_status (Optional[ContractWorkflowStatus], optional): Workflow status of the contract.\n    contract_kind (ContractKind): Kind of the contract.\n    campaign_id (Optional[int], optional): ID of the associated campaign.\n    campaign_v3_id (Optional[CampaignId], optional): ID of the associated campaign (v3).\n    express_template_id (Optional[int], optional): ID of the express template.\n    contract_data_id (Optional[int], optional): ID of the contract data.\n    contract_editable_document_id (Optional[int], optional): ID of the editable document related to the contract.\n    created (datetime): Date and time when the contract was created.\n    created_by_workspace_id (WorkspaceId): ID of the workspace where the contract was created.\n    editor_client (ContractEditorClient): Client editor of the contract.\n    execution_date (Optional[datetime], optional): Date and time of contract execution.\n    frozen_template_id (Optional[int], optional): ID of the frozen contract template.\n    workflow_id (str): ID of the workflow associated with the contract.\n\nMethods:\n    is_executed() -> bool:\n        Checks if the contract is executed.\n\n    is_voided() -> bool:\n        Checks if the contract is voided.\n\n    is_historic_upload() -> bool:\n        Checks if the contract is a historic upload.\n\n    contract_response_v2() -> ContractResponseV2:\n        Retrieves the full response object for the contract.\n\n    get_fields_to_select() -> List[str]:\n        Retrieves the list of fields to select for the contract."
      type: object
      properties:
        id:
          title: Id
          type: integer
        public_id:
          title: Public Id
          type: string
        contract_name:
          title: Contract Name
          type: string
        contract_type_id:
          title: Contract Type Id
          type: integer
        contract_template_id:
          title: Contract Template Id
          type: integer
        status:
          title: Status
          type: string
        display_status:
          allOf:
          - $ref: '#/components/schemas/ContractDisplayStatusEnum'
          title: ContractDisplayStatus
          description: An enumeration.
        display_status_without_on_hold_check:
          allOf:
          - $ref: '#/components/schemas/ContractDisplayStatusEnum'
          title: ContractDisplayStatus
          description: An enumeration.
        workflow_status:
          allOf:
          - $ref: '#/components/schemas/WorkflowStatusEnum'
          title: ContractWorkflowStatus
          description: An enumeration.
        contract_kind:
          allOf:
          - $ref: '#/components/schemas/ContractMinimalResponseV2ContractKindEnum'
          title: ContractKind
          description: An enumeration.
        campaign_id:
          title: Campaign Id
          type: integer
        campaign_v3_id:
          title: Campaign V3 Id
          type: integer
        express_template_id:
          title: Express Template Id
          type: integer
        contract_data_id:
          title: Contract Data Id
          type: integer
        contract_editable_document_id:
          title: Contract Editable Document Id
          type: integer
        created:
          title: Created
          type: string
          format: date-time
        created_by_workspace_id:
          title: Created By Workspace Id
          type: integer
        editor_client:
          allOf:
          - $ref: '#/components/schemas/EditorClientEnum'
          title: ContractEditorClient
          description: An enumeration.
        execution_date:
          title: Execution Date
          type: string
          format: date-time
        frozen_template_id:
          title: Frozen Template Id
          type: integer
        workflow_id:
          title: Workflow Id
          type: string
        workflow_name:
          title: Workflow Name
          type: string
      required:
      - id
      - public_id
      - contract_name
      - contract_type_id
      - status
      - display_status
      - display_status_without_on_hold_check
      - contract_kind
      - created
      - created_by_workspace_id
      - editor_client
      - workflow_id
    ClickwrapSettingsPublicResponse:
      properties:
        type:
          $ref: '#/components/schemas/ClickwrapType'
        whitelisted_domains:
          default: []
          items:
            type: string
          title: Whitelisted Domains
          type: array
        allow_all_domains:
          default: false
          title: Allow All Domains
          type: boolean
        clickwrap_texts:
          items:
            minLength: 1
            type: string
          title: Clickwrap Texts
          type: array
        clickwrap_texts_raw:
          items:
            type: object
          title: Clickwrap Texts Raw
          type: array
      required:
      - type
      - clickwrap_texts
      - clickwrap_texts_raw
      title: ClickwrapSettingsPublicResponse
      type: object
    ContractDisplayStatusEnum:
      enum:
      - DRAFT
      - REDLINING
      - SIGN
      - EXECUTED
      - ON_HOLD
      - VOIDED
      type: string
    PublicClickwrapConsentStatusResponse:
      example:
        status: NOT_ACCEPTED
      properties:
        status:
          $ref: '#/components/schemas/ClickwrapConsentStatus'
        trigger_acceptance:
          title: Trigger Acceptance
          type: boolean
      required:
      - status
      - trigger_acceptance
      title: PublicClickwrapConsentStatusResponse
      type: object
    ClickwrapAgreementPreviewRequest:
      title: ClickwrapAgreementPreviewRequest
      type: object
      properties:
        auth_user_id:
          title: Auth User Id
          description: Authenticated user id under whose context the agreement preview should be rendered.
          type: integer
        workspace_id:
          title: Workspace Id
          description: Workspace id that owns the clickwrap agreement.
          type: integer
        org_user_id:
          title: Org User Id
          description: Workspace membership id for the authenticated user.
          type: integer
        agreement_id:
          title: Agreement Id
          description: Agreement id to preview.
          type: integer
        name:
          title: Name
          description: Agreement name shown in the preview.
          type: string
        html_content:
          title: Html Content
          description: Rendered agreement HTML that should be previewed.
          type: string
      required:
      - auth_user_id
      - workspace_id
      - org_user_id
      - agreement_id
      - name
      - html_content
    ClickwrapType:
      enum:
      - SINGLE_CHECKBOX
      - MULTIPLE_CHECKBOX
      - INLINE
      title: ClickwrapType
      type: string
    ClickwrapPublicGetAPIResponse:
      properties:
        id:
          title: Id
          type: integer
        name:
          minLength: 1
          title: Name
          type: string
        description:
          minLength: 1
          title: Description
          type: string
        created_by_org_user:
          $ref: '#/components/schemas/OrgUserMinimalDomainModel'
        updated_by_org_user_at:
          title: Updated By Org User At
          type: string
        agreements:
          items:
            $ref: '#/components/schemas/AgreementClickwrapGetAPIResponse'
          title: Agreements
          type: array
        public_id:
          format: uuid4
          title: Public Id
          type: string
        contract_type_id:
          title: Contract Type Id
          type: integer
        settings:
          $ref: '#/components/schemas/ClickwrapSettingsPublicResponse'
      required:
      - id
      - name
      - description
      - created_by_org_user
      - updated_by_org_user_at
      - agreements
      - public_id
      - contract_type_id
      - settings
      title: ClickwrapPublicGetAPIResponse
      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