Smokeball Users API

openapi: 3.2.0
info:
  title: Smokeball Activity Codes Users API
  version: '1.0'
  description: REST API for integrating with Smokeball legal practice management software. Supports matters, contacts, documents, time entries, billing, trust accounting, staff, webhooks, and law firm workflows across US, AU, and UK regions. Uses OAuth 2.0 (client credentials) authentication.
  contact:
    name: Smokeball Developer Support
    url: https://docs.smokeball.com/docs/api-docs/1e13a13124aee-introduction
  x-api-id: smokeball
  x-audience: external-public
servers:
- url: https://api.smokeball.com
- url: https://api.smokeball.com.au
- url: https://api.smokeball.co.uk
- url: https://stagingapi.smokeball.com
- url: https://stagingapi.smokeball.com.au
- url: https://stagingapi.smokeball.co.uk
security:
- api-key: []
  token: []
tags:
- name: Users
paths:
  /users/{id}:
    get:
      tags:
      - Users
      summary: Get a user
      description: Retrieves a specified user.
      operationId: GetUserByIdAsync
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: When request is successful. Returns a 'User' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: When user with specified id is not associated with authenticated client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When user with specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    delete:
      tags:
      - Users
      summary: Remove a user
      description: "Removes a user.\n            \nUser must belong to the specified account."
      operationId: DeleteUserAsync
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '202':
          description: When request is accepted. Returns a hypermedia 'Link' object of the user to be removed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: When the user is not associated to the specified account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /users:
    post:
      tags:
      - Users
      summary: Create a user
      description: 'Creates a user.


        Sends an email with a generated password if the password is missing.'
      operationId: CreateUserAsync
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/UserDto'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/UserDto'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/UserDto'
      responses:
        '202':
          description: When request is accepted. Returns a hypermedia 'Link' object of the user to be created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '400':
          description: When user or password validation fails.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /users/{id}/invite:
    post:
      tags:
      - Users
      summary: Resend a user invitation
      description: 'Resends an invitation email with a temporary password for the specified user.


        The user must exist and belong to the specified account when specifying id.

        Optionally invite a user using a email address instead of user id. Use a default id of all zeros when posting email address payload.

        Email address invites are only available to client credential grants.'
      operationId: InviteUserAsync
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/InviteUserDto'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/InviteUserDto'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/InviteUserDto'
      responses:
        '202':
          description: When request is accepted. Returns a hypermedia 'Link' object of the user to be invited.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: When the user is not associated to the specified account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    InviteUserDto:
      required:
      - email
      type: object
      properties:
        email:
          minLength: 1
          type: string
          description: Invite user by email address.
      additionalProperties: false
    Link:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
        href:
          type:
          - string
          - 'null'
        relation:
          type:
          - string
          - 'null'
        method:
          type:
          - string
          - 'null'
          default: GET
      additionalProperties: false
    User:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
        href:
          type:
          - string
          - 'null'
        relation:
          type:
          - string
          - 'null'
        method:
          type:
          - string
          - 'null'
          default: GET
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
        userId:
          type:
          - string
          - 'null'
          description: Unique identifier of the user.
          example: 23d2a4bc-8529-462e-8560-dfbf4fa24e49
        email:
          type:
          - string
          - 'null'
          description: Email address of the user.
          example: user@domain.com
        isInternal:
          type: boolean
          description: Returns true if the user is flagged as an internal user.
          example: true
        bypassMfa:
          type: boolean
          description: Returns true if multi-factor authentication is bypassed for the user.
          example: true
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
          format: int32
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
      additionalProperties: {}
    UserDto:
      required:
      - email
      type: object
      properties:
        email:
          minLength: 1
          type: string
          description: Email address of the user.
          example: user@domain.com
        password:
          type:
          - string
          - 'null'
          description: 'Password for the user.


            Password must include atleast one lowercase character, uppercase character, numeric character as well as a special character.'
        expireAfterDays:
          type:
          - integer
          - 'null'
          description: Expire after the specified days. Must be left blank for users that do not expire.
          format: int32
          example: 7
        isInternal:
          type: boolean
          description: 'Creates the user as an internal user.


            Internal users are excluded from billing and license counts.


            Use this option for testing, background services, or other non-customer-facing purposes.'
          example: true
        bypassMfa:
          type: boolean
          description: 'Bypasses multi-factor authentication for the user.


            When enabled, the user will not be prompted for two factor authentication during login.'
          example: true
      additionalProperties: false
  securitySchemes:
    api-key:
      type: apiKey
      name: x-api-key
      in: header
    token:
      type: apiKey
      name: Authorization
      in: header
      x-amazon-apigateway-authtype: cognito_user_pools