openapi: 3.2.0
info:
  title: Lawmatics OAuth Folders 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: Folders
paths:
  /v1/folders/{folder_id}:
    get:
      operationId: getFolder
      summary: Folder
      description: A specific Folder's metadata in Lawmatics
      tags:
      - Folders
      parameters:
      - name: folder_id
        in: path
        required: true
        description: The folder id
        schema:
          type: string
      responses:
        default:
          description: Example response captured in the source Postman collection; the HTTP status code was not recorded by the publisher.
          content:
            application/json:
              schema:
                type: object
              examples:
                getFolder:
                  summary: GET Folder
                  value:
                    data:
                      id: '3'
                      type: folder
                      attributes:
                        name: images
                        created_at: '2023-07-06T15:58:41.855-07:00'
                        updated_at: '2023-07-06T15:58:41.855-07:00'
                      relationships:
                        documentable:
                          data:
                            id: '144'
                            type: prospect
        '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: updateFolder
      summary: Update Folder
      description: 'Updates a Folder by ID


        documentable_type: One of ["matter", "contact"]


        documentable_id: The record ID


        name: Folder name. Must be unique within parent folder. Returns 429 if name is already taken. Any slashes "/" in folder name will be replaces with colons ":"


        folder_id: Folder ID if adding a subfolder


        path: String Array. e.g. ["Root", "Folder 1", "Folder 2"]. Finds folders with the name or creates it if it doesn''t exist. Moves folder into the Folder with the last name in the path. path overrides folder_id if both given.'
      tags:
      - Folders
      parameters:
      - name: folder_id
        in: path
        required: true
        description: The folder id
        schema:
          type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                documentable_type:
                  type: string
                documentable_id:
                  type: string
                name:
                  type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              examples:
                putUpdateFolder:
                  summary: PUT Update Folder
                  value:
                    data:
                      id: '20'
                      type: folder
                      attributes:
                        name: Changed name
                        created_at: '2023-07-07T15:14:15.974-07:00'
                        updated_at: '2023-07-07T15:29:39.922-07:00'
                      relationships:
                        documentable:
                          data:
                            id: '144'
                            type: prospect
                        folders:
                          data: []
                putUpdateSubfolder:
                  summary: PUT Update Subfolder
                  value:
                    data:
                      id: '20'
                      type: folder
                      attributes:
                        name: Subfolder is now a root folder
                        created_at: '2023-07-07T15:14:15.974-07:00'
                        updated_at: '2023-07-10T10:03:45.312-07:00'
                      relationships:
                        documentable:
                          data:
                            id: '225'
                            type: contact
                        folders:
                          data: []
                        files:
                          data: []
                putUpdateSubfolderByFolderPath:
                  summary: PUT Update Subfolder by folder path
                  value:
                    data:
                      id: '164'
                      type: folder
                      attributes:
                        name: bar
                        created_at: '2024-01-19T11:29:34.054-08:00'
                        updated_at: '2024-01-19T11:41:57.557-08:00'
                      relationships:
                        documentable:
                          data:
                            id: '143'
                            type: prospect
                        folders:
                          data:
                          - id: '159'
                            type: folder
                        files:
                          data:
                          - id: '159'
                            type: file
        '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: deleteFolder
      summary: Delete Folder
      description: Deletes a Folder by ID
      tags:
      - Folders
      parameters:
      - name: folder_id
        in: path
        required: true
        description: The folder id
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              examples:
                deleteFolder:
                  summary: DELETE Folder
                  value:
                    data:
                      id: '17'
                      type: folder
                      attributes:
                        name: videos
                        created_at: '2023-07-07T14:55:12.311-07:00'
                        updated_at: '2023-07-07T14:55:37.861-07:00'
                      relationships:
                        documentable:
                          data:
                            id: '144'
                            type: prospect
                        folders:
                          data: []
        '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/folders:
    get:
      operationId: getFolders
      summary: Folders
      description: 'A paginated list of all Folder metadata in Lawmatics


        Can be filtered by matter_id , prospect_id , contact_id


        as well as all the regular fields as referenced by our Param Guide (most fields returned by?fields=all).'
      tags:
      - Folders
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              examples:
                getFolders:
                  summary: GET Folders
                  value:
                    data:
                    - id: '11'
                      type: folder
                      attributes:
                        name: eulogy
                        created_at: '2023-07-06T16:10:00.232-07:00'
                        updated_at: '2023-07-06T16:10:00.232-07:00'
                      relationships:
                        documentable:
                          data:
                            id: '142'
                            type: prospect
                    - id: '6'
                      type: folder
                      attributes:
                        name: docs
                        created_at: '2023-07-06T16:01:22.321-07:00'
                        updated_at: '2023-07-06T16:01:22.321-07:00'
                      relationships:
                        documentable:
                          data:
                            id: '144'
                            type: prospect
                    - id: '3'
                      type: folder
                      attributes:
                        name: images
                        created_at: '2023-07-06T15:58:41.855-07:00'
                        updated_at: '2023-07-06T15:58:41.855-07:00'
                      relationships:
                        documentable:
                          data:
                            id: '144'
                            type: prospect
                    meta:
                      total_pages: 1
                      limit_per_page: 25
                      total_entries: 3
                    links:
                      self: /v1/folders?page=1
        '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: createFolder
      summary: Create Folder
      description: 'Creates a folder for a Matter or Contact


        documentable_type: One of ["matter", "contact"]


        documentable_id: The record ID


        name: Folder name. Must be unique within parent folder. Returns 429 if name is already taken. Any slashes "/" in folder name will be replaces with colons ":"


        folder_id: Folder ID if adding a subfolder


        path: String Array. e.g. ["Root", "Folder 1", "Folder 2"]. Finds the folder with the name or creates it if it doesn''t exist. Path overrides folder_id if both given.'
      tags:
      - Folders
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                documentable_type:
                  type: string
                documentable_id:
                  type: string
                name:
                  type: string
                folder_id:
                  type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
              examples:
                postCreateFolder:
                  summary: POST Create Folder
                  value:
                    data:
                      id: '21'
                      type: folder
                      attributes:
                        name: This is a folder
                        created_at: '2023-07-07T15:19:05.673-07:00'
                        updated_at: '2023-07-07T15:19:05.673-07:00'
                        folder_id: 456
                      relationships:
                        documentable:
                          data:
                            id: '144'
                            type: prospect
                        folders:
                          data: []
        default:
          description: Example response captured in the source Postman collection; the HTTP status code was not recorded by the publisher.
        '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.'