SpotDraft V1 Users API

openapi: 3.2.0
info:
  title: SpotDraft V1 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: V1 Users
  description: List users, list roles, manage role membership, invite users, and update user access across public API versions.
paths:
  /api/v1/public/auth/roles:
    get:
      operationId: v1_public_auth_roles_retrieve
      description: 'Lists the active roles configured for the workspace tied to the API credentials.

        Use these ids in user-create and user-update requests.'
      summary: Get Roles
      tags:
      - V1 Users
      security:
      - ClientId: []
        ClientSecret: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExternalUserActiveRole'
              examples:
                Example:
                  value:
                  - - id: 1
                      name: Admin
                    - id: 2
                      name: Signatory
          description: List of Roles
      x-tagGroup: Platform
  /api/v1/public/auth/users:
    get:
      operationId: v1_public_auth_users_retrieve
      description: 'Lists users in the workspace linked to the API credentials.

        Use `page`, `limit`, and `user_email` to page through results or narrow to a specific user.'
      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:
      - V1 Users
      security:
      - ClientId: []
        ClientSecret: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalUserPaginated'
              examples:
                Example:
                  value:
                    total_results: 2
                    page: 1
                    limit: 10
                    results:
                    - first_name: Sonia
                      last_name: Sotomayor
                      roles:
                      - Admin
                      - Signatory
                      username: sonia_sotomayor@notreally.supremecourt.gov
                      created: '2009-08-06T00:00:00Z'
                      modified: '2009-08-06T00:00:00Z'
                    - first_name: Elena
                      last_name: Kagan
                      roles:
                      - Admin
                      - Signatory
                      username: elena_kagan@notreally.supremecourt.gov
                      created: '2010-08-05T00:00:00Z'
                      modified: '2010-08-05T00:00:00Z'
          description: User List
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Error detail.
                required:
                - detail
              examples:
                Example:
                  value:
                    detail: Invalid page number or page limit too big.
          description: Invalid pagination parameters.
      x-tagGroup: Platform
    post:
      operationId: v1_public_auth_users_create
      description: 'Creates a user in the client account and assigns the requested roles.

        If the user already exists in a deactivated state, the same endpoint can reactivate that user.'
      summary: Create User
      tags:
      - V1 Users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalUserCreate'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ExternalUserCreate'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ExternalUserCreate'
        required: true
      security:
      - ClientId: []
        ClientSecret: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalUser'
              examples:
                Example:
                  value:
                    first_name: Sonia
                    last_name: Sotomayor
                    roles:
                    - Admin
                    - Signatory
                    username: sonia_sotomayor@notreally.supremecourt.gov
                    created: '2009-08-06T00:00:00Z'
                    modified: '2009-08-06T00:00:00Z'
          description: Created User
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Error detail.
                required:
                - detail
              examples:
                Example:
                  value:
                    detail: Invalid request body or user already exists.
          description: Invalid request body.
      x-tagGroup: Platform
  /api/v1/public/auth/users/{user_id}:
    patch:
      operationId: v1_public_auth_users_partial_update
      description: 'Updates the roles assigned to an existing workspace user.

        Use this to add or remove role access without recreating the user.'
      summary: Update User Roles
      parameters:
      - in: path
        name: user_id
        schema:
          type: integer
        description: ID of the user as returned by the List Users API.
        required: true
      tags:
      - V1 Users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedExternalUserEdit'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedExternalUserEdit'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedExternalUserEdit'
      security:
      - ClientId: []
        ClientSecret: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalUser'
              examples:
                Example:
                  value:
                    first_name: Sonia
                    last_name: Sotomayor
                    roles:
                    - Admin
                    - Signatory
                    username: sonia_sotomayor@notreally.supremecourt.gov
                    created: '2009-08-06T00:00:00Z'
                    modified: '2009-08-06T00:00:00Z'
          description: Updated User
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Error detail.
                required:
                - detail
              examples:
                Example:
                  value:
                    detail: Invalid role ID.
          description: Invalid role update request.
      x-tagGroup: Platform
    delete:
      operationId: v1_public_auth_users_destroy
      description: 'Deactivates a workspace user by id.

        The user remains part of the historical audit trail but can no longer act in the workspace.'
      summary: Deactivate a User
      parameters:
      - in: path
        name: user_id
        schema:
          type: integer
        description: ID of the user as returned by the List Users API.
        required: true
      tags:
      - V1 Users
      security:
      - ClientId: []
        ClientSecret: []
      responses:
        '204':
          description: No response body
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Error detail.
                required:
                - detail
              examples:
                Example:
                  value:
                    detail: User already deactivated.
          description: Invalid request.
      x-tagGroup: Platform
components:
  schemas:
    PatchedExternalUserEdit:
      type: object
      properties:
        roles:
          type: array
          items:
            type: integer
          description: The Role IDs for this user. Role IDs are returned by the Roles API.
    ExternalUser:
      type: object
      description: The response for the user created in SpotDraft
      properties:
        id:
          type: integer
          readOnly: true
        first_name:
          type: string
          description: The first name of the user.
        last_name:
          type: string
          description: The last name of the user.
        roles:
          type: array
          items:
            type: string
          readOnly: true
          description: The list of roles for the user.
        username:
          type: string
          description: The email address of the user.
        created:
          type: string
          format: date-time
          description: The ISO timestamp when the user was created.
        modified:
          type: string
          format: date-time
          description: The ISO timestamp when the user was last modified.
      required:
      - created
      - first_name
      - id
      - last_name
      - modified
      - roles
      - username
    ExternalUserCreate:
      type: object
      description: The request body to create the users in SpotDraft
      properties:
        username:
          type: string
          format: email
          description: The email address of the user.
        first_name:
          type: string
          description: The first name of the user.
        last_name:
          type: string
          description: The last name of the user.
        password:
          type: string
          description: Password for the user.
        roles:
          type: array
          items:
            type: integer
          description: Role IDs applicable to this user. IDs are returned by the Roles API.
      required:
      - first_name
      - last_name
      - roles
      - username
    ExternalUserActiveRole:
      type: object
      description: The response for the active role for that workspace
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
          maxLength: 150
      required:
      - id
      - name
    ExternalUserPaginated:
      type: object
      properties:
        total_results:
          type: integer
          description: Total number of items in the result set.
        page:
          type: integer
          description: The current page number. Page numbers start at 1.
        limit:
          type: integer
          description: The number of items returned per page.
        results:
          type: array
          items:
            $ref: '#/components/schemas/ExternalUser'
          description: The actual results.
      required:
      - limit
      - page
      - results
      - total_results
  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