The Firm API from Smokeball — 3 operation(s) for firm.
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-firm-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 Firm 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: Firm
paths:
/firm:
get:
tags:
- Firm
summary: Get firm
description: Retrieves the details of the firm associated with the authenticated client.
operationId: GetFirm
responses:
'200':
description: When request is successful. Returns a 'Firm' object.
content:
application/json:
schema:
$ref: '#/components/schemas/Firm'
'404':
description: When firm does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
put:
tags:
- Firm
summary: Update firm
description: Updates firm details for the current authenticated client.
operationId: UpdateFirm
requestBody:
content:
application/json-patch+json:
schema:
allOf:
- $ref: '#/components/schemas/UpdateFirmDto'
application/json:
schema:
allOf:
- $ref: '#/components/schemas/UpdateFirmDto'
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/UpdateFirmDto'
responses:
'202':
description: When request is accepted. Returns a hypermedia 'Link' object of the firm to be updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Link'
'404':
description: When firm does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
post:
tags:
- Firm
summary: Create firm
description: Creates a firm for the current authenticated client and registers an existing user as a staff member and firm owner.
operationId: CreateFirm
requestBody:
content:
application/json-patch+json:
schema:
allOf:
- $ref: '#/components/schemas/CreateFirmDto'
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CreateFirmDto'
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/CreateFirmDto'
responses:
'202':
description: When request is accepted. Returns a hypermedia 'Link' object of the firm to be created.
content:
application/json:
schema:
$ref: '#/components/schemas/Link'
'400':
description: When staff user does not exist or is already associated with another firm.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'403':
description: When an unsupported request is made.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/firmusers:
get:
tags:
- Firm
summary: Get firm user mappings
description: Retrieves a list of user mappings in the firm associated with the authenticated client.
responses:
'200':
description: When request is successful. Returns an array of one or more 'FirmUser' objects.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FirmUser'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
operationId: getFirmusers
x-operation-id-source: derived
/firmusers/{id}:
get:
tags:
- Firm
summary: Get firm user mapping
description: Retrieves a user mapping (based on staff or user id parameter provided) in the firm associated with the authenticated client.
operationId: GetFirmUserByIdAsync
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: When request is successful. Returns a 'FirmUser' object.
content:
application/json:
schema:
$ref: '#/components/schemas/FirmUser'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
put:
tags:
- Firm
summary: Update firm user mapping
description: Updates a user mapping in the firm associated with the authenticated client.
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json-patch+json:
schema:
allOf:
- $ref: '#/components/schemas/FirmUserDto'
description: Represents a mapping between a user and a staff member in a firm.
application/json:
schema:
allOf:
- $ref: '#/components/schemas/FirmUserDto'
description: Represents a mapping between a user and a staff member in a firm.
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/FirmUserDto'
description: Represents a mapping between a user and a staff member in a firm.
responses:
'202':
description: When request is accepted. Returns a hypermedia 'Link' object of the user to be updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Link'
'400':
description: When staff or user has not been provided.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'403':
description: When staff does not belong to the firm.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When 'FirmUser' does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
operationId: putFirmusersById
x-operation-id-source: derived
delete:
tags:
- Firm
summary: Delete firm user mapping
description: 'Removes the user from the firm associated with the authenticated client.
The staff member is set as a former staff member and a former user. User access is also disabled.'
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Link'
'202':
description: When request is accepted. Returns a hypermedia 'Link' object of the user to be deleted.
'404':
description: When 'FirmUser' object does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
operationId: deleteFirmusersById
x-operation-id-source: derived
components:
schemas:
Link:
type: object
properties:
id:
type:
- string
- 'null'
href:
type:
- string
- 'null'
relation:
type:
- string
- 'null'
method:
type:
- string
- 'null'
default: GET
additionalProperties: false
FirmAccountStatus:
enum:
- Active
- Warning
- Suspended
type: string
FirmAddressDto:
type: object
properties:
buildingLevel:
type:
- string
- 'null'
description: Building level in address (if applicable).
example: Level 1
unitNumber:
type:
- string
- 'null'
description: Unit number in address (if applicable).
example: '10'
unitType:
type:
- string
- 'null'
description: Unit type (e.g. Unit,Flat,Villa,Suite,etc.) in address (if applicable).
example: Suite
streetNumber:
type:
- string
- 'null'
description: Street number in address.
example: '100'
streetName:
type:
- string
- 'null'
description: Street name in address.
example: Broad
streetType:
type:
- string
- 'null'
description: Street type (e.g. Street,Road,Avenue,Lane,etc.) in address.
example: Street
addressLine1:
type:
- string
- 'null'
description: First line of address.
example: Level 1/10
addressLine2:
type:
- string
- 'null'
description: Second line of address (if applicable).
example: 100 Broad Street
city:
type:
- string
- 'null'
description: City, district, suburb, town, or village.
example: Chicago
state:
type:
- string
- 'null'
description: State, province, or region (if applicable).
example: IL
zipCode:
type:
- string
- 'null'
description: Zip or post code.
example: '60606'
county:
type:
- string
- 'null'
description: County (if applicable).
example: ''
locality:
type:
- string
- 'null'
description: Locality (if applicable).
example: ''
country:
type:
- string
- 'null'
description: Country.
example: United States
careOf:
type:
- string
- 'null'
description: Care of the addressee (if applicable).
example: ''
poBoxType:
type:
- string
- 'null'
description: PO box type in address (if applicable).
example: ''
poBoxNumber:
type:
- string
- 'null'
description: PO box Number in address (if applicable).
example: ''
additionalProperties: false
FirmSubscriptionDto:
type: object
properties:
productSuite:
type:
- string
- 'null'
description: 'Optional product suite to use when creating the firm.
Use ''SMOKEBALL'' to use the new product suite.'
promotionId:
type:
- string
- 'null'
description: Optional promotion ID that will be used when the firm is subscribed.
interval:
type:
- string
- 'null'
description: 'Optional interval to register the account subscription with.
Possible values: Monthly, Yearly'
additionalProperties: false
description: The subscription details for the firm.
FirmDxAddressDto:
type: object
properties:
number:
type:
- string
- 'null'
description: Direct Exchange number (if applicable).
example: '376'
exchange:
type:
- string
- 'null'
description: Direct Exchange name.
example: DX
state:
type:
- string
- 'null'
description: State, province, or region.
example: NSW
additionalProperties: false
FirmUserDto:
type: object
properties:
userId:
type:
- string
- 'null'
description: Unique identifier of the associated user.
example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
staffId:
type:
- string
- 'null'
description: Unique identifier of the associated staff member..
example: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
additionalProperties: false
description: Represents a mapping between a user and a staff member in a firm.
FirmStatus:
type: object
properties:
status:
allOf:
- $ref: '#/components/schemas/FirmAccountStatus'
description: The status of the firm.
example: Active
statusMessage:
type:
- string
- 'null'
description: The status message of the firm.
additionalProperties: false
description: The status of the firm.
Firm:
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 firm.
example: f4ff1eff-b7fe-4d46-4e46-01d985838d76
versionId:
type:
- string
- 'null'
description: Version id of the record.
example: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
owner:
type:
- string
- 'null'
description: 'The owner/white-label partner used by the firm.
Possible values: Smokeball, PracticeEvolve, TriConvey.'
example: Smokeball
name:
type:
- string
- 'null'
description: The name of the firm.
example: Brown LLC
status:
allOf:
- $ref: '#/components/schemas/FirmStatus'
description: The status of the firm.
productId:
type:
- string
- 'null'
description: 'The product/tier the firm is subscribed to. Must be set when creating the firm and is optional when updating the firm.
The supported products are listed in order below, the identifier (in brackets) must be used.
* Bill (SMK001)
* Boost (SMK004)
* Grow (SMK002)
* Prosper + (SMK003)
Possible values: SMK001, SMK004, SMK002, SMK003'
example: SMK001
addOnIds:
type:
- array
- 'null'
items:
type: string
description: 'The optional add-ons the firm is subscribed to. Must be specified with an accompanying productId.
The supported add-ons are listed below, the identifier (listed in brackets) must be used.
* Intake (ADD001)
* AutoTime (ADD003)
* FamilyPro (ADD004)
* Api (ADD005)
* Workflows (ADD006)
* PowerBI (ADD007)
* Archie (ADD008)
* SSO (ADD010)
* PracticeEvolve (ADD011)
* CustomReporting (ADD012)
Possible values: ADD001, ADD003, ADD004, ADD005, ADD006, ADD007, ADD008, ADD010, ADD011, ADD012'
example:
- ADD001
- ADD003
email:
type:
- string
- 'null'
description: 'The email of the firm.
Only supported in AUS.'
example: john.smith@law.com
abn:
type:
- string
- 'null'
description: 'For AU: Australian Business Number (ABN) of the firm.
For UK: Value-added Tax Number (VAT) of the firm.
Only supported in AU and UK.'
example: '1234567890'
acn:
type:
- string
- 'null'
description: 'For AU: Australian Company Number (ACN) of the firm.
For UK: Company Registration Number (CRN) of the firm.
Only supported in AU and UK.'
example: '1234567890'
streetAddress:
allOf:
- $ref: '#/components/schemas/FirmAddress'
description: Street address of the firm.
mailingAddress:
allOf:
- $ref: '#/components/schemas/FirmAddress'
description: Mailing address of the firm.
dxAddress:
allOf:
- $ref: '#/components/schemas/DxAddress'
description: 'DX address of the firm.
Only supported in AUS.'
phone:
allOf:
- $ref: '#/components/schemas/PhoneNumber'
description: Phone number of the firm.
fax:
allOf:
- $ref: '#/components/schemas/PhoneNumber'
description: Fax number of the firm.
logo:
type:
- string
- 'null'
description: Logo of the firm.
example: https://example-logo-url.com/image
stylingDetails:
allOf:
- $ref: '#/components/schemas/StylingDetails'
description: Styling details of the firm.
licenceNumbers:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/LicenceNumber'
description: Licence numbers of the firm.
createdDate:
type:
- string
- 'null'
description: The date when the firm was created in UTC.
format: date-time
example: '2024-01-15T10:30:00Z'
additionalProperties: false
PhoneNumber:
type: object
properties:
areaCode:
type:
- string
- 'null'
description: Phone area code.
example: '555'
number:
type:
- string
- 'null'
description: Phone number (excluding area code).
example: '1234567'
additionalProperties: false
StylingDetails:
type: object
properties:
primaryColorHexCode:
type:
- string
- 'null'
description: Firm's primary color hex code.
example: '#FF000000'
secondaryColorHexCode:
type:
- string
- 'null'
description: Firm's secondary color hex code.
example: '#FF000000'
fontFamilyName:
type:
- string
- 'null'
description: Firm's font family name.
example: Open Sans
additionalProperties: false
FirmAddress:
type: object
properties:
buildingLevel:
type:
- string
- 'null'
description: Building level in address (if applicable).
example: Level 1
unitNumber:
type:
- string
- 'null'
description: Unit number in address (if applicable).
example: '10'
unitType:
type:
- string
- 'null'
description: Unit type (e.g. Unit,Flat,Villa,Suite,etc.) in address (if applicable).
example: Suite
streetNumber:
type:
- string
- 'null'
description: Street number in address.
example: '100'
streetName:
type:
- string
- 'null'
description: Street name in address.
example: Broad
streetType:
type:
- string
- 'null'
description: Street type (e.g. Street,Road,Avenue,Lane,etc.) in address.
example: Street
addressLine1:
type:
- string
- 'null'
description: First line of address.
example: Level 1/10
addressLine2:
type:
- string
- 'null'
description: Second line of address (if applicable).
example: 100 Broad Street
city:
type:
- string
- 'null'
description: City, district, suburb, town, or village.
example: Chicago
state:
type:
- string
- 'null'
description: State, province, or region.
example: IL
zipCode:
type:
- string
- 'null'
description: Zip or post code.
example: '60606'
county:
type:
- string
- 'null'
description: County (if applicable)
example: Berkshire
locality:
type:
- string
- 'null'
description: Locality (if applicable)
example: Windsor
country:
type:
- string
- 'null'
description: Country.
example: United States
careOf:
type:
- string
- 'null'
description: Care of the addressee (if applicable).
readOnly: true
example: ''
poBoxType:
type:
- string
- 'null'
description: PO box type in address (if applicable).
readOnly: true
example: ''
poBoxNumber:
type:
- string
- 'null'
description: PO box Number in address (if applicable).
readOnly: true
example: ''
additionalProperties: false
PhoneNumberDto:
type: object
properties:
areaCode:
type:
- string
- 'null'
description: Phone area code.
example: '555'
number:
type:
- string
- 'null'
description: Phone number (excluding area code).
example: '1234567'
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: {}
LicenceNumber:
type: object
properties:
state:
type:
- string
- 'null'
description: State associated to the licence.
example: IL
type:
type:
- string
- 'null'
description: Type of the licence.
example: ''
number:
type:
- string
- 'null'
description: Licence number.
additionalProperties: false
UpdateFirmDto:
type: object
properties:
productId:
type:
- string
- 'null'
description: 'The product/tier the firm is subscribed to. Must be set when creating the firm and is optional when updating the firm.
The supported products are listed in order below, the identifier (in brackets) must be used.
* Bill (SMK001)
* Boost (SMK004)
* Grow (SMK002)
* Prosper + (SMK003)
Possible values: SMK001, SMK004, SMK002, SMK003'
example: SMK001
addOnIds:
uniqueItems: true
type:
- array
- 'null'
items:
type: string
description: 'The optional add-ons the firm is subscribed to. Must be specified with an accompanying productId.
The supported add-ons are listed below, the identifier (listed in brackets) must be used.
* Intake (ADD001)
* AutoTime (ADD003)
* FamilyPro (ADD004)
* Api (ADD005)
* Workflows (ADD006)
* PowerBI (ADD007)
* Archie (ADD008)
* SSO (ADD010)
Possible values: ADD01, ADD003, ADD004, ADD005, ADD006, ADD007, ADD008, ADD010'
example:
- ADD01
- ADD003
name:
type:
- string
- 'null'
description: The name of the firm.
example: Brown LLC
email:
type:
- string
- 'null'
description: 'The email of the firm.
Only supported in AU.'
example: john.smith@law.com
abn:
type:
- string
- 'null'
description: 'Represents a different field depending on the region.
* For AU: Australian Business Number (ABN) of the firm.
* For UK: Value-added Tax Number (VAT) of the firm.
Only supported in AU and UK.'
example: '1234567890'
acn:
type:
- string
- 'null'
description: 'Represents a different field depending on the region.
* For AU: Australian Company Number (ACN) of the firm.
* For UK: Company Registration Number (CRN) of the firm.
Only supported in AU and UK.'
example: '1234567890'
streetAddress:
allOf:
- $ref: '#/components/schemas/FirmAddressDto'
description: Street address of the firm.
mailingAddress:
allOf:
- $ref: '#/components/schemas/FirmAddressDto'
description: Mailing address of the firm.
dxAddress:
allOf:
- $ref: '#/components/schemas/FirmDxAddressDto'
description: 'DX address of the firm.
Only supported in AU.'
phone:
allOf:
- $ref: '#/components/schemas/PhoneNumberDto'
description: Phone number of the firm.
fax:
allOf:
- $ref: '#/components/schemas/PhoneNumberDto'
description: Fax number of the firm.
status:
allOf:
- $ref: '#/components/schemas/FirmStatusDto'
description: The status of the firm.
additionalProperties: false
FirmStatusDto:
type: object
properties:
status:
allOf:
- $ref: '#/components/schemas/FirmAccountStatus'
description: The status of the firm account.
example: Active
statusMessage:
type:
- string
- 'null'
description: The status message of the firm. If left blank, an appropriate message is set depending on the status.
additionalProperties: false
description: The status of the firm.
DxAddress:
type: object
properties:
number:
type:
- string
- 'null'
description: Direct Exchange number (if applicable).
example: '376'
exchange:
type:
- string
- 'null'
description: Direct Exchange name.
example: DX
state:
type:
- string
- 'null'
description: State, province, or region.
example: NSW
additionalProperties: false
CreateFirmDto:
type: object
properties:
productId:
type:
- string
- 'null'
description: 'The product/tier the firm is subscribed to. Must be set when creating the firm and is optional when updating the firm.
The supported products are listed in order below, the identifier (in brackets) must be used.
* Bill (SMK001)
* Boost (SMK004)
* Grow (SMK002)
* Prosper + (SMK003)
Possible values: SMK001, SMK004, SMK002, SMK003'
example: SMK001
addOnIds:
uniqueItems: true
type:
- array
- 'null'
items:
type: string
description: 'The optional add-ons the firm is subscribed to. Must be specified with an accompanying productId.
The supported add-ons are listed below, the identifier (listed in brackets) must be used.
* Intake (ADD001)
* AutoTime (ADD003)
* FamilyPro (ADD004)
* Api (ADD005)
* Workflows (ADD006)
* PowerBI (ADD007)
* Archie (ADD008)
* SSO (ADD010)
Possible values: ADD01, ADD003, ADD004, ADD005, ADD006, ADD007, ADD008, ADD010'
example:
- ADD01
- ADD003
name:
type:
- string
- 'null'
description: The name of the firm.
example: Brown LLC
email:
type:
- string
- 'null'
description: 'The email of the firm.
Only supported in AU.'
example: john.smith@law.com
abn:
type:
- string
- 'null'
description: 'Represents a different field depending on the region.
* For AU: Australian Business Number (ABN) of the firm.
* For UK: Value-added Tax Number (VAT) of the firm.
Only supported in AU and UK.'
example: '1234567890'
acn:
type:
- string
- 'null'
description: 'Represents a different field depending on the region.
* For AU: Australian Company Number (ACN) of the firm.
* For UK: Company Registration Number (CRN) of the firm.
Only supported in AU and UK.'
example: '1234567890'
streetAddress:
allOf:
- $ref: '#/components/schemas/FirmAddressDto'
description: Street address of the firm.
mailingAddress:
allOf:
- $ref: '#/components/schemas/FirmAddressDto'
description: Mailing address of the firm.
dxAddress:
allOf:
- $ref: '#/components/schemas/FirmDxAddressDto'
description: 'DX address of the firm.
Only supported in AU.'
phone:
allOf:
- $ref: '#/components/schemas/PhoneNumberDto'
description: Phone number of the firm.
fax:
allOf:
- $ref: '#/components/schemas/PhoneNumberDto'
description: Fax number of the firm.
isInternal:
type: boolean
description: Whether firm is being created for internal use. Internal firms will not be subscribed for payment processing and will not be charged.
example: false
staff:
allOf:
- $ref: '#/components/schemas/StaffDto'
description: The staff member that will be created with the firm. This staff member will become the firm owner.
subscription:
allOf:
- $ref: '#/components/schemas/FirmSubscriptionDto'
description: Optional subscription details that will be used when creating the firm.
additionalProperties: false
FirmUser:
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'
staffId:
type:
- string
- 'null'
description: Unique identifier of the staff member.
example: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
userId:
type:
- st
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/smokeball/refs/heads/main/openapi/smokeball-firm-api-openapi.yml