---
title: "Create a matter"
method: POST
path: "/matters"
tags: ["Matters"]
---

# Create a matter

`POST /matters`

Creates a new matter.
            
Note: This endpoint can also be used to create a `Lead`.

When creating a `Lead` you MUST remember to set a valid lead specific `matterTypeId` field (see field description below for more details) and set the `isLead` field to true.

The `clientRole` and `otherSideRole` are optional and cannot be identical. They will be set to the default role(s) for the specified matter type - if not provided.

## Request body

- MatterDto
  - `externalSystemId` string, nullable — External system id for the matter.
  - `number` string, nullable — Human-friendly number assigned to matter.
  - `matterTypeId` string, nullable — Unique identifier of the matter type associated with the matter. Matter types define what information can be saved to the matter, relevant to that area of law and state / location. A pre-configured list of matter types can be obtained via the 'GET /mattertypes' API. 'Lead' matter types are different from the standard matter types used when creating a 'Matter'. Use the 'Type' query parameter in the 'GET /mattertypes' API call to get 'Lead' specific matter types.
  - `clientIds` string[], nullable — List of 'Client' contact id's associated with the matter.
  - `otherSideIds` string[], nullable — List of 'OtherSide' contact id's associated with the matter.
  - `branchId` string, nullable — Unique identifier of the associated branch.
  - `branchProviderId` string, nullable — Unique identifier of the associated branch provider.
  - `clientRole` string, nullable — 'Client' matter type representative option for the matter. If unsure, this can be left empty and the default Client role will be used.
  - `otherSideRole` string, nullable — 'OtherSide' matter type representative option for the matter. If unsure, this can be left empty and the default OtherSide role will be used.
  - `description` string, nullable — Brief description of the matter.
  - `status` string, nullable — Current status of matter. Possible values: Open, Pending, Closed, Deleted or Cancelled.
  - `openedDate` string, date-time, nullable — Date the matter was opened. This can be backdated if required.
  - `closedDate` string, date-time, nullable — Date the matter was closed. This can be backdated if required.
  - `leadOpenedDate` string, date-time, nullable — Date the lead was opened. This can be backdated if required. Only applies if isLead is true.
  - `leadClosedDate` string, date-time, nullable — Date the lead was closed. This can be backdated if required. Only applies if isLead is true.
  - `leadClosedReason` string, nullable — Reason the lead was closed. Only applies if isLead is true.
  - `referralType` string, nullable — Referral Type of the matter. Custom Referral Types are also supported, the name or id of the Custom Referral Type can be used. If the name is used, it is looked up and stored as the id. See the Referral Types API for retrieval of all valid Referral Types. Possible values may also differ per region.
  - `referrerId` string, nullable — Contact id of the person that referred the matter.
  - `referralAgreementFeeType` string, nullable — The referral agreement fee type. Possible values: %, Flat fee, Other
  - `referralAgreementFee` number, double, nullable — The referral agreement fee value.
  - `referralAgreementFeeComment` string, nullable — The referral agreement fee comment.
  - `personResponsibleStaffId` string, nullable — Staff id of the person responsible for the matter (if applicable).
  - `personAssistingStaffId` string, nullable — Staff id of the person assisting in the matter (if applicable).
  - `personAssistingStaffIds` string[], nullable — Staff ids of the other persons assisting in the matter (if applicable).
  - `originatingStaffId` string, nullable — Staff id of the originating attorney (if in US) or an Introducer (if in AU)
  - `originatingStaffIds` string[], nullable — Staff ids of the other originating attorneys (if in US) or an Introducer (if in AU) Required when SplitOriginatingStaffSettings is provided and enabled.
  - `splitOriginatingStaffSettings` SplitMatterStaffSettingsDto
    - `isEnabled` boolean — Indicates whether the split matter staff settings are enabled or not.
    - `splitMatterStaffs` SplitMatterStaffDto[], nullable — List of staff members involved in the split matter settings.
      - `matterStaffId` string, nullable — The unique identifier for the split matter staff.
      - `matterStaffRatio` integer — The split ratio for the matter staff.
    - `splitMethod` string, nullable — Method used to split the matter staff. Possible values: Unknown, SplitEvenly, UseRatio.
    - `remainderStaffId` string, nullable — The unique identifier for the staff member who will handle the remainder of the matter after the split.
  - `supervisorStaffId` string, nullable — Staff id of the supervisor of the matter. Only supported in the UK.
  - `clientCode` string, nullable — Associates an external client code to this matter. Only supported in AU and UK.
  - `isLead` boolean — Optional boolean flag indicating if a 'Lead' is being created. This must be set to 'true' when creating a 'Lead'.

## Response `202`

When request is accepted. Returns a hypermedia 'Link' object of the matter to be created.

- Link
  - `id` string, nullable
  - `href` string, nullable
  - `relation` string, nullable
  - `method` string, nullable

## Other responses

- `400` — When an unsupported request is made or a mandatory field - i.e. client, matter type, status - is not provided.

---

[API](https://skmtc.net/smokeball/apis/api.md) · [All operations](https://skmtc.net/smokeball/apis/api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/smokeball/api/revisions/197984da9b42/schema)