The Matters API from Smokeball — 6 operation(s) for matters.
openapi: 3.0.1
info:
title: Smokeball Activity Codes Matters API
version: '1.0'
description: REST API for integrating with Smokeball legal practice management software. Supports matters, contacts, documents, time entries, billing, trust accounting, staff, webhooks, and law firm workflows across US, AU, and UK regions. Uses OAuth 2.0 (client credentials) authentication.
contact:
name: Smokeball Developer Support
url: https://docs.smokeball.com/docs/api-docs/1e13a13124aee-introduction
x-api-id: smokeball
x-audience: external-public
servers:
- url: https://api.smokeball.com
- url: https://api.smokeball.com.au
- url: https://api.smokeball.co.uk
- url: https://stagingapi.smokeball.com
- url: https://stagingapi.smokeball.com.au
- url: https://stagingapi.smokeball.co.uk
security:
- api-key: []
token: []
tags:
- name: Matters
paths:
/matters/{matterId}/archive:
get:
tags:
- Matters
summary: Get the archive for a matter
description: Retrieves an archive for a matter.
operationId: GetArchiveForMatter
parameters:
- name: matterId
in: path
required: true
schema:
type: string
responses:
'200':
description: When request is successful. Returns an 'Archive' object.
content:
application/json:
schema:
$ref: '#/components/schemas/Archive'
'404':
description: When the specified matter's archive does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
put:
tags:
- Matters
summary: Update an archive for a matter.
description: Updates a specified matter's archive
operationId: UpdateArchive
parameters:
- name: matterId
in: path
required: true
schema:
type: string
requestBody:
content:
application/json-patch+json:
schema:
allOf:
- $ref: '#/components/schemas/ArchiveDto'
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ArchiveDto'
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/ArchiveDto'
responses:
'202':
description: When request is accepted. Returns a 'Link' object.
content:
application/json:
schema:
$ref: '#/components/schemas/Link'
'400':
description: When an unsupported request is made.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
patch:
tags:
- Matters
summary: Patch an archive for a matter
description: Updates a specified matter's archive with patch operations.
operationId: PatchArchive
parameters:
- name: matterId
in: path
required: true
schema:
type: string
requestBody:
content:
application/json-patch+json:
schema:
$ref: '#/components/schemas/ArchiveDto'
application/json:
schema:
$ref: '#/components/schemas/ArchiveDto'
application/*+json:
schema:
$ref: '#/components/schemas/ArchiveDto'
responses:
'202':
description: When request is accepted. Returns a 'Link' object.
content:
application/json:
schema:
$ref: '#/components/schemas/Link'
'400':
description: When an unsupported request is made.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/matters/{matterId}/billingconfiguration:
get:
tags:
- Matters
summary: Get matter billing configuration
description: Retrieves the billing configuration for the specified matter.
operationId: GetBillingConfiguration
parameters:
- name: matterId
in: path
required: true
schema:
type: string
responses:
'200':
description: When request is successful. Returns a 'BillingConfiguration' object.
content:
application/json:
schema:
$ref: '#/components/schemas/BillingConfiguration'
'400':
description: When an unsupported request is made.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'403':
description: When the matter is not associated with the authenticated client.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When the specified matter does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
put:
tags:
- Matters
summary: Update matter billing configuration
description: Updates the billing configuration for the specified matter.
operationId: UpdateBillingConfigurationAsync
parameters:
- name: matterId
in: path
required: true
schema:
type: string
requestBody:
content:
application/json-patch+json:
schema:
allOf:
- $ref: '#/components/schemas/BillingConfigurationDto'
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BillingConfigurationDto'
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/BillingConfigurationDto'
responses:
'202':
description: When request is accepted. Returns a hypermedia 'Link' object of the billing configuration to be updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Link'
'400':
description: When an unsupported request is made.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'403':
description: When matter with specified id is not associated with authenticated client.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When the specified matter does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/matters:
get:
tags:
- Matters
summary: Get matters
description: Returns a list of matters. To return leads, set the `isLead` search option to true.
operationId: GetMatters
parameters:
- name: Offset
in: query
schema:
maximum: 2147483647
minimum: 0
type: integer
format: int32
- name: Limit
in: query
schema:
maximum: 500
minimum: 1
type: integer
format: int32
- name: Search
in: query
description: "Filter matters by specified search term.\r\nThis field is wide reaching, it is used to search by clients, othersides, description and matter numbers."
schema:
type: string
example: Bob
example: Bob
- name: MatterTypeId
in: query
description: Filter by matter type identifier.
schema:
type: string
example: 009f778f-83df-454a-b344-768a862a7e55
example: 009f778f-83df-454a-b344-768a862a7e55
- name: ContactId
in: query
description: Filter by the contact identifier.
schema:
type: string
example: 7fdbdd5b-0f5e-4095-af9e-ae5b055325c7
example: 7fdbdd5b-0f5e-4095-af9e-ae5b055325c7
- name: Status
in: query
description: "Filter by current status of the matter.\r\n\r\nPossible values: Open, Pending, Closed, Deleted or Cancelled."
schema:
type: array
items:
type: string
- name: IsLead
in: query
description: "Boolean flag to return 'Leads'. This is false by default.\r\n\r\nA Lead is a potential matter that has not yet been converted to a full matter. The data structure of a lead is similar to a matter, but with some small variances."
schema:
type: boolean
example: true
deprecated: true
example: true
- name: Type
in: query
description: "Type of matter to search for. This is set to Matters by default. \r\n \r\nA Lead is a potential matter that has not yet been converted to a full matter. The data structure of a lead is similar to a matter, but with some small variances.\r\n \r\nPossible values: \"Matters\", \"Leads\", \"Matters,Leads\"."
schema:
type: string
example: Leads
example: Leads
- name: UpdatedSince
in: query
description: "Filter by matters updated since a specified time (.net ticks representation of the UTC datetime). Cannot be used in conjunction with `LastUpdated`.\r\n\r\nThis field will not be supported in future, please use LastUpdated instead."
schema:
type: integer
format: int64
example: 637873555398585000
example: 637873555398585000
- name: LastUpdated
in: query
description: Filter by last updated date of matter. Cannot be used in conjunction with `UpdatedSince`.
schema:
type: string
format: date-time
example: '2022-04-23T14:00:00Z'
example: '2022-04-23T14:00:00Z'
- name: Sort
in: query
description: ' Available fields: status, lastUpdated'
schema:
type: string
- name: Fields
in: query
description: ' Available fields: items, tags'
schema:
type: string
responses:
'200':
description: When request is successful. Returns a paged collection of 'Matter' objects.
content:
application/json:
schema:
$ref: '#/components/schemas/MatterPagedCollection'
post:
tags:
- Matters
summary: Create a matter
description: "Creates a new matter.\r\n \r\nNote: This endpoint can also be used to create a `Lead`.\r\n\r\nWhen 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.\r\n\r\nThe `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."
operationId: CreateMatter
requestBody:
content:
application/json-patch+json:
schema:
allOf:
- $ref: '#/components/schemas/MatterDto'
application/json:
schema:
allOf:
- $ref: '#/components/schemas/MatterDto'
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/MatterDto'
responses:
'202':
description: When request is accepted. Returns a hypermedia 'Link' object of the matter to be created.
content:
application/json:
schema:
$ref: '#/components/schemas/Link'
'400':
description: When an unsupported request is made or a mandatory field - i.e. client, matter type, status - is not provided.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/matters/{matterId}:
get:
tags:
- Matters
summary: Get a matter
description: Retrieves a specified matter.
operationId: GetMatterById
parameters:
- name: matterId
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: When request is successful. Returns a 'Matter' object.
content:
application/json:
schema:
$ref: '#/components/schemas/Matter'
'403':
description: When the authenticated account does not have access to the matter.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When matter with specified id does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
put:
tags:
- Matters
summary: Update a matter
description: "Updates a specified matter.\r\n \r\nThe following actions are currently not supported:\r\n \r\n- `clientIds` cannot be modified\r\n \r\n- `otherSideIds` cannot be modified\r\n\r\n- `Matter` cannot be converted back to `Lead`"
operationId: UpdateMatter
parameters:
- name: matterId
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json-patch+json:
schema:
allOf:
- $ref: '#/components/schemas/MatterDto'
application/json:
schema:
allOf:
- $ref: '#/components/schemas/MatterDto'
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/MatterDto'
responses:
'202':
description: When request is accepted. Returns a hypermedia 'Link' object of the matter to be updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Link'
'400':
description: When an unsupported request is made.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'403':
description: When the authenticated account does not have access to the matter.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When matter with specified id does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
patch:
tags:
- Matters
summary: Patch a matter
description: "Patches a specified matter.\r\n \r\nNote: This endpoint can also be used to update a `Lead`, convert `Lead` to `Matter` and change the `Lead`/`Matter` type.\r\n \r\nSee `Matters` documentation for more details on how to use this.\r\n\r\nThe following actions are not supported:\r\n\r\n- `items` cannot be updated where either `clientIds` and/or `otherSideIds` are being updated\r\n \r\n- `items` cannot be updated when converting a `Lead` to `Matter` or changing the `Lead`/`Matter` type\r\n \r\n- `clientRole` cannot be updated, unless converting a `Lead` to `Matter` or changing the `Lead`/`Matter` type\r\n \r\n- `Matter` cannot be converted back to `Lead`\r\n \r\n- `splitOriginatingStaffSettings` cannot be updated without also providing `originatingStaffIds` in the same PATCH request\r\n \r\n- `personAssistingStaffIds` cannot contain `personAssistingStaffId`\r\n \r\n- `originatingStaffIds` cannot contain `originatingStaffId`\r\n \r\n- If split originating staff settings are enabled, `originatingStaffIds` and `originatingStaffId` cannot be updated\r\n \r\n- 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"
operationId: PatchMatter
parameters:
- name: matterId
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json-patch+json:
schema:
$ref: '#/components/schemas/MatterDto2'
application/json:
schema:
$ref: '#/components/schemas/MatterDto2'
application/*+json:
schema:
$ref: '#/components/schemas/MatterDto2'
responses:
'202':
description: When request is accepted. Returns a hypermedia 'Link' object of the matter to be patched.
content:
application/json:
schema:
$ref: '#/components/schemas/Link'
'400':
description: When an unsupported request is made.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'403':
description: When the authenticated account does not have access to the matter.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When matter with specified id does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
delete:
tags:
- Matters
summary: Delete a matter
description: Deletes a specified matter.
operationId: DeleteMatter
parameters:
- name: matterId
in: path
required: true
schema:
type: string
format: uuid
responses:
'202':
description: When request is accepted. Returns a hypermedia 'Link' object of the matter to be deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/Link'
'400':
description: When an unsupported request is made.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'403':
description: When the authenticated account does not have access to the matter.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When matter with specified id does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/matters/{matterId}/tags:
get:
tags:
- Matters
summary: Get matter tags
operationId: GetMatterTagsByMatterId
parameters:
- name: matterId
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: When request is successful. Returns a collection of 'MatterTag' objects.
content:
application/json:
schema:
$ref: '#/components/schemas/MatterTagCollection'
'403':
description: When matter with specified id is not associated with authenticated client.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When matter with specified id does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
post:
tags:
- Matters
summary: Add tags to a matter
operationId: AddMatterTags
parameters:
- name: matterId
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json-patch+json:
schema:
type: array
items:
$ref: '#/components/schemas/MatterTagDto'
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/MatterTagDto'
application/*+json:
schema:
type: array
items:
$ref: '#/components/schemas/MatterTagDto'
responses:
'201':
description: When request is successful. Returns a 'Link' object.
content:
application/json:
schema:
$ref: '#/components/schemas/Link'
'400':
description: When an unsupported request is made.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When matter with specified id does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/matters/{matterId}/tags/{tagId}:
delete:
tags:
- Matters
summary: Remove tags from a matter
description: Removes the tag from the matter without deleting from the account.
operationId: DeleteMatterTag
parameters:
- name: matterId
in: path
required: true
schema:
type: string
format: uuid
- name: tagId
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json-patch+json:
schema:
type: array
items:
$ref: '#/components/schemas/MatterTagDto'
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/MatterTagDto'
application/*+json:
schema:
type: array
items:
$ref: '#/components/schemas/MatterTagDto'
responses:
'202':
description: When request is accepted. Returns a 'Link' object.
content:
application/json:
schema:
$ref: '#/components/schemas/Link'
'400':
description: When an unsupported request is made.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'403':
description: When matter with specified id is not associated with authenticated client.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When matter with specified id does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
components:
schemas:
BillingConfigurationDto:
type: object
properties:
billingType:
allOf:
- $ref: '#/components/schemas/BillingTypeEnum'
description: "The billing type.\r\n\r\nPossible values: \r\nNone = 0, \r\nFixed Fee = 1, \r\nFixed Fee per Appearance = 2, \r\nTime Based = 3, \r\nContingency Dollars = 4, \r\nContingency Percent = 5, \r\nNot Billable = 6,\r\nConditionalFeeAgreement = 7"
example: 1
amount:
type: number
description: "The amount (currency).\r\n\r\nOnly applicable when BillingType is 'Fixed Fee', 'Fixed Fee per Apperance', 'Contingency ($)' or 'Time Based'."
format: double
example: 142.31
contingencyAmount:
type: number
description: "The contingency amount (percentage). \r\n\r\nOnly applicable when BillingType is 'Contingency Percent'."
format: double
example: 32
disbursementAmount:
type: number
description: "The disbursement amount (currency).\r\n\r\nOnly applicable when BillingType is 'Fixed Fee', 'Fixed Fee per Apperance', 'Contingency ($)' or 'Time Based'.\r\n\r\nOnly supported in the UK."
format: double
example: 520.67
debtorIds:
type: array
items:
type: string
description: The matter debtors. Must be valid contact id(s) and a maximum of 3 debtors can be set.
nullable: true
isUtbmsEnabled:
type: boolean
description: "True if Uniform Task Based Management (UTBMS) is enabled for this matter.\r\n\r\nOnly supported in the US."
example: true
ledesFirmId:
type: string
description: "The associated Legal Electronic Data Exchange Standard (LEDES) firm.\r\n\r\nOnly supported in the US."
nullable: true
example: '100558'
ledesMatterId:
type: string
description: "The associated Legal Electronic Data Exchange Standard (LEDES) matter.\r\n\r\nOnly supported in the US."
nullable: true
example: '100558'
ledesClientMatterId:
type: string
description: "The associated Legal Electronic Data Exchange Standard (LEDES) client matter.\r\n\r\nOnly supported in the US."
nullable: true
example: '100558'
ledesTimekeeperClassificationType:
allOf:
- $ref: '#/components/schemas/TimekeeperClassificationType'
description: "The associated Legal Electronic Data Exchange Standard (LEDES) classification type.\r\n \r\nPossible values: Length6 = 0, Length2 = 1, UseFirmDefault = 2.\r\n \r\nOnly supported in the US."
example: 0
rateSetId:
type: string
description: "The RateSet Id.\r\n\r\nOnly supported in the UK."
nullable: true
example: '100558'
additionalProperties: false
TimekeeperClassificationType:
enum:
- 0
- 1
- 2
type: integer
description: "The associated Legal Electronic Data Exchange Standard (LEDES) classification type.\r\n \r\nPossible values: Length6 = 0, Length2 = 1, UseFirmDefault = 2.\r\n \r\nOnly supported in the US."
format: int32
IMatterItem:
type: object
properties:
type:
type: string
description: Type of the matter item.
nullable: true
readOnly: true
example: role or layout
id:
type: string
description: Unique identifier of the matter item.
nullable: true
example: 009f778f-83df-454a-b344-768a862a7e55
name:
type: string
description: Name of the matter item as it appears on the matter.
nullable: true
example: Vendor
subItems:
type: object
additionalProperties:
type: array
items:
$ref: '#/components/schemas/IMatterItem'
nullable: true
description: Subitems associated to the matter item. These items vary depending on the matter.
nullable: true
additionalProperties: false
SplitMatterStaffDto:
type: object
properties:
matterStaffId:
type: string
description: The unique identifier for the split matter staff.
nullable: true
matterStaffRatio:
type: integer
description: The split ratio for the matter staff.
format: int64
additionalProperties: false
Link:
type: object
properties:
id:
type: string
nullable: true
href:
type: string
nullable: true
relation:
type: string
nullable: true
method:
type: string
default: GET
nullable: true
additionalProperties: false
SplitMatterStaff:
type: object
properties:
matterStaffId:
type: string
description: The unique identifier for the split matter staff.
nullable: true
matterStaffRatio:
type: integer
description: The split ratio for the matter staff.
format: int64
additionalProperties: false
MatterDto2:
type: object
properties:
externalSystemId:
type: string
description: External system id for the matter.
nullable: true
example: EXT01
number:
type: string
description: Human-friendly number assigned to matter.
nullable: true
example: FUS-124
matterTypeId:
type: string
description: "Unique identifier of the matter type associated with the matter.\r\n \r\nMatter types define what information can be saved to the matter, relevant to that area of law and state / location.\r\n \r\nA pre-configured list of matter types can be obtained via the 'GET /mattertypes' API.\r\n \r\n'Lead' matter types are different from the standard matter types used when creating a 'Matter'.\r\n \r\nUse the 'Type' query parameter in the 'GET /mattertypes' API call to get 'Lead' specific matter types."
nullable: true
example: 009f778f-83df-454a-b344-768a862a7e55
description:
type: string
description: Brief description of the matter.
nullable: true
example: This is a brief description for the matter
status:
type: string
description: "Current status of matter.\r\n\r\nPossible values: Open, Pending, Closed, Deleted or Cancelled."
nullable: true
example: Open
dateOpened:
type: string
description: Date when the matter was opened. This can be backdated if required.
format: date-time
nullable: true
example: '2022-04-23T14:00:00Z'
openedDate:
type: string
description: Date the matter was opened. This can be backdated if required.
format: date-time
nullable: true
example: '2022-04-23T14:00:00Z'
closedDate:
type: string
description: Date the matter was closed. This can be backdated if required.
format: date-time
nullable: true
example: '2022-04-23T14:00:00Z'
leadOpenedDate:
type: string
description: "Date the lead was opened. This can be backdated if required.\r\n\r\nOnly applies if isLead is true."
format: date-time
nullable: true
example: '2022-04-23T14:00:00Z'
leadClosedDate:
type: string
description: "Date the lead was closed. This can be backdated if required.\r\n\r\nOnly applies if isLead is true."
format: date-time
nullable: true
example: '2022-04-23T14:00:00Z'
leadClosedReason:
type: string
description: "Reason the lead was closed.\r\n\r\nOnly applies if isLead is true."
nullable: true
example: No longer interested
referralType:
type: string
description: "Referral Type of the matter.\r\n\r\nPossible values are different per region."
nullable: true
example: Google
referrerId:
type: string
description: Contact id of the person that referred the matter.
nullable: true
example: 97bbe49f-6460-4bfc-b287-34ddfdbb81ef
referralAgreementFeeType:
type: string
description: "The referral agreement fee type.\r\n\r\nPossible values: %, Flat fee, Other"
nullable: true
referralAgreementFee:
type: number
description: The referral agreement fee value.
format: double
nullable: true
referralAgreementFeeComment:
type: string
description: The referral agreement fee comment.
nullable: true
personResponsibleStaffId:
type: string
description: Staff id of the person responsible for the matter (if applicable).
nu
# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/smokeball/refs/heads/main/openapi/smokeball-matters-api-openapi.yml