The Matters API from Smokeball — 6 operation(s) for matters.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/smokeball-matters-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
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.
This 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.
Possible 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.
A 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. \n \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.\n \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`.
This 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.\n \nNote: This endpoint can also be used to create a `Lead`.\n\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.\n\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.\n \nThe following actions are currently not supported:\n \n- `clientIds` cannot be modified\n \n- `otherSideIds` cannot be modified\n\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.\n \nNote: This endpoint can also be used to update a `Lead`, convert `Lead` to `Matter` and change the `Lead`/`Matter` type.\n \nSee `Matters` documentation for more details on how to use this.\n\nThe following actions are not supported:\n\n- `items` cannot be updated where either `clientIds` and/or `otherSideIds` are being updated\n \n- `items` cannot be updated when converting a `Lead` to `Matter` or changing the `Lead`/`Matter` type\n \n- `clientRole` cannot be updated, unless converting a `Lead` to `Matter` or changing the `Lead`/`Matter` type\n \n- `Matter` cannot be converted back to `Lead`\n \n- `splitOriginatingStaffSettings` cannot be updated without also providing `originatingStaffIds` in the same PATCH request\n \n- `personAssistingStaffIds` cannot contain `personAssistingStaffId`\n \n- `originatingStaffIds` cannot contain `originatingStaffId`\n \n- If split originating staff settings are enabled, `originatingStaffIds` and `originatingStaffId` cannot be updated\n \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:
ArchiveDto:
required:
- isArchived
type: object
properties:
archivedDate:
type: string
description: Date the matter was archived.
format: date-time
example: '2022-04-23T14:00:00Z'
archiveBoxNumber:
type:
- string
- 'null'
description: Archive box number.
example: '24'
archiveComments:
type:
- string
- 'null'
description: Archive comments.
example: Lot 1
archivedLocation:
type:
- string
- 'null'
description: Archived location.
example: Box
destroyDate:
type: string
description: Date the files of the matter were destroyed.
format: date-time
example: '2022-04-29T14:00:00Z'
isArchived:
type: boolean
description: Flag indicating if the matter is archived.
example: true
additionalProperties: false
MatterTagDto:
type: object
properties:
id:
type:
- string
- 'null'
description: 'Unique identifier for the tag.
When the tag Type is Staff, this value represents the staff member''s ID.
When GET tags, this value represents the tag''s unique identifier after creation.
Not required when posting standard custom tags.'
name:
type:
- string
- 'null'
description: 'Human-readable display name of the tag.
API would know you are adding the same tag to multiple matters as long as they have the same Name.
You can put any string you like and you can re-use strings as they are stored and re-used per account.
Theoretically an Id would be the same across matters for a custom tag.'
color:
type:
- string
- 'null'
description: 'Visual color associated with the tag.
Must be one of the supported color values (the valid list is documented separately).
If not provided, the color will default to Brown.
If the tag already exists, this field will be ignored and the existing color will be retained.'
type:
type: string
description: 'Defines what kind of tag this is.
Accepted values:
Staff – The tag represents a firm staff member.
Custom – The tag is a user-defined custom label.'
example: Staff
additionalProperties: false
SplitMatterStaffSettingsDto:
type: object
properties:
isEnabled:
type: boolean
description: Indicates whether the split matter staff settings are enabled or not.
splitMatterStaffs:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/SplitMatterStaffDto'
description: List of staff members involved in the split matter settings.
splitMethod:
type:
- string
- 'null'
description: 'Method used to split the matter staff.
Possible values: Unknown, SplitEvenly, UseRatio.'
remainderStaffId:
type:
- string
- 'null'
description: The unique identifier for the staff member who will handle the remainder of the matter after the split.
additionalProperties: false
SplitMatterStaffDto:
type: object
properties:
matterStaffId:
type:
- string
- 'null'
description: The unique identifier for the split matter staff.
matterStaffRatio:
type: integer
description: The split ratio for the matter staff.
format: int64
additionalProperties: false
MatterTagCollection:
type: object
properties:
id:
type:
- string
- 'null'
href:
type:
- string
- 'null'
relation:
type:
- string
- 'null'
method:
type:
- string
- 'null'
default: GET
self:
allOf:
- $ref: '#/components/schemas/Link'
value:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/MatterTag'
additionalProperties: false
MatterTag:
type: object
properties:
href:
type:
- string
- 'null'
relation:
type:
- string
- 'null'
method:
type:
- string
- 'null'
default: GET
self:
allOf:
- $ref: '#/components/schemas/Link'
id:
type:
- string
- 'null'
description: Unique identifier of the tag.
example: a15086f5-4da7-4271-8fea-b24d479ced2b
type:
type: string
description: Tag type.
example: Staff
name:
type:
- string
- 'null'
description: Name of the tag.
example: ''
color:
type:
- string
- 'null'
description: 'Color associated with the tag.
Defaults to ''Brown'' if not specified.'
example: Light Blue
staff:
allOf:
- $ref: '#/components/schemas/Link'
description: 'Link to staff.
Available when `P:MatterManagement.Api.Shared.Resources.MatterTag.Type` is `F:MatterManagement.Api.Shared.Resources.MatterTagType.Staff`.'
additionalProperties: false
IMatterItem:
type: object
properties:
type:
type:
- string
- 'null'
description: Type of the matter item.
readOnly: true
example: role or layout
id:
type:
- string
- 'null'
description: Unique identifier of the matter item.
example: 009f778f-83df-454a-b344-768a862a7e55
name:
type:
- string
- 'null'
description: Name of the matter item as it appears on the matter.
example: Vendor
subItems:
type:
- object
- 'null'
additionalProperties:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/IMatterItem'
description: Subitems associated to the matter item. These items vary depending on the matter.
additionalProperties: false
MatterItemDto:
type: object
properties:
id:
type:
- string
- 'null'
description: Unique identifier of the matter item.
example: 009f778f-83df-454a-b344-768a862a7e55
contactId:
type:
- string
- 'null'
description: 'Unique identifier of the associated contact.
Only applicable for ''role'' matter items.'
example: c85d28cb-a760-4627-aa59-0a853c2e65ed
contact:
allOf:
- $ref: '#/components/schemas/MatterItemContactDto'
description: 'Associated contact.
Only applicable for ''role'' matter items.'
roleDescription:
type:
- string
- 'null'
description: "Displayed name for the matter item.\n \nOnly applicable for 'role' matter items."
description:
type:
- string
- 'null'
description: "Description for the matter item.\n \nOnly applicable for 'role' matter items."
subItems:
type:
- object
- 'null'
additionalProperties:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/MatterItemDto'
description: 'SubItems associated with the matter item.
Not applicable for matter sub items.'
additionalProperties: false
ProblemDetails:
type: object
properties:
type:
type:
- string
- 'null'
title:
type:
- string
- 'null'
status:
type:
- integer
- 'null'
format: int32
detail:
type:
- string
- 'null'
instance:
type:
- string
- 'null'
additionalProperties: {}
SplitMatterStaff:
type: object
properties:
matterStaffId:
type:
- string
- 'null'
description: The unique identifier for the split matter staff.
matterStaffRatio:
type: integer
description: The split ratio for the matter staff.
format: int64
additionalProperties: false
MatterDto2:
type: object
properties:
externalSystemId:
type:
- string
- 'null'
description: External system id for the matter.
example: EXT01
number:
t
# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/smokeball/refs/heads/main/openapi/smokeball-matters-api-openapi.yml