openapi: 3.2.0
info:
  title: Lawmatics OAuth Custom Fields API
  version: 1.22.0
  description: 'The official Lawmatics REST API for legal CRM, client intake and law firm automation. Manage matters (prospects), contacts, companies, custom forms and form entries, custom fields, events and appointments, tasks, notes, files, tags, users, time entries, expenses, invoices and transactions.


    Authentication is OAuth 2.0 authorization code grant; access tokens do not expire, there are no refresh tokens, and Lawmatics does not currently support scopes - an authorized app receives full CRUD access to the granted account.


    All list endpoints support the shared query-parameter grammar documented in the Param Guide: `fields` (field selection, one level deep, `fields=all` to expand), `page` (pagination), `sort_by`/`sort_order`, and `filter_by`/`filter_on`/`filter_with` (one filter at a time; operators `=`, `!=`, `<=`, `<`, `>=`, `>`, `like`, `ilike`, `null`, `not_null`).


    Responses follow a JSON:API-style `data` / `attributes` / `relationships` envelope.'
  contact:
    name: Lawmatics API Support
    email: api@lawmatics.com
    url: https://docs.lawmatics.com/
  termsOfService: https://www.lawmatics.com/terms-of-use
servers:
- url: https://api.lawmatics.com
  description: Lawmatics production API
