SpotDraft V2 Users API

openapi: 3.2.0
info:
  title: SpotDraft V2 Users 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 Users
  description: List users, list roles, manage role membership, invite users, and update user access across public API versions.
paths:
  /api/v2/public/auth/roles/:
    get:
      operationId: v2_public_auth_roles_retrieve
      description: Returns the Roles that exist for the workspace whose credentials are used.
      summary: Get Active Roles
      tags:
      - V2 Users
      security:
      - ClientId: []
        ClientSecret: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalUserActiveRolesResponseList'
              examples:
                Example1:
                  value:
                    active_roles:
                    - id: 1
                      name: Legal Team
                      description: The in-house legal team responsible for TPP Reviews.
                    - id: 2
                      name: NA Sales
                      description: The North America Sales Team
                    - id: 3
                      name: APAC Sales
                      description: The Asia Pacific Sales Team (ex Japan)
                  summary: Example 1
          description: Success
      x-tagGroup: Platform
  /api/v2/public/auth/roles/{role_id}/members:
    post:
      operationId: v2_public_auth_roles_members_create
      description: 'Adds one or more users to the specified role within the current workspace.

        Use this when role membership is managed separately from user creation.'
      summary: Add Role Member
      parameters:
      - in: path
        name: role_id
        schema:
          type: integer
        description: Use the [Get Active Roles](#tag/v21-users/GET/api/v2.1/public/auth/roles/) API to get the role ID.
        required: true
      tags:
      - V2 Users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicRoleMembersAddRequest'
            examples:
              Example1:
                value:
                  user_ids_to_add:
                  - 4567
                  - 2345
                summary: Example 1
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PublicRoleMembersAddRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PublicRoleMembersAddRequest'
      security:
      - ClientId: []
        ClientSecret: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicRoleMemberAddResponse'
              examples:
                Example1:
                  value:
                  - id: 6545
                    email: barack@obama.com
                    name: Barack Obama
                    designation: President
                  summary: Example 1
          description: Add Role Member
      x-tagGroup: Platform
    delete:
      operationId: v2_public_auth_roles_members_destroy
      description: 'Removes one or more users from the specified role within the current workspace.

        The role itself is not deleted.'
      summary: Delete Role Member
      parameters:
      - in: path
        name: role_id
        schema:
          type: integer
        description: Use the [Get Active Roles](#tag/v21-users/GET/api/v2.1/public/auth/roles/) API to get the role ID.
        required: true
      tags:
      - V2 Users
      security:
      - ClientId: []
        ClientSecret: []
      responses:
        '204':
          description: Delete Role Member
      x-tagGroup: Platform
  /api/v2/public/auth/users/:
    get:
      operationId: v2_public_auth_users_retrieve
      description: 'Lists users in the organization backing the current workspace.

        Use `page`, `limit`, and `user_email` to page through results or narrow the list.'
      summary: Get User List
      parameters:
      - in: query
        name: limit
        schema:
          type: integer
          default: 10
        description: The number of items to return per page.
      - in: query
        name: page
        schema:
          type: integer
          default: 1
        description: The page to return. Page numbers start at 1.
      - in: query
        name: user_email
        schema:
          type: string
        description: User email address for which that user list should be filtered. Please make sure that the value is url encoded. So for example, if the email address is `abc+123@xyz.com` the value passed should be `abc%2B123%40xyz.com`.
      tags:
      - V2 Users
      security:
      - ClientId: []
        ClientSecret: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicUserMinimalListResponse'
              examples:
                Example1:
                  value:
                    total_results: 2
                    page: 1
                    limit: 10
                    results:
                    - id: 100
                      first_name: Sonia
                      last_name: Sotomayor
                      email: sonia_sotomayor@notreally.supremecourt.gov
                      designation: Lawyer
                    - id: 101
                      first_name: Elena
                      last_name: Kagan
                      email: elena_kagan@notreally.supremecourt.gov
                      designation: Lead Lawyer
                  summary: Example 1
          description: User List
      x-tagGroup: Platform
components:
  schemas:
    PublicRoleMemberAddResponse:
      title: PublicRoleMemberAddResponse
      description: A list of the members who were added to the role.
      type: array
      items:
        title: PublicMinimalUserResponse
        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
      examples:
      - - id: 6545
          email: barack@obama.com
          name: Barack Obama
          designation: President
    ExternalUserActiveRolesResponseList:
      title: ExternalUserActiveRolesResponseList
      description: External model containing list of active roles.
      type: object
      properties:
        active_roles:
          title: Active Roles
          description: The list of roles active in the current workspace.
          type: array
          items:
            title: ExternalUserActiveRolesData
            description: Details of an active role
            type: object
            properties:
              id:
                title: Id
                description: ID of the role. Use this to identify the role when calling APIs like Add/Delete Role Member.
                type: integer
              name:
                title: Name
                description: The user visible name of the role.
                type: string
              description:
                title: Description
                description: An option description that helps clarify the use of a particular role.
                type: string
            required:
            - id
            - name
      required:
      - active_roles
      examples:
      - active_roles:
        - id: 1
          name: Legal Team
          description: The in-house legal team responsible for TPP Reviews.
        - id: 2
          name: NA Sales
          description: The North America Sales Team
        - id: 3
          name: APAC Sales
          description: The Asia Pacific Sales Team (ex Japan)
    PublicUserMinimalListResponse:
      title: PublicUserMinimalListResponse
      description: SD Generic Model from which all other Generic Models should inherit
      type: object
      properties:
        page:
          title: Page
          description: The current page number. Page numbers start at 1.
          type: integer
        limit:
          title: Limit
          description: The number of items returned per page.
          type: integer
        total_results:
          title: Total Results
          description: Total number of items in the result set.
          type: integer
        results:
          title: Results
          description: The actual results.
          type: array
          items:
            title: PublicMinimalUserResponse
            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
      required:
      - page
      - limit
      - total_results
      - results
      examples:
      - total_results: 2
        page: 1
        limit: 10
        results:
        - id: 100
          first_name: Sonia
          last_name: Sotomayor
          email: sonia_sotomayor@notreally.supremecourt.gov
          designation: Lawyer
        - id: 101
          first_name: Elena
          last_name: Kagan
          email: elena_kagan@notreally.supremecourt.gov
          designation: Lead Lawyer
    PublicRoleMembersAddRequest:
      title: PublicRoleMembersAddRequest
      type: object
      properties:
        user_ids_to_add:
          title: User Ids To Add
          description: The user ids that are to be added to the role. The IDs are returned by the [Get User List](#tag/v21-users/GET/api/v2.1/public/auth/users/) API. This list must contain at least one user id.
          default: []
          type: array
          items:
            type: integer
      examples:
      - user_ids_to_add:
        - 4567
        - 2345
  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