Clio Users API

openapi: 3.2.0
info:
  title: Clio API Documentation Users API
  contact:
    name: Clio API Support
    email: api@clio.com
  description: '# Developer Support and Feedback

    * Clio takes the availability and stability of our API seriously; please report any **degradations** or **breakages** to Clio''s API Support team at api@clio.com.'
  version: v4
  x-logo:
    url: https://www.clio.com/wp-content/uploads/2015/05/Container-5-Logo.png
servers:
- url: https://app.clio.com/api/v4
  description: US region Production Server
- url: https://eu.app.clio.com/api/v4
  description: Europe region Production Server
- url: https://ca.app.clio.com/api/v4
  description: Canada region Production Server
- url: https://au.app.clio.com/api/v4
  description: Australia region Production Server
tags:
- name: Users
  description: 'A User is anyone with the ability to log in to Clio. This does not include Clio for Co-Counsel/Clio Connect users.


    Support Link


    ## Firm name

    You can obtain the name of the firm linked to a user by accessing the nested `account` object:


    ```json

    Request

    GET /api/v4/users/who_am_i?fields=account{name}

    ```'
paths:
  /users/who_am_i.json:
    get:
      tags:
      - Users
      summary: Return the data for the current User
      operationId: User#who_am_i
      description: Outlines the parameters, optional and required, used when requesting the data for a single User
      parameters:
      - name: IF-MODIFIED-SINCE
        in: header
        description: The server will send the requested resource with a 200 status, but only if it has been modified after the given date. (Expects an RFC 2822 timestamp).
        required: false
        schema:
          type: string
          format: date
      - name: IF-NONE-MATCH
        in: header
        description: The server will send the requested resource with a 200 status, but only if the existing resource's [ETag](#section/ETags) doesn't match any of the values listed.
        required: false
        schema:
          type: string
      - name: X-API-VERSION
        in: header
        description: 'The [API minor version](#section/Minor-Versions). Default: latest version.'
        required: false
        schema:
          type: string
      - name: fields
        in: query
        description: The fields to be returned. See response samples for what fields are available. For more information see the [fields section](#section/Fields).
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Ok
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/User_Show'
        '400':
          description: Bad Request
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too Many Requests
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '304':
          description: Not Modified
  /users.json:
    get:
      tags:
      - Users
      summary: Return the data for all Users
      operationId: User#index
      description: Outlines the parameters, optional and required, used when requesting the data for all Users
      parameters:
      - name: X-API-VERSION
        in: header
        description: 'The [API minor version](#section/Minor-Versions). Default: latest version.'
        required: false
        schema:
          type: string
      - name: created_since
        in: query
        description: Filter User records to those having the `created_at` field after a specific time. (Expects an ISO-8601 timestamp).
        required: false
        schema:
          type: string
          format: date-time
      - name: enabled
        in: query
        description: Filter User records to those that are enabled or disabled.
        required: false
        schema:
          type: boolean
      - name: fields
        in: query
        description: The fields to be returned. See response samples for what fields are available. For more information see the [fields section](#section/Fields).
        required: false
        schema:
          type: string
      - name: ids[]
        in: query
        description: Filter User records to those having the specified unique identifiers.
        required: false
        schema:
          type: integer
          format: int64
      - name: include_co_counsel
        in: query
        description: Filter User to include co-counsel users
        required: false
        schema:
          type: boolean
      - name: limit
        in: query
        description: 'A limit on the number of User records to be returned. Limit can range between 1 and 2000. Default: `2000`.'
        required: false
        schema:
          type: integer
          format: int32
      - name: name
        in: query
        description: Filter User records to those with the given name.
        required: false
        schema:
          type: string
      - name: order
        in: query
        description: 'Orders the User records by the given field. Default: `id(asc)`.'
        required: false
        schema:
          type: string
          enum:
          - enabled(asc)
          - enabled(desc)
          - id(asc)
          - id(desc)
          - name(asc)
          - name(desc)
          - first_name(asc)
          - first_name(desc)
          - last_name(asc)
          - last_name(desc)
          - initials(asc)
          - initials(desc)
          - subscription_type(asc)
          - subscription_type(desc)
      - name: page_token
        in: query
        description: A token specifying which page to return.
        required: false
        schema:
          type: string
      - name: pending_setup
        in: query
        description: Filter User records based on whether or not they are still being setup.
        required: false
        schema:
          type: boolean
      - name: role
        in: query
        description: Filter User records to those with a specific role.
        required: false
        schema:
          type: string
          enum:
          - admin
          - accounts
          - billing
          - reports
      - name: subscription_type
        in: query
        description: Filter User records to those with a specific subscription type.
        required: false
        schema:
          type: string
          enum:
          - attorney
          - nonattorney
      - name: updated_since
        in: query
        description: Filter User records to those having the `updated_at` field after a specific time. (Expects an ISO-8601 timestamp).
        required: false
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Ok
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/User_List'
        '400':
          description: Bad Request
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too Many Requests
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
  /users/{id}.json:
    get:
      tags:
      - Users
      summary: Return the data for a single User
      operationId: User#show
      description: Outlines the parameters, optional and required, used when requesting the data for a single User
      parameters:
      - name: IF-MODIFIED-SINCE
        in: header
        description: The server will send the requested resource with a 200 status, but only if it has been modified after the given date. (Expects an RFC 2822 timestamp).
        required: false
        schema:
          type: string
          format: date
      - name: IF-NONE-MATCH
        in: header
        description: The server will send the requested resource with a 200 status, but only if the existing resource's [ETag](#section/ETags) doesn't match any of the values listed.
        required: false
        schema:
          type: string
      - name: X-API-VERSION
        in: header
        description: 'The [API minor version](#section/Minor-Versions). Default: latest version.'
        required: false
        schema:
          type: string
      - name: fields
        in: query
        description: The fields to be returned. See response samples for what fields are available. For more information see the [fields section](#section/Fields).
        required: false
        schema:
          type: string
      - name: id
        in: path
        description: The unique identifier for the User.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Ok
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/User_Show'
        '400':
          description: Bad Request
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too Many Requests
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '304':
          description: Not Modified
components:
  schemas:
    Avatar_base:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier for the *Avatar*
        etag:
          type: string
          description: ETag for the *Avatar*
        created_at:
          type: string
          format: date-time
          description: The time the *Avatar* was created (as a ISO-8601 timestamp)
        updated_at:
          type: string
          format: date-time
          description: The time the *Avatar* was last updated (as a ISO-8601 timestamp)
        url:
          type: string
          description: The URL for the *Avatar*
        _destroy:
          type: boolean
          description: Whether to destroy the *Avatar*
    Contact_base:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier for the *Contact*
        etag:
          type: string
          description: ETag for the *Contact*
        name:
          type: string
          description: The full name of the *Contact*
        first_name:
          type: string
          description: First name of the Person
        middle_name:
          type: string
          description: Middle name of the Person
        last_name:
          type: string
          description: Last name of the Person
        date_of_birth:
          type: string
          format: date
          description: Date of birth
        type:
          type: string
          enum:
          - Company
          - Person
          description: The type of the *Contact*
        created_at:
          type: string
          format: date-time
          description: The time the *Contact* was created (as a ISO-8601 timestamp)
        updated_at:
          type: string
          format: date-time
          description: The time the *Contact* was last updated (as a ISO-8601 timestamp)
        prefix:
          type: string
          description: The prefix of the *Contact* (Mr, Mrs, etc)
        title:
          type: string
          description: The designated title of the *Contact*
        initials:
          type: string
          description: The initials of the *Contact*
        clio_connect_email:
          type: string
          description: Clio Connect email if the *Contact* is a ClioConnect User
        locked_clio_connect_email:
          type: boolean
          description: A boolean indicating if the ability to modify this *Contacts Clio connect email is locked.
        client_connect_user_id:
          type: integer
          format: int64
          description: The ID for the Clio Connect user associated with this *Contact*
        primary_email_address:
          type: string
          description: The primary email address associated with this *Contact*.
        secondary_email_address:
          type: string
          description: The secondary email address associated with this *Contact*.
        primary_phone_number:
          type: string
          description: The primary phone number associated with this *Contact*.
        secondary_phone_number:
          type: string
          description: The secondary phone number of the *Contact*.
        ledes_client_id:
          type: string
          description: LEDES client id of the Contact
        has_clio_for_clients_permission:
          type: boolean
          description: True if at least one resource has been shared with the contact using Clio for Clients.
        is_client:
          type: boolean
          description: Whether or not the Contact is a client
        is_clio_for_client_user:
          type: boolean
          description: Whether or not this contact has client_login and client_user (can be created due to addition to client portal or client_share_permissions)
        is_co_counsel:
          type: boolean
          description: Whether or not the Contact has matters shared as co-counsel
        is_bill_recipient:
          type: boolean
          description: Whether the Contact is a bill recipient on at least one matter.
        sales_tax_number:
          type: string
          description: The sales tax number of the *Contact*
        currency:
          type: object
          description: Currency of the *Contact*
    NotificationMethod_base:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier for the *NotificationMethod*
        etag:
          type: string
          description: ETag for the *NotificationMethod*
        type:
          type: string
          enum:
          - Email
          - Popup
          - SMS
          description: Human readable description of the type of notification
        email_address:
          type: string
          description: Email address to send the notification to (only for email type)
        is_default_email_address:
          type: boolean
          description: A boolean that is returned only on notification method objects that are relevant e.g. Email notification or Alternative Email
        created_at:
          type: string
          format: date-time
          description: The time the *NotificationMethod* was created (as a ISO-8601 timestamp)
        updated_at:
          type: string
          format: date-time
          description: The time the *NotificationMethod* was last updated (as a ISO-8601 timestamp)
    Group_base:
      type: object
      properties:
        client_connect_user:
          type: boolean
          description: Whether or not the Group is a UserGroup for a Clio Connect User
        etag:
          type: string
          description: ETag for the *Group*
        id:
          type: integer
          format: int64
          description: Unique identifier for the *Group*
        name:
          type: string
          description: The name of the *Group*
        type:
          type: string
          enum:
          - UserGroup
          - AdhocGroup
          - AccountGroup
          - TeamGroup
          description: The type of the *Group*
        updated_at:
          type: string
          format: date-time
          description: The time the *Group* was last updated (as a ISO-8601 timestamp)
    User_base:
      type: object
      properties:
        account_owner:
          type: boolean
          description: Whether the *User* is the owner of the account
        clio_connect:
          type: boolean
          description: Whether the *User* is a Clio Connect user
        court_rules_default_attendee:
          type: boolean
          description: Whether the *User* is a default attendee for court rules events
        created_at:
          type: string
          format: date-time
          description: The time the *User* was created (as a ISO-8601 timestamp)
        default_calendar_id:
          type: integer
          format: int64
          description: Default calendar id for *User*.
        email:
          type: string
          description: The email of the *User*
        enabled:
          type: boolean
          description: Whether the *User* is allowed to log in
        etag:
          type: string
          description: ETag for the *User*
        first_name:
          type: string
          description: The first name of the *User*
        id:
          type: integer
          format: int64
          description: Unique identifier for the *User*
        initials:
          type: string
          description: The initials of the *User*
        last_name:
          type: string
          description: The last name of the *User*
        name:
          type: string
          description: The full name of the *User*
        phone_number:
          type: string
          description: The primary phone number for the *User*.
        rate:
          type: number
          format: float
          description: Default user activity rate for *User*.
        roles:
          type: array
          items:
            type: string
          description: An array of roles assigned to this *User*
        subscription_type:
          type: string
          enum:
          - Attorney
          - NonAttorney
          description: The subscription type of the *User*
        time_zone:
          type: string
          description: The selected time zone of the *User*
        updated_at:
          type: string
          format: date-time
          description: The time the *User* was last updated (as a ISO-8601 timestamp)
    ActivityDescription_base:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier for the *ActivityDescription*
        etag:
          type: string
          description: ETag for the *ActivityDescription*
        name:
          type: string
          description: The name of the *ActivityDescription*
        visible_to_co_counsel:
          type: boolean
          description: A toggle that determines if a co-counsel user of the firm can have access to this activity description
        created_at:
          type: string
          format: date-time
          description: The time the *ActivityDescription* was created (as a ISO-8601 timestamp)
        updated_at:
          type: string
          format: date-time
          description: The time the *ActivityDescription* was last updated (as a ISO-8601 timestamp)
        default:
          type: boolean
          description: Whether it is the user's default activity description
        type:
          type: string
          description: The type of the *ActivityDescription*
        utbms_activity_id:
          type: integer
          format: int64
          description: The UTBMS activity id if the *ActivityDescription* is a UTBMS activity description
        utbms_task_name:
          type: string
          description: The UTBMS activity task name if attached to a UTBMS activity description
        utbms_task_id:
          type: integer
          format: int64
          description: The UTBMS activity task id if attached to a UTBMS activity description
        xero_service_code:
          type: string
          description: Custom Xero service code for this activity description
        accessible_to_user:
          type: boolean
          description: Determines if activity description is accessible to user
        category_type:
          type: string
          description: Activity category rate type. Either hourly or flat fee
        currency:
          type: object
          description: The currency of the activity description
    Account_base:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier for the *Account*
        etag:
          type: string
          description: ETag for the *Account*
        name:
          type: string
          description: The name of the *Account*
        state:
          type: string
          description: Account state
        created_at:
          type: string
          format: date-time
          description: The time the *Account* was created (as a ISO-8601 timestamp)
        updated_at:
          type: string
          format: date-time
          description: The time the *Account* was last updated (as a ISO-8601 timestamp)
    ErrorDetail:
      type: object
      required:
      - type
      - message
      properties:
        type:
          type: string
          description: Unique name for this error
        message:
          type: string
          description: Detailed message about the error
    User_List:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          description: User List Response
          items:
            $ref: '#/components/schemas/User'
    JobTitle_base:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier for the *JobTitle*
        etag:
          type: string
          description: ETag for the *JobTitle*
        name:
          type: string
          description: Name of the job title
        initials:
          type: string
          description: Initials of the job title
    Error:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
    User:
      allOf:
      - $ref: '#/components/schemas/User_base'
      - type: object
        properties:
          default_activity_description:
            $ref: '#/components/schemas/ActivityDescription_base'
            description: ActivityDescription
          notification_methods:
            type: array
            items:
              $ref: '#/components/schemas/NotificationMethod_base'
            description: NotificationMethod
          account:
            $ref: '#/components/schemas/Account_base'
            description: Account
          avatar:
            $ref: '#/components/schemas/Avatar_base'
            description: Avatar
          contact:
            $ref: '#/components/schemas/Contact_base'
            description: Contact
          job_title:
            $ref: '#/components/schemas/JobTitle_base'
            description: JobTitle
          groups:
            type: array
            items:
              $ref: '#/components/schemas/Group_base'
            description: Group
    User_Show:
      type: object
      required:
      - data
      properties:
        data:
          $ref: '#/components/schemas/User'
x-tagGroups:
- name: Api
  tags:
  - Custom Actions
  - Webhooks
- name: Activities
  tags:
  - Activities
  - Activity Descriptions
  - Activity Rates
  - Expense Categories
  - Timers
  - Utbms Codes
  - Utbms Sets
- name: Accounting
  tags:
  - Bank Accounts
  - Bank Transactions
  - Bank Transfers
- name: Billing
  tags:
  - Bills
  - Billable Clients
  - Billable Matters
  - Bill Themes
  - Interest Charges
  - Line Items
  - Outstanding Client Balances
- name: Calendars
  tags:
  - Calendars
  - Calendar Entries
  - Calendar Entry Event Types
  - Calendar Visibilities
  - Reminders
- name: Clio Payments
  tags:
  - Clio Payments Links
  - Clio Payments Payments
- name: Communications
  tags:
  - Communications
  - Conversations
  - Conversation Messages
- name: Contacts
  tags:
  - Contacts
  - Email Addresses
  - Phone Numbers
  - Notes
  - Log Entries
- name: Court Rules
  tags:
  - Jurisdictions To Triggers
  - Jurisdictions
  - Matter Dockets
  - Service Types
- name: Custom Fields
  tags:
  - Custom Fields
  - Custom Field Sets
- name: Documents
  tags:
  - Documents
  - Document Versions
  - Folders
  - Document Archives
  - Document Automations
  - Document Categories
  - Document Templates
  - Comments
- name: In-app Notifications
  tags:
  - My Events
  - Event Metrics
- name: Matters
  tags:
  - Matters
  - Relationships
  - Clients
  - Related Contacts
  - Matter Contacts
  - Notes
  - Practice Areas
  - Log Entries
  - Matter Stages
  - Medical Records Details
  - Medical Records
  - Medical Bills
  - Damages
- name: Payments
  tags:
  - Allocations
  - Credit Memos
- name: Reporting
  tags:
  - Reports
  - Report Presets
  - Report Schedules
- name: Settings
  tags:
  - Text Snippets
  - Billing Settings
  - Currencies
  - Tax Rate Configurations
- name: Tasks
  tags:
  - Tasks
  - Task Templates
  - Task Template Lists
  - Task Types
- name: Trust
  tags:
  - Trust Line Items
  - Trust Requests
- name: Users
  tags:
  - Users
  - Groups
- name: Legal Aid US
  tags:
  - Grants
  - Grant Funding Sources
- name: Legal Aid England & Wales
  tags:
  - Civil Controlled Rates
  - Civil Certificated Rates
  - Criminal Controlled Rates
  - Expense Categories