security:
- oauth2: []
- bearerAuth: []
tags:
- name: Custom Fields
paths:
  /v1/custom_fields/{custom_field_id}:
    get:
      operationId: getCustomField
      summary: Custom Field
      description: Specific Custom Field metadata by ID
      tags:
      - Custom Fields
      parameters:
      - name: custom_field_id
        in: path
        required: true
        description: The custom field id
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              examples:
                getCustomField:
                  summary: GET Custom Field
                  value:
                    data:
                      id: '13'
                      type: custom_field
                      attributes:
                        name: Jurisdiction
                        type: PracticeArea
                        field_type: list
                        practice_area: Criminal Defense
                        list_options:
                        - id: 4
                          name: West County
                        - id: 3
                          name: East County
                        - id: 2
                          name: South County
                        - id: 1
                          name: North County
                        created_at: '2018-01-08T10:05:25.432-08:00'
                        updated_at: '2018-01-08T10:05:25.432-08:00'
        '401':
          description: Unauthorized - missing or invalid OAuth 2.0 bearer token
        '429':
          description: Too Many Requests - the per-firm rate limit was exceeded; a Retry-After header is returned
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
    put:
      operationId: updateCustomField
      summary: Update Custom Field
      description: Update an existing Custom Field by ID.
      tags:
      - Custom Fields
      parameters:
      - name: custom_field_id
        in: path
        required: true
        description: The custom field id
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              name: Jurisprudence 6ada4e0f-2d2b-4915-90dd-60851e0cb64b
              type: Contact
              field_type: multi_picklist
              list_options:
              - 10
              - 20
              - 30
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              examples:
                putUpdateCustomField:
                  summary: PUT Update Custom Field
                  value:
                    data:
                      id: '7'
                      type: custom_field
                      attributes:
                        name: Jurisprudence
                        type: Contact
                        field_type: multi_picklist
                        list_options:
                        - id: 18
                          name: '10'
                        - id: 19
                          name: '20'
                        - id: 20
                          name: '30'
                        created_at: '2022-06-02T12:03:29.977-07:00'
                        updated_at: '2022-06-02T12:06:07.154-07:00'
                        visibility: default
        '401':
          description: Unauthorized - missing or invalid OAuth 2.0 bearer token
        '429':
          description: Too Many Requests - the per-firm rate limit was exceeded; a Retry-After header is returned
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
    delete:
      operationId: deleteCustomField
      summary: Delete Custom Field
      tags:
      - Custom Fields
      parameters:
      - name: custom_field_id
        in: path
        required: true
        description: The custom field id
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              examples:
                deleteDeleteCustomField:
                  summary: DELETE Delete Custom Field
                  value:
                    data:
                      id: '7'
                      type: custom_field
                      attributes:
                        name: Jurisprudence
                        type: Contact
                        field_type: multi_picklist
                        list_options: []
                        created_at: '2022-06-02T12:03:29.977-07:00'
                        updated_at: '2022-06-02T12:10:42.915-07:00'
                        visibility: default
        '401':
          description: Unauthorized - missing or invalid OAuth 2.0 bearer token
        '429':
          description: Too Many Requests - the per-firm rate limit was exceeded; a Retry-After header is returned
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
  /v1/custom_fields:
    get:
      operationId: getCustomFields
      summary: Custom Fields
      description: A paginated list of all Custom Field metadata in Lawmatics
      tags:
      - Custom Fields
      parameters:
      - name: fields
        in: query
        required: false
        schema:
          type: string
        example: all
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              examples:
                getCustomFields:
                  summary: GET Custom Fields
                  value:
                    data:
                    - id: '4638'
                      type: custom_field
                      attributes:
                        name: Test Date
                        field_type: date
                        visibility: default
                        type: Prospect
                        created_at: '2018-09-24T12:31:05.231-07:00'
                        updated_at: '2018-10-12T14:23:23.732-07:00'
                    - id: '1'
                      type: custom_field
                      attributes:
                        name: Test Practice Area Checkbox
                        field_type: boolean
                        visibility: default
                        type: PracticeArea
                        created_at: '2018-07-17T15:27:16.765-07:00'
                        updated_at: '2018-10-12T14:24:58.670-07:00'
                    - id: '4627'
                      type: custom_field
                      attributes:
                        name: Test User Lookup
                        field_type: lookup
                        visibility: default
                        type: Prospect
                        lookup_type: User
                        created_at: '2018-08-28T17:19:04.897-07:00'
                        updated_at: '2018-10-12T14:22:00.976-07:00'
                    - id: '4639'
                      type: custom_field
                      attributes:
                        name: Test Time
                        field_type: time
                        visibility: default
                        type: Prospect
                        created_at: '2018-09-24T12:31:15.295-07:00'
                        updated_at: '2018-10-12T14:23:35.585-07:00'
                    - id: '4644'
                      type: custom_field
                      attributes:
                        name: Test Contact String
                        field_type: string
                        visibility: default
                        type: Contact
                        created_at: '2018-10-10T17:38:24.915-07:00'
                        updated_at: '2018-10-12T14:24:42.034-07:00'
                    - id: '4631'
                      type: custom_field
                      attributes:
                        name: Test DateTime
                        field_type: datetime
                        visibility: hidden
                        type: Prospect
                        created_at: '2018-09-06T16:33:22.026-07:00'
                        updated_at: '2018-10-12T14:23:43.570-07:00'
                    - id: '7'
                      type: custom_field
                      attributes:
                        name: Test Client String
                        field_type: string
                        visibility: default
                        type: Client
                        created_at: '2018-07-22T13:37:40.043-07:00'
                        updated_at: '2018-10-12T14:24:01.079-07:00'
                    - id: '4'
                      type: custom_field
                      attributes:
                        name: Test Client Currency
                        field_type: currency
                        visibility: default
                        type: Client
                        created_at: '2018-07-22T13:00:57.587-07:00'
                        updated_at: '2018-10-12T14:24:08.556-07:00'
                    - id: '2'
                      type: custom_field
                      attributes:
                        name: Status
                        field_type: list
                        visibility: default
                        type: Prospect
                        list_options:
                        - id: 1
                          name: Open
                        - id: 2
                          name: Closed Won
                        - id: 3
                          name: Closed Lost
                        created_at: '2018-07-21T10:30:31.322-07:00'
                        updated_at: '2018-08-23T16:53:20.710-07:00'
                    - id: '5'
                      type: custom_field
                      attributes:
                        name: Test Practice Area Text
                        field_type: text
                        visibility: default
                        type: PracticeArea
                        created_at: '2018-07-22T13:01:26.681-07:00'
                        updated_at: '2018-10-12T14:24:48.621-07:00'
                    - id: '8'
                      type: custom_field
                      attributes:
                        name: Test Money Field
                        field_type: currency
                        visibility: default
                        type: Prospect
                        created_at: '2018-07-22T14:25:40.345-07:00'
                        updated_at: '2018-08-23T16:53:20.807-07:00'
                    - id: '9'
                      type: custom_field
                      attributes:
                        name: Test PNC Lookup
                        field_type: lookup
                        visibility: starred
                        type: Prospect
                        lookup_type: Prospect
                        created_at: '2018-08-03T18:12:09.181-07:00'
                        updated_at: '2018-10-12T14:22:44.470-07:00'
                    - id: '6'
                      type: custom_field
                      attributes:
                        name: Test PNC Picklist
                        field_type: list
                        visibility: starred
                        type: Prospect
                        list_options:
                        - id: 9
                          name: Blue
                        - id: 11
                          name: Red
                        created_at: '2018-07-22T13:17:19.943-07:00'
                        updated_at: '2018-08-23T16:53:20.791-07:00'
        '401':
          description: Unauthorized - missing or invalid OAuth 2.0 bearer token
        '429':
          description: Too Many Requests - the per-firm rate limit was exceeded; a Retry-After header is returned
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
    post:
      operationId: createCustomField
      summary: Create Custom Field
      description: 'Create a new Custom Field


        Name: Custom Field''s name


        Type: One of Matter, Contact, Company, Client, or PracticeArea


        Visibility (optional): starred, hidden, default (default)


        field_type: One of integer, boolean, string, text, currency, date, time, datetime, list, lookup, multi_picklist


        list_options: Required if field_type is list or multi_picklist, two options at minimum


        lookup_type: Required if field_type is lookup. One of User, Contact, Company or Prospect


        practice_area: Name of practice area. Required if type is PracticeArea'
      tags:
      - Custom Fields
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              name: Jurisdiction b50ceffa-1b5b-40c8-8a36-248485ee0eaf
              type: PracticeArea
              field_type: list
              practice_area: Divorce
              list_options:
              - one
              - two
              - three
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
              examples:
                postCreateCustomField:
                  summary: POST Create Custom Field
                  value:
                    data:
                      id: '5'
                      type: custom_field
                      attributes:
                        name: Jurisdiction
                        type: Prospect
                        field_type: list
                        practice_area: High Treason
                        list_options:
                        - id: 7
                          name: one
                        - id: 8
                          name: two
                        - id: 9
                          name: three
                        created_at: '2022-06-01T16:09:06.943-07:00'
                        updated_at: '2022-06-01T16:09:06.943-07:00'
                        visibility: default
        '401':
          description: Unauthorized - missing or invalid OAuth 2.0 bearer token
        '429':
          description: Too Many Requests - the per-firm rate limit was exceeded; a Retry-After header is returned
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization code grant. Register a developer app at https://app.lawmatics.com/settings/developers (developer settings must be enabled by Lawmatics support). Access tokens are non-expiring; no refresh tokens are issued and scopes are not supported.
      flows:
        authorizationCode:
          authorizationUrl: https://app.lawmatics.com/oauth/authorize
          tokenUrl: https://api.lawmatics.com/oauth/token
          scopes: {}
    bearerAuth:
      type: http
      scheme: bearer
      description: 'The OAuth 2.0 access token is sent as `Authorization: Bearer <access_token>`.'
externalDocs:
  description: Official Lawmatics RESTful API documentation (Postman)
  url: https://docs.lawmatics.com/
x-provenance:
  generated: '2026-08-13'
  method: derived
  publisher: API Evangelist
  source: https://docs.lawmatics.com/api/collections/26379991/2sA3JM7gbw?segregateAuth=true&versionTag=latest
  source_type: Postman collection published by Lawmatics as its official API documentation
  source_file: postman/lawmatics-oauth-api.postman_collection.json
  note: 'NOT published by Lawmatics. Lawmatics publishes no OpenAPI. Every path, method, parameter, request example and response example in this document was converted mechanically from the provider-published Postman collection "Lawmatics OAuth API v1.22.0"; nothing was invented. Schemas are typed as generic objects because the collection carries examples, not JSON Schema. The server URL is the base documented in the collection Param Guide (https://api.lawmatics.com), not the collection''s disabled {{host}} placeholder. The 401 and 429 responses added to every authenticated operation are the provider-documented, globally applicable responses: the collection''s auth guide states a per-firm rate limit applies to all endpoints and returns 429 with a Retry-After header, and https://api.lawmatics.com/v1/contacts was observed returning 401 unauthenticated on 2026-08-13.'