SpotDraft V2.1 Recipients API

openapi: 3.2.0
info:
  title: SpotDraft V2.1 Recipients 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 Recipients
  description: Recipient lookups and participant-facing contract resources across public API versions.
paths:
  /api/v2.1/public/contracts/{composite_id}/recipients/:
    get:
      operationId: v2.1_public_contracts_recipients_retrieve
      description: 'A recipient is a person who can access the contract and perform an action. A recipient can be one of these

        3 types:


        Type

        Action


        APPROVER

        Approve the contract


        SIGNATORY

        Sign the contract


        RECEIVER

        Receive the contract


        Further, every action has a status associated with it. It can be one of these 3 types:


        Action Status

        Description


        COMPLETED

        User has successfully performed the action


        IN_PROGRESS

        User has been invited but is yet to perform the action


        PENDING

        User is yet to be invited to perform the action


        This API can be used to get list of all recipients for a contract.'
      summary: Get Contract Recipients
      parameters:
      - in: path
        name: composite_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 Recipients
      security:
      - ClientId: []
        ClientSecret: []
      - OAuthBearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSignRecipientWithStatusListResponse'
              examples:
                Example1:
                  value:
                    items:
                    - recipient:
                        id: 143476
                        recipient_type: APPROVER
                        user:
                          id: 25367
                          name: Tyler
                          designation: Senior Manager
                          email: tyler@yahoo.com
                        title: Senior Manager - Operations
                        recipient_order: 1
                        note: He is a Senior Manager heading operations team
                        is_sent_for_signature: true
                        created: '2024-05-24T05:45:34.478802Z'
                        last_sent_for_signature_at: '2024-05-24T05:46:22.721800Z'
                      recipient_action:
                        is_success: true
                        action_notes: Approving on behalf of tyler
                        timestamp: '2024-05-24T05:47:31.594842Z'
                      status: COMPLETED
                    - recipient:
                        id: 143776
                        recipient_type: SIGNATORY
                        user:
                          id: 25567
                          name: Mike Reed
                          designation: Operations Head
                          email: mike_reed@yahoo.com
                        title: ''
                        recipient_order: 2
                        note: null
                        is_sent_for_signature: true
                        created: '2024-05-24T05:45:34.478802Z'
                        last_sent_for_signature_at: '2024-05-25T05:46:22.721800Z'
                      recipient_action: null
                      status: IN_PROGRESS
                    - recipient:
                        id: 144776
                        recipient_type: RECEIVER
                        user:
                          id: 25367
                          name: Alice
                          designation: null
                          email: alice@yahoo.com
                        title: ''
                        recipient_order: 3
                        note: null
                        is_sent_for_signature: false
                        created: '2024-05-24T05:45:34.478802Z'
                        last_sent_for_signature_at: null
                      recipient_action: null
                      status: IN_PROGRESS
                  summary: Example 1
          description: Success
      x-tagGroup: Contracts
  /api/v2.1/public/contracts/{contract_id}/recipients/recipient_link/:
    get:
      operationId: v2.1_public_contracts_recipients_recipient_link_retrieve
      description: Returns a recipient-specific signing or review link for the given contract and recipient email. Use this when you need to surface the recipient journey from your own application.
      summary: Get Recipient Link
      parameters:
      - in: path
        name: contract_id
        schema:
          type: integer
        description: ID of the Contract.
        required: true
      - in: query
        name: recipient_email
        schema:
          type: string
        description: Email of the recipient for whom the link needs to be generated.
        required: true
      tags:
      - V2.1 Recipients
      security:
      - ClientId: []
        ClientSecret: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalGetRecipientLinkResponse'
          description: Success
      x-tagGroup: Contracts
