---
title: "Create a matter"
method: POST
path: "/legal/{connection_id}/matter"
tags: ["legal", "matter"]
---

# Create a matter

`POST /legal/{connection_id}/matter`

## Request

- Base URL: `https://api.unified.to`
- URL: `https://api.unified.to/legal/{connection_id}/matter`
- Auth: API key in header `authorization`

## Path parameters

- `connection_id` string, required

## Query parameters

- `fields` string[]
- `raw` string

## Request body

- LegalMatter
  - `id` string: unique identifier for the matter
  - `created_at` string, date-time: when the matter was created (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
  - `updated_at` string, date-time: when the matter was last updated (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
  - `name` string: the matter name
  - `number` string: the firm's display/matter number
  - `description` string: free-text description of the matter
  - `status` 'PENDING' | 'OPEN' | 'CLOSED' | 'OTHER': the matter status
  - `billing_method` 'HOURLY' | 'FLAT_FEE' | 'CONTINGENCY' | 'OTHER': how the matter is billed
  - `practicearea_id` string: pointer to the Legal Practicearea object
  - `stage` string: the matter stage name
  - `contact_ids` string[]: CRM Contacts that are clients on this matter
  - `company_ids` string[]: CRM Companies that are clients on this matter
  - `parties` LegalParty[]: all people and organizations related to this matter, with their role
    - `contact_id` string: pointer to a CRM Contact
    - `company_id` string: pointer to a CRM Company
    - `role` 'CLIENT' | 'OPPOSING_PARTY' | 'OPPOSING_COUNSEL' | 'CO_COUNSEL' | 'WITNESS' | 'EXPERT' | 'JUDGE' | 'REFERRER' | 'OTHER': the party role on the matter
    - `description` string: the vendor's free-text relationship description
  - `user_id` string: HR Employee who is the responsible attorney (reference to HrisEmployee)
  - `originating_user_id` string: HR Employee who is the originating attorney (reference to HrisEmployee)
  - `user_ids` string[]: other HR Employees assigned to this matter
  - `client_reference` string: the client's own reference number for this matter
  - `currency` string: ISO 4217 currency code
  - `is_billable` boolean: whether the matter is billable
  - `opened_at` string, date-time: when the matter was opened (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
  - `closed_at` string, date-time: when the matter was closed (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
  - `pending_at` string, date-time: when the matter became pending (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
  - `statute_of_limitations_at` string, date-time: statute of limitations deadline for the matter (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
  - `metadata` LegalMetadata[]: custom field values
    - `id` string: the custom field identifier
    - `slug` string: the custom field key
    - `value` union: the custom field value
      - object
      - string
      - number
      - boolean
      - union[]
        - union
          - object
          - string
          - number
          - boolean
    - `namespace` string: the scope or origin of the custom field
    - `format` 'TEXT' | 'NUMBER' | 'DATE' | 'BOOLEAN' | 'FILE' | 'TEXTAREA' | 'SINGLE_SELECT' | 'MULTIPLE_SELECT' | 'MEASUREMENT' | 'PRICE' | 'YES_NO' | 'CURRENCY' | 'URL': the data type of the value
    - `extra_data` union: additional data about the custom field
      - object
      - string
      - number
      - boolean
      - union[]
        - union
          - object
          - string
          - number
          - boolean
  - `raw` object: raw data from the integration

## Response `200`

Successful

- LegalMatter
  - `id` string: unique identifier for the matter
  - `created_at` string, date-time: when the matter was created (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
  - `updated_at` string, date-time: when the matter was last updated (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
  - `name` string: the matter name
  - `number` string: the firm's display/matter number
  - `description` string: free-text description of the matter
  - `status` 'PENDING' | 'OPEN' | 'CLOSED' | 'OTHER': the matter status
  - `billing_method` 'HOURLY' | 'FLAT_FEE' | 'CONTINGENCY' | 'OTHER': how the matter is billed
  - `practicearea_id` string: pointer to the Legal Practicearea object
  - `stage` string: the matter stage name
  - `contact_ids` string[]: CRM Contacts that are clients on this matter
  - `company_ids` string[]: CRM Companies that are clients on this matter
  - `parties` LegalParty[]: all people and organizations related to this matter, with their role
    - `contact_id` string: pointer to a CRM Contact
    - `company_id` string: pointer to a CRM Company
    - `role` 'CLIENT' | 'OPPOSING_PARTY' | 'OPPOSING_COUNSEL' | 'CO_COUNSEL' | 'WITNESS' | 'EXPERT' | 'JUDGE' | 'REFERRER' | 'OTHER': the party role on the matter
    - `description` string: the vendor's free-text relationship description
  - `user_id` string: HR Employee who is the responsible attorney (reference to HrisEmployee)
  - `originating_user_id` string: HR Employee who is the originating attorney (reference to HrisEmployee)
  - `user_ids` string[]: other HR Employees assigned to this matter
  - `client_reference` string: the client's own reference number for this matter
  - `currency` string: ISO 4217 currency code
  - `is_billable` boolean: whether the matter is billable
  - `opened_at` string, date-time: when the matter was opened (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
  - `closed_at` string, date-time: when the matter was closed (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
  - `pending_at` string, date-time: when the matter became pending (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
  - `statute_of_limitations_at` string, date-time: statute of limitations deadline for the matter (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
  - `metadata` LegalMetadata[]: custom field values
    - `id` string: the custom field identifier
    - `slug` string: the custom field key
    - `value` union: the custom field value
      - object
      - string
      - number
      - boolean
      - union[]
        - union
          - object
          - string
          - number
          - boolean
    - `namespace` string: the scope or origin of the custom field
    - `format` 'TEXT' | 'NUMBER' | 'DATE' | 'BOOLEAN' | 'FILE' | 'TEXTAREA' | 'SINGLE_SELECT' | 'MULTIPLE_SELECT' | 'MEASUREMENT' | 'PRICE' | 'YES_NO' | 'CURRENCY' | 'URL': the data type of the value
    - `extra_data` union: additional data about the custom field
      - object
      - string
      - number
      - boolean
      - union[]
        - union
          - object
          - string
          - number
          - boolean
  - `raw` object: raw data from the integration

## Changes

- **2026-10-11** `a29ffd62ac71`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/unified/apis/unified-to-api/changes/legal/:connection_id/matter/post.md)

---

[API](https://skmtc.dev/unified/apis/unified-to-api.md) · [All operations](https://skmtc.dev/unified/apis/unified-to-api/llms.txt) · [OpenAPI document](https://skmtc.dev/unified/apis/unified-to-api/revisions/88a1fc7820d6?raw)