Patch a matter

curl --request PATCH \
  --url https://api.smokeball.com/matters/{matterId} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json-patch+json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "externalSystemId": "EXT01",
  "number": "FUS-124",
  "matterTypeId": "009f778f-83df-454a-b344-768a862a7e55",
  "description": "This is a brief description for the matter",
  "status": "Open",
  "dateOpened": "2022-04-23T14:00:00Z",
  "openedDate": "2022-04-23T14:00:00Z",
  "closedDate": "2022-04-23T14:00:00Z",
  "leadOpenedDate": "2022-04-23T14:00:00Z",
  "leadClosedDate": "2022-04-23T14:00:00Z",
  "leadClosedReason": "No longer interested",
  "referralType": "Google",
  "referrerId": "97bbe49f-6460-4bfc-b287-34ddfdbb81ef",
  "referralAgreementFeeType": "<string>",
  "referralAgreementFee": 123,
  "referralAgreementFeeComment": "<string>",
  "personResponsibleStaffId": "c85d28cb-a760-4627-aa59-0a853c2e65ed",
  "personAssistingStaffId": "c85d28cb-a760-4627-aa59-0a853c2e65ed",
  "personAssistingStaffIds": [
    "c85d28cb-a760-4627-aa59-0a853c2e65ed"
  ],
  "originatingStaffId": "c85d28cb-a760-4627-aa59-0a853c2e65ed",
  "originatingStaffIds": [
    "c85d28cb-a760-4627-aa59-0a853c2e65ed"
  ],
  "splitOriginatingStaffSettings": {
    "isEnabled": true,
    "splitMatterStaffs": [
      {
        "matterStaffId": "<string>",
        "matterStaffRatio": 123
      }
    ],
    "splitMethod": "<string>",
    "remainderStaffId": "<string>"
  },
  "supervisorStaffId": "c85d28cb-a760-4627-aa59-0a853c2e65ed",
  "clientCode": "Client A",
  "branchId": "c85d28cb-a760-4627-aa59-0a853c2e65ed",
  "branchProviderId": "c85d28cb-a760-4627-aa59-0a853c2e65ed",
  "clientRole": "Buyer",
  "isLead": false,
  "clientIds": [
    "<string>"
  ],
  "otherSideIds": [
    "<string>"
  ],
  "items": {}
}
'

{
  "id": "<string>",
  "href": "<string>",
  "relation": "<string>",
  "method": "GET"
}

Matters

Patch a matter

Patches a specified matter.

Note: This endpoint can also be used to update a Lead, convert Lead to Matter and change the Lead/Matter type.

See Matters documentation for more details on how to use this.

The following actions are not supported:

items cannot be updated where either clientIds and/or otherSideIds are being updated
items cannot be updated when converting a Lead to Matter or changing the Lead/Matter type
clientRole cannot be updated, unless converting a Lead to Matter or changing the Lead/Matter type
Matter cannot be converted back to Lead
splitOriginatingStaffSettings cannot be updated without also providing originatingStaffIds in the same PATCH request
personAssistingStaffIds cannot contain personAssistingStaffId
originatingStaffIds cannot contain originatingStaffId
If split originating staff settings are enabled, originatingStaffIds and originatingStaffId cannot be updated
When updating via items, client role items and their sub-items must contain at least one item (cannot be empty), while non-client role items and their sub-items can be empty arrays to remove all items

PATCH

matters

{matterId}

Patch a matter

curl --request PATCH \
  --url https://api.smokeball.com/matters/{matterId} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json-patch+json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "externalSystemId": "EXT01",
  "number": "FUS-124",
  "matterTypeId": "009f778f-83df-454a-b344-768a862a7e55",
  "description": "This is a brief description for the matter",
  "status": "Open",
  "dateOpened": "2022-04-23T14:00:00Z",
  "openedDate": "2022-04-23T14:00:00Z",
  "closedDate": "2022-04-23T14:00:00Z",
  "leadOpenedDate": "2022-04-23T14:00:00Z",
  "leadClosedDate": "2022-04-23T14:00:00Z",
  "leadClosedReason": "No longer interested",
  "referralType": "Google",
  "referrerId": "97bbe49f-6460-4bfc-b287-34ddfdbb81ef",
  "referralAgreementFeeType": "<string>",
  "referralAgreementFee": 123,
  "referralAgreementFeeComment": "<string>",
  "personResponsibleStaffId": "c85d28cb-a760-4627-aa59-0a853c2e65ed",
  "personAssistingStaffId": "c85d28cb-a760-4627-aa59-0a853c2e65ed",
  "personAssistingStaffIds": [
    "c85d28cb-a760-4627-aa59-0a853c2e65ed"
  ],
  "originatingStaffId": "c85d28cb-a760-4627-aa59-0a853c2e65ed",
  "originatingStaffIds": [
    "c85d28cb-a760-4627-aa59-0a853c2e65ed"
  ],
  "splitOriginatingStaffSettings": {
    "isEnabled": true,
    "splitMatterStaffs": [
      {
        "matterStaffId": "<string>",
        "matterStaffRatio": 123
      }
    ],
    "splitMethod": "<string>",
    "remainderStaffId": "<string>"
  },
  "supervisorStaffId": "c85d28cb-a760-4627-aa59-0a853c2e65ed",
  "clientCode": "Client A",
  "branchId": "c85d28cb-a760-4627-aa59-0a853c2e65ed",
  "branchProviderId": "c85d28cb-a760-4627-aa59-0a853c2e65ed",
  "clientRole": "Buyer",
  "isLead": false,
  "clientIds": [
    "<string>"
  ],
  "otherSideIds": [
    "<string>"
  ],
  "items": {}
}
'

