--- title: "Matter data model" url: "https://docs.unified.to/legal/matter/model" description: "The Matter data model object in Unified's Matter API: 24 fields, including created_at, updated_at and name, with types and enum values." --- # Matter data model View field support, webhooks, and list parameters for each integration on the [Supported Integrations](https://docs.unified.to/legal/integrations.md) page. | Field | Type | Required | Description | | ---------------------------- | -------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | | id | string | No | | | created\_at | string (date-time) | No | (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format) | | updated\_at | string (date-time) | No | (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format) | | name | string | No | | | number | string | No | the firm's display/matter number | | description | string | No | | | status | enum | No | Values: PENDING, OPEN, CLOSED, OTHER | | billing\_method | enum | No | Values: HOURLY, FLAT\_FEE, CONTINGENCY, OTHER | | practicearea\_id | string | No | pointer to the Legal Practicearea object | | stage | string | No | the matter stage name | | contact\_ids | string\[\] | No | CRM Contacts that are clients on this matter | | company\_ids | string\[\] | No | CRM Companies that are clients on this matter | | parties | [LegalParty](https://docs.unified.to/legal/matter/model.md#LegalParty)\[\] | No | all people and organizations related to this matter, with their role | | parties\[\].contact\_id | string | No | pointer to a CRM Contact | | parties\[\].company\_id | string | No | pointer to a CRM Company | | parties\[\].role | enum | No | Values: CLIENT, OPPOSING\_PARTY, OPPOSING\_COUNSEL, CO\_COUNSEL, WITNESS, EXPERT, JUDGE, REFERRER, OTHER | | parties\[\].description | string | No | the vendor's free-text relationship description | | user\_id | string | No | HR Employee who is the responsible attorney (reference to HrisEmployee) | | originating\_user\_id | string | No | HR Employee who is the originating attorney (reference to HrisEmployee) | | user\_ids | string\[\] | No | other HR Employees assigned to this matter | | client\_reference | string | No | the client's own reference number for this matter | | currency | string | No | | | is\_billable | boolean | No | | | opened\_at | string (date-time) | No | (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format) | | closed\_at | string (date-time) | No | (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format) | | pending\_at | string (date-time) | No | (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format) | | statute\_of\_limitations\_at | string (date-time) | No | (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format) | | metadata | [LegalMetadata](https://docs.unified.to/legal/matter/model.md#LegalMetadata)\[\] | No | custom field values | | metadata\[\].id | string | No | | | metadata\[\].slug | string | No | | | metadata\[\].value | object | No | | | metadata\[\].namespace | string | No | | | metadata\[\].format | enum | No | Values: TEXT, NUMBER, DATE, BOOLEAN, FILE, TEXTAREA, SINGLE\_SELECT, MULTIPLE\_SELECT, MEASUREMENT, PRICE, YES\_NO, CURRENCY, URL | | metadata\[\].extra\_data | object | No | | ## TypeScript ```typescript export type LegalMatter = { id?: string; created_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format) updated_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format) name?: string; number?: string; // the firm's display/matter number description?: string; status?: 'PENDING' | 'OPEN' | 'CLOSED' | 'OTHER'; billing_method?: 'HOURLY' | 'FLAT_FEE' | 'CONTINGENCY' | 'OTHER'; 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?: []; // all people and organizations related to this matter, with their role 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; is_billable?: boolean; opened_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format) closed_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format) pending_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format) statute_of_limitations_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format) metadata?: []; // custom field values raw?: any; } ``` ## Zod ```typescript import { z } from 'zod'; export const ZodLegalMatter = z.object({ id: z.string().optional(), created_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"), updated_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"), name: z.string().optional(), number: z.string().optional().describe("the firm's display/matter number"), description: z.string().optional(), status: z.enum("PENDING", "OPEN", "CLOSED", "OTHER").optional(), billing_method: z.enum("HOURLY", "FLAT_FEE", "CONTINGENCY", "OTHER").optional(), practicearea_id: z.string().optional().describe("pointer to the Legal Practicearea object"), stage: z.string().optional().describe("the matter stage name"), contact_ids: z.array().optional().describe("CRM Contacts that are clients on this matter"), company_ids: z.array().optional().describe("CRM Companies that are clients on this matter"), parties: z.array().optional().describe("all people and organizations related to this matter, with their role"), user_id: z.string().optional().describe("HR Employee who is the responsible attorney (reference to HrisEmployee)"), originating_user_id: z.string().optional().describe("HR Employee who is the originating attorney (reference to HrisEmployee)"), user_ids: z.array().optional().describe("other HR Employees assigned to this matter"), client_reference: z.string().optional().describe("the client's own reference number for this matter"), currency: z.string().optional(), is_billable: z.boolean().optional(), opened_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"), closed_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"), pending_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"), statute_of_limitations_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"), metadata: z.array().optional().describe("custom field values"), }); ``` ## Python ```python import dataclasses @dataclasses.dataclass class LegalMatterStatus(str, Enum): PENDING = 'PENDING' OPEN = 'OPEN' CLOSED = 'CLOSED' OTHER = 'OTHER' @dataclasses.dataclass class LegalMatterBilling_method(str, Enum): HOURLY = 'HOURLY' FLAT_FEE = 'FLAT_FEE' CONTINGENCY = 'CONTINGENCY' OTHER = 'OTHER' @dataclasses.dataclass class LegalMatter: id: Optional[str] """(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)""" created_at: Optional[str] """(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)""" updated_at: Optional[str] name: Optional[str] """the firm's display/matter number""" number: Optional[str] description: Optional[str] status: Optional[LegalMatterStatus] billing_method: Optional[LegalMatterBilling_method] """pointer to the Legal Practicearea object""" practicearea_id: Optional[str] """the matter stage name""" stage: Optional[str] """CRM Contacts that are clients on this matter""" contact_ids: Optional[List[List[str]]] """CRM Companies that are clients on this matter""" company_ids: Optional[List[List[str]]] """all people and organizations related to this matter, with their role""" parties: Optional[PropertyLegalMatterParties] """HR Employee who is the responsible attorney (reference to HrisEmployee)""" user_id: Optional[str] """HR Employee who is the originating attorney (reference to HrisEmployee)""" originating_user_id: Optional[str] """other HR Employees assigned to this matter""" user_ids: Optional[List[List[str]]] """the client's own reference number for this matter""" client_reference: Optional[str] currency: Optional[str] is_billable: Optional[bool] """(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)""" opened_at: Optional[str] """(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)""" closed_at: Optional[str] """(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)""" pending_at: Optional[str] """(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)""" statute_of_limitations_at: Optional[str] """custom field values""" metadata: Optional[PropertyLegalMatterMetadata] ```