components:
  schemas:
    ExternalGetRecipientLinkResponse:
      title: ExternalGetRecipientLinkResponse
      type: object
      properties:
        link:
          title: Link
          description: Link that can be used by the recipient to take an action like signing, approval, etc.
          type: string
      required:
      - link
    PublicSignRecipientWithStatusListResponse:
      title: PublicSignRecipientWithStatusListResponse
      type: object
      properties:
        items:
          title: Items
          description: List of all recipients with their details for the contract
          type: array
          items:
            title: PublicSignRecipientWithStatusResponse
            type: object
            properties:
              recipient:
                title: Recipient
                type: object
                properties:
                  id:
                    title: Id
                    description: Signatory ID
                    type: integer
                  recipient_type:
                    title: RecipientType
                    description: The type of recipient as set by the creator/editor for the contract
                    enum:
                    - SIGNATORY
                    - APPROVER
                    - RECEIVER
                    type: string
                  user:
                    title: User
                    type: object
                    properties:
                      id:
                        title: Id
                        description: ID of the user
                        type: integer
                      email:
                        title: Email
                        description: Email Id of the user
                        type: string
                      name:
                        title: Name
                        description: Name of the user
                        type: string
                      designation:
                        title: Designation
                        description: Designation of the user within the organization
                        type: string
                    required:
                    - id
                    - email
                    - name
                    description: Basic details of a recipient user
                  recipient_order:
                    title: Recipient Order
                    description: The order in which contract is sent out to the recipient, as set by the creator/editor for the contract
                    type: integer
                  note:
                    title: Note
                    description: The note for the recipient as set by the creator/editor for the contract
                    type: string
                  created:
                    title: Created
                    description: The timestamp (in ISO 8601 format) when the recipient was added by the creator/editor for the contract
                    type: string
                    format: date-time
                  title:
                    title: Title
                    description: The title of the recipient as set by the creator/editor for the contract
                    default: ''
                    type: string
                  is_sent_for_signature:
                    title: Is Sent For Signature
                    description: Set to true when contract has been sent out to recipient and false when contract has yet to be sent out to recipient
                    default: false
                    type: boolean
                  last_sent_for_signature_at:
                    title: Last Sent For Signature At
                    description: The timestamp (in ISO 8601 format) when the contract was last sent to the recipient
                    type: string
                    format: date-time
                required:
                - id
                - recipient_type
                - user
                - created
                description: The details of the recipient
              recipient_action:
                title: Recipient Action
                type: object
                properties:
                  is_success:
                    title: Is Success
                    description: Set to true when recipient has signed/approved the contract and false when recipient has declined to sign/approve the contract
                    default: false
                    type: boolean
                  action_notes:
                    title: Action Notes
                    description: Note added by the recipient while signing/approving the contract
                    type: string
                  timestamp:
                    title: Timestamp
                    description: The timestamp (in ISO 8601 format) when recipient performed the action on the contract
                    type: string
                    format: date-time
                description: The action taken by the recipient
              status:
                title: RecipientStatus
                description: The current status of action that the recipient can perform
                enum:
                - PENDING
                - IN_PROGRESS
                - COMPLETED
                type: string
            required:
            - recipient
            - status
      required:
      - items
      examples:
      - items:
        - recipient:
            id: 143476
            recipient_type: APPROVER
            user:
              id: 25367
              name: Tyler
              designation: Senior Manager
              email: tyler@yahoo.com
            title: Senior Manager - Operations
            recipient_order: 1
            note: He is a Senior Manager heading operations team
            is_sent_for_signature: true
            created: '2024-05-24T05:45:34.478802Z'
            last_sent_for_signature_at: '2024-05-24T05:46:22.721800Z'
          recipient_action:
            is_success: true
            action_notes: Approving on behalf of tyler
            timestamp: '2024-05-24T05:47:31.594842Z'
          status: COMPLETED
        - recipient:
            id: 143776
            recipient_type: SIGNATORY
            user:
              id: 25567
              name: Mike Reed
              designation: Operations Head
              email: mike_reed@yahoo.com
            title: ''
            recipient_order: 2
            note: null
            is_sent_for_signature: true
            created: '2024-05-24T05:45:34.478802Z'
            last_sent_for_signature_at: '2024-05-25T05:46:22.721800Z'
          recipient_action: null
          status: IN_PROGRESS
        - recipient:
            id: 144776
            recipient_type: RECEIVER
            user:
              id: 25367
              name: Alice
              designation: null
              email: alice@yahoo.com
            title: ''
            recipient_order: 3
            note: null
            is_sent_for_signature: false
            created: '2024-05-24T05:45:34.478802Z'
            last_sent_for_signature_at: null
          recipient_action: null
          status: IN_PROGRESS
  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