{
  "id": "<string>",
  "href": "<string>",
  "relation": "<string>",
  "method": "GET"
}

Authorizations

x-api-key

string

header

required

Authorization

string

header

required

Path Parameters

matterId

string<uuid>

required

Body

externalSystemId

string | null

External system id for the matter.

Example:

"EXT01"

number

string | null

Human-friendly number assigned to matter.

Example:

"FUS-124"

matterTypeId

string | null

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.

Example:

"009f778f-83df-454a-b344-768a862a7e55"

description

string | null

Brief description of the matter.

Example:

"This is a brief description for the matter"

status

string | null

Current status of matter.

Possible values: Open, Pending, Closed, Deleted or Cancelled.

Example:

"Open"

dateOpened

string<date-time> | null

Date when the matter was opened. This can be backdated if required.

Example:

"2022-04-23T14:00:00Z"

openedDate

string<date-time> | null

Date the matter was opened. This can be backdated if required.

Example:

"2022-04-23T14:00:00Z"

closedDate

string<date-time> | null

Date the matter was closed. This can be backdated if required.

Example:

"2022-04-23T14:00:00Z"

leadOpenedDate

string<date-time> | null

Date the lead was opened. This can be backdated if required.

Only applies if isLead is true.

Example:

"2022-04-23T14:00:00Z"

leadClosedDate

string<date-time> | null

Date the lead was closed. This can be backdated if required.

Only applies if isLead is true.

Example:

"2022-04-23T14:00:00Z"

leadClosedReason

string | null

Reason the lead was closed.

Only applies if isLead is true.

Example:

"No longer interested"

referralType

string | null

Referral Type of the matter.

Possible values are different per region.

Example:

"Google"

referrerId

string | null

Contact id of the person that referred the matter.

Example:

"97bbe49f-6460-4bfc-b287-34ddfdbb81ef"

referralAgreementFeeType

string | null

The referral agreement fee type.

Possible values: %, Flat fee, Other

referralAgreementFee

number<double> | null

The referral agreement fee value.

referralAgreementFeeComment

string | null

The referral agreement fee comment.

personResponsibleStaffId

string | null

Staff id of the person responsible for the matter (if applicable).

Example:

"c85d28cb-a760-4627-aa59-0a853c2e65ed"

personAssistingStaffId

string | null

Staff id of the person assisting in the matter (if applicable).

Example:

"c85d28cb-a760-4627-aa59-0a853c2e65ed"

personAssistingStaffIds

string[] | null

Staff ids of the other persons assisting in the matter (if applicable).

Example:

["c85d28cb-a760-4627-aa59-0a853c2e65ed"]

originatingStaffId

string | null

Staff id of the originating attorney (if in US) or an Introducer (if in AU)

Example:

"c85d28cb-a760-4627-aa59-0a853c2e65ed"

originatingStaffIds

string[] | null

Staff ids of the other originating attorneys (if in US) or an Introducer (if in AU)

Required when SplitOriginatingStaffSettings is provided and enabled. This field must be included when updating SplitOriginatingStaffSettings.

Example:

["c85d28cb-a760-4627-aa59-0a853c2e65ed"]

splitOriginatingStaffSettings

object

Settings for splitting originating staff members on a matter.

When enabled, this allows distribution of originating staff responsibilities across multiple staff members using either equal splits or custom ratios. The staff IDs specified in SplitMatterStaffs must exactly match the OriginatingStaffIds provided.

OriginatingStaffIds must be included in the same request when updating these settings.

Validation rules:

OriginatingStaffIds must be provided when this setting is enabled
Staff ratios must sum to 10000 (100%) when using UseRatio split method
RemainderStaffId must be one of the staff members in the SplitMatterStaffs collection
No duplicate staff members allowed

Show child attributes

supervisorStaffId

string | null

Staff id of the supervisor of the matter.

Only supported in the UK.

Example:

"c85d28cb-a760-4627-aa59-0a853c2e65ed"

clientCode

string | null

Associates an external client code to this matter.

Only supported in AU and UK.

Example:

"Client A"

branchId

string | null

Unique identifier of the associated branch.

Example:

"c85d28cb-a760-4627-aa59-0a853c2e65ed"

branchProviderId

string | null

Unique identifier of the associated branch provider.

Example:

"c85d28cb-a760-4627-aa59-0a853c2e65ed"

clientRole

string | null

'Client' matter type representative option for the matter.

Required and only supported when converting a 'Lead' to 'Matter'.

Example:

"Buyer"

isLead

boolean

Optional boolean flag indicating if matter is a 'Lead'.

This must be set to 'false' when converting a 'Lead' to 'Matter'.

Example:

false

clientIds

string[] | null

List of unique identifiers of 'Client' contacts associated with the matter.

otherSideIds

string[] | null

List of unique identifiers of 'OtherSide' contacts associated with the matter.

items

object

Items associated with the matter.

Show child attributes

Response

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

string | null

href

string | null

relation

string | null

method

string | null

default:GET

Delete a matter Get matter tags

⌘I

Documentation Index

Authorizations

Path Parameters

Body

Response