---
title: "Create a new Matter"
method: POST
path: "/matters.json"
tags: ["Matters"]
---

# Create a new Matter

`POST /matters.json`

Outlines the parameters and data fields used when creating a new Matter

## Query parameters

- `custom_field_ids[]` integer
- `fields` string

## Headers

- `X-API-VERSION` string

## Request body

- object
  - `data` object, required
    - `billable` boolean — Whether or not the matter is billable.
    - `client` object, required
      - `id` integer, required — The unique identifier for a single Contact associated with the Matter. The keyword `null` is not valid for this field.
    - `client_reference` string — Client Reference string for external uses.
    - `close_date` string, date — Date the Matter was set to closed. (Expects an ISO-8601 date).
    - `currency` object — Currency of the matter
    - `custom_field_set_associations` object[]
      - `display_order` integer — The order to display the CustomFieldSet in a Matter. If not specified, it is added as the last CustomFieldSet of the Matter.
      - `custom_field_set` object, required
        - `id` integer, required — The unique identifier for a single CustomFieldSet associated with the CustomFieldSetAssociation. The keyword `null` is not valid for this field.
    - `custom_field_values` object[]
      - `value` string, required — The value of the CustomFieldValue.
      - `custom_field` object, required
        - `id` integer, required — The unique identifier for a single CustomField associated with the CustomFieldValue. The keyword `null` is not valid for this field.
    - `custom_rate` object
      - `type` 'FlatRate' | 'HourlyRate' | 'ContingencyFee', required — The type of custom rate for the Matter.
      - `rates` object[]
        - `user` object, required
          - `id` integer, required — The unique identifier for a single User associated with the Rate. The keyword `null` is not valid for this field.
        - `award` number, double — The full amount of the award given. Only valid for ContingencyFee. If given as an empty string, it will reset the ContingencyFee into the unawarded state.
        - `note` string — Detailed description of the rate. Only valid for ContingencyFee.
        - `date` string, date — The date the rate is for. Only valid for ContingencyFee. (Expects an ISO-8601 date).
        - `rate` number, double, required — If `type` is `HourlyRate`, it is the dollar amount of the custom rate of the User or Group for the Matter. If `type` is `FlatRate`, it is the dollar amount of the custom flat rate for the Matter. If `type` is `ContingencyFee`, it is the percentage of the contingency fee awarded to the user for the Matter.
        - `activity_description` object
          - `id` integer — The unique identifier for a single ActivityDescription associated with the Rate. The keyword `null` is not valid for this field.
        - `group` object
          - `id` integer — The unique identifier for a single Group associated with the Rate. The keyword `null` is not valid for this field.
    - `description` string, required — Detailed description of the Matter.
    - `display_number` string — Matter reference and label. Depending on the account's manual_matter_numbering setting, this is either read only (generated), or customizable.
    - `evergreen_retainer` object
      - `minimum_threshold` number, double — The trust balance threshold for the Matter. When the balance falls below the threshold, the retainer's associated recipients (firm users) will receive a notification.
      - `recipients` object[]
        - `id` integer — the `id` of a User who will receive the trust balance notification.
        - `_destroy` boolean — Used to remove an existing User as a recipient of the trust balance notification.
    - `group` object
      - `id` integer — The unique identifier for a single Group associated with the Matter. Use the keyword `null` to specify no association.
    - `kyc_field_values` object[]
      - `field_name` string, required — The name of the KYC/KYB field. KYC/KYB fields are available for eligible accounts in Australia, Canada, Channel Islands, Ireland, Isle of Man, New Zealand, and United Kingdom.
      - `field_type` 'date' | 'text' | 'picklist', required — The type of the KYC/KYB field. Must be one of: date, text, picklist.
      - `field_value` string, required — The value of the KYC/KYB field.
    - `location` string — Location of the Matter.
    - `matter_budget` object
      - `_destroy` boolean — Determines whether the matter budget associated with the matter should be destroyed. Only users with matter budget destroy capabilities can destroy matter budgets.
      - `budget` number, double — The amount allocated for the matter.
      - `include_expenses` boolean — Determines whether the budget includes expenses in the calculation.
      - `notification_threshold` integer — Percentage of the budget when it starts notifying users.
      - `notify_users` boolean — Determine whether to notify users when the matter reaches the notification threshold.
    - `matter_stage` object
      - `id` integer — The unique identifier for a single MatterStage associated with the Matter. Use the keyword `null` to specify no association.
    - `open_date` string, date — Date the Matter was set to open. (Expects an ISO-8601 date).
    - `originating_attorney` object
      - `id` integer — The unique identifier for a single User associated with the Matter. The keyword `null` is not valid for this field.
    - `pending_date` string, date — Date the Matter was set to pending. (Expects an ISO-8601 date).
    - `practice_area` object
      - `id` integer — The unique identifier for a single PracticeArea associated with the Matter. Use the keyword `null` to specify no association.
    - `rate_table_assignment` object
      - `rate_table_id` integer, required — The unique identifier for a single RateTableAssignment associated with the Matter. The keyword `null` is not valid for this field.
      - `rate_table_category_id` integer, required — The unique identifier for a single RateTableAssignment associated with the Matter. The keyword `null` is not valid for this field.
    - `relationships` object[]
      - `description` string, required — Describe the relationship between a Contact and a Matter.
      - `contact` object, required
        - `id` integer, required — The unique identifier for a single Contact associated with the Relationship. The keyword `null` is not valid for this field.
    - `require_utbms_codes` boolean — When true, billable time and expense entries on this Matter must include the required UTBMS/LEDES codes before they can be saved. Requires the firm to have mandatory LEDES billing enabled; otherwise the value is ignored.
    - `reset_matter_number` boolean — Defaults to false. Resets the matter's number based on the account's matter numbering scheme.
    - `responsible_attorney` object
      - `id` integer — The unique identifier for a single User associated with the Matter. The keyword `null` is not valid for this field.
    - `responsible_staff` object
      - `id` integer — The unique identifier for a single User associated with the Matter. The keyword `null` is not valid for this field.
    - `split_invoice_payers` object[]
      - `contact_id` integer, required — Contact id for the matter payer.
      - `send_to_bill_recipients` boolean — Boolean indication to send a split invoice to all bill recipients.
      - `split_portion` number, double, required — The split portion for the payer.
    - `status` 'open' | 'closed' | 'pending' — Matter status.
    - `statute_of_limitations` object
      - `status` 'pending' | 'in_progress' | 'in_review' | 'complete' | 'draft' — The task status of Statue of Limitations. Users without advanced tasks are allowed to select `Complete' or `Pending` only.
      - `due_at` string, date — The due date of Statute of Limitations. (Expects an ISO-8601 date).
      - `reminders` object[]
        - `duration_value` integer, required — Time measured in `duration_unit` to remind user before the subject.
        - `duration_unit` string, required — Unit to measure the duration value in.
        - `notification_method` object, required
          - `id` integer, required — The unique identifier for a single NotificationMethod associated with the Reminder. The keyword `null` is not valid for this field.
    - `task_template_list_instances` object[]
      - `task_template_list` object, required
        - `id` integer, required — The unique identifier for a single TaskTemplateList associated with the TaskTemplateListInstance. The keyword `null` is not valid for this field.
      - `assignee_id` integer — The id of the user to assign the task template list to.
      - `notify_assignees` boolean — Whether or not task list assignees should be notified when the task list is assigned to a matter.
      - `due_at` string, date — Due date of the tasks. (Expects an ISO-8601 date).

## Response `201`

Created

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Unprocessable Entity
- `429` — Too Many Requests

---

[API](https://skmtc.net/clio/apis/clio-api-documentation.md) · [All operations](https://skmtc.net/clio/apis/clio-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/clio/clio-api-documentation/versions/73791ddd1207/schema)