The Expenses API from Smokeball — 2 operation(s) for expenses.
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-expenses-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 Expenses 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: Expenses
paths:
/matters/{matterId}/expenses:
get:
tags:
- Expenses
summary: Get expenses
description: Returns a list of expenses for the specified matter.
operationId: GetExpenses
parameters:
- name: matterId
in: path
required: true
schema:
type: string
- 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: UpdatedSince
in: query
description: Returns expenses updated since a specified time (.net ticks representation of the UTC datetime).
schema:
type: integer
format: int64
responses:
'200':
description: When request is successful. Returns a paged collection of 'Expense' objects.
content:
application/json:
schema:
$ref: '#/components/schemas/ExpensePagedCollection'
'400':
description: When an unsupported request is made.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
post:
tags:
- Expenses
summary: Create an expense
description: Creates an expense for the specified matter.
operationId: CreateExpense
parameters:
- name: matterId
in: path
required: true
schema:
type: string
requestBody:
content:
application/json-patch+json:
schema:
allOf:
- $ref: '#/components/schemas/ExpenseDto'
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ExpenseDto'
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/ExpenseDto'
responses:
'202':
description: When request is accepted. Returns a hypermedia 'Link' object of the expense to be created.
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}/expenses/{id}:
get:
tags:
- Expenses
summary: Get an expense
description: Retrieves a specified expense.
operationId: GetExpenseById
parameters:
- name: id
in: path
required: true
schema:
type: string
- name: matterId
in: path
required: true
schema:
type: string
responses:
'200':
description: When request is successful. Returns an 'Expense' object.
content:
application/json:
schema:
$ref: '#/components/schemas/Expense'
'400':
description: When an unsupported request is made.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'403':
description: When expense with specified id is not associated with authenticated client.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When expense with specified id does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
put:
tags:
- Expenses
summary: Update an expense
description: Updates an expense for the specified matter.
operationId: UpdateExpense
parameters:
- name: matterId
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json-patch+json:
schema:
allOf:
- $ref: '#/components/schemas/ExpenseDto'
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ExpenseDto'
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/ExpenseDto'
responses:
'202':
description: When request is accepted. Returns a hypermedia 'Link' object of the expense 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 expense with specified id is not associated with authenticated client.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When expense with specified id does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
patch:
tags:
- Expenses
summary: Patch an expense
description: Patches an expense for the specified matter.
operationId: PatchExpense
parameters:
- name: matterId
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json-patch+json:
schema:
$ref: '#/components/schemas/ExpenseDto'
application/json:
schema:
$ref: '#/components/schemas/ExpenseDto'
application/*+json:
schema:
$ref: '#/components/schemas/ExpenseDto'
responses:
'202':
description: When request is accepted. Returns a hypermedia 'Link' object of the expense 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 expense with specified id is not associated with authenticated client.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When expense with specified id does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
delete:
tags:
- Expenses
summary: Delete an expense
description: Deletes an expense.
operationId: DeleteExpense
parameters:
- name: id
in: path
required: true
schema:
type: string
- name: matterId
in: path
required: true
schema:
type: string
responses:
'202':
description: When request is accepted. Returns a hypermedia 'Link' object of the expense 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 expense with specified id is not associated with authenticated client.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When expense with specified id does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
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
ExpensePagedCollection:
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/Expense'
offset:
type:
- integer
- 'null'
format: int32
limit:
type:
- integer
- 'null'
format: int32
size:
type: integer
format: int64
first:
allOf:
- $ref: '#/components/schemas/Link'
previous:
allOf:
- $ref: '#/components/schemas/Link'
next:
allOf:
- $ref: '#/components/schemas/Link'
last:
allOf:
- $ref: '#/components/schemas/Link'
additionalProperties: false
ExpenseDto:
type: object
properties:
updatedByUserId:
type:
- string
- 'null'
description: 'Unique identifier of the user updating the expense.
This field is reserved for server-to-server operations.'
example: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
staffId:
type:
- string
- 'null'
description: 'Unique identifier of the associated staff member.
When StaffId is not provided, the API will attempt to match your User Id to a Staff Id automatically.'
example: 47efff74-3e4b-45b3-bddf-affc6649db0b
invoiceId:
type:
- string
- 'null'
description: Unique identifier of the associated invoice.
example: fdb766bc-eb20-4bc1-9417-08b51a7b2286
expenseDate:
type: string
description: The date of the expense.
format: date-time
example: '2022-07-01'
activityCode:
type:
- string
- 'null'
description: The activity code associated to the expense.
example: PRT
subject:
type:
- string
- 'null'
description: The subject - this should be a short description of the expense.
example: Review contract
description:
type:
- string
- 'null'
description: Optional detailed description of the expense.
example: Print documents
costType:
type: string
description: 'The cost type of the expense.
* Hard - Direct cost such as travel, accommodation, or materials.
* Soft - Indirect cost such as administrative fees or overhead.'
example: Hard
quantity:
type: number
description: 'The quantity of the expense in units (if not applicable, use 1).
The expense amount will be calculated as Quantity * Price.'
format: double
example: 3
price:
type: number
description: 'The price of the expense in dollars. Limited to 2 decimal places (cents).
The expense amount will be calculated as Quantity * Price.'
format: double
example: 350.32
tax:
type:
- number
- 'null'
description: 'Tax amount of the expense in dollars. Only applicable in AU and UK regions.
When TaxOutOfScope or TaxExempt is true, this value must be 0.
When TaxZeroRated is true, this value can be greater than 0.'
format: double
example: 90
outputTax:
type:
- number
- 'null'
description: 'Output tax amount of the expense in dollars. Only applicable in AU and UK regions.
When TaxOutOfScope or TaxZeroRated is true, this value must be 0.
When TaxExempt is true, this value can be greater than 0.'
format: double
example: 85
taxInclusive:
type: boolean
description: 'If true, the amount is tax inclusive, otherwise tax exclusive. Only applicable in AU and UK regions.
Tax inclusive means: Amount exc. tax = Amount - Tax, Amount inc. tax = Amount.
Tax exclusive means: Amount exc. tax = Amount, Amount inc. tax = Amount + Tax.
(Amount = Price * Quantity, Tax = value of the Tax field)
This field is mutually exclusive with TaxZeroRated, TaxOutOfScope and TaxExempt.'
example: false
taxZeroRated:
type: boolean
description: 'True if the expense is zero-rated for tax purposes. Only supported in UK regions.
This field is mutually exclusive with TaxInclusive, TaxOutOfScope and TaxExempt.
When true, OutputTax must be 0.'
example: false
taxOutOfScope:
type: boolean
description: 'True if the expense is out of scope for tax purposes. Only supported in UK regions.
This field is mutually exclusive with TaxInclusive, TaxZeroRated and TaxExempt.
When true, both Tax and OutputTax must be 0.'
example: false
taxExempt:
type: boolean
description: 'True if the expense is exempt from tax.
This field is mutually exclusive with TaxInclusive, TaxZeroRated and TaxOutOfScope.
When true, Tax must be 0 but OutputTax can be greater than 0.'
example: false
finalized:
type: boolean
description: True if the expense has been finalized.
example: false
isWrittenOff:
type: boolean
description: "True if the expense is written off. True only allowed if IsBillable is true. \n\nWritten off expenses will show on an invoice with their amount, but will not be counted in the invoice total."
example: false
isBillable:
type: boolean
description: True if the expense is billable. Non-billable expense will, by default, not be shown on invoices (and, if shown, the amount will be 0).
example: false
isInvoicedExternally:
type: boolean
description: True if the expense is invoiced externally.
example: false
assignToFirmOwner:
type: boolean
description: 'Assigns expense to a firm owner if true. Ignored if a StaffId is provided.
Note: If there are multiple firm owners, it is not guaranteed that the same firm owner will be assigned everytime.'
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: {}
Expense:
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'
versionId:
type:
- string
- 'null'
description: Unique version identifier of the expense.
example: 23d2a4bc-8529-462e-8560-dfbf4fa24e49
createdByUserId:
type:
- string
- 'null'
description: Unique identifier of the user that created the expense.
example: 8a7f40ea-4123-4ebe-bb05-e9b4b666e706
staff:
allOf:
- $ref: '#/components/schemas/Link'
description: The staff member associated to the expense.
matter:
allOf:
- $ref: '#/components/schemas/Link'
description: The matter associated to the expense.
invoice:
allOf:
- $ref: '#/components/schemas/Link'
description: The invoice associated to the expense.
staffId:
type:
- string
- 'null'
description: Deprecated, use Staff.
matterId:
type:
- string
- 'null'
description: Deprecated, use Matter.
invoiceId:
type:
- string
- 'null'
description: Unique identifier of the associated invoice.
example: fdb766bc-eb20-4bc1-9417-08b51a7b2286
origin:
type:
- string
- 'null'
description: Where the expense originated from.
activityCode:
type:
- string
- 'null'
description: The activity code associated to the expense.
example: PRT
utbmsTaskCode:
type:
- string
- 'null'
description: The UTBMS task code associated to the expense, where UTBMS is enabled. Only applicable in US.
example: E101
subject:
type:
- string
- 'null'
description: The subject - this should be a short description of the expense.
example: Review contract
description:
type:
- string
- 'null'
description: Optional detailed description of the expense.
example: Print documents
expenseDate:
type: string
description: The date of the expense.
format: date-time
example: '2022-07-01'
costType:
type: string
description: 'The cost type of the expense.
* Hard - Direct cost such as travel, accommodation, or materials.
* Soft - Indirect cost such as administrative fees or overhead.'
example: Hard
quantity:
type: number
description: 'The quantity of the expense in units (if not applicable, use 1).
The expense amount will be calculated as Quantity * Price.'
format: double
example: 3
price:
type: number
description: 'The price of the expense in dollars. Limited to 2 decimal places (cents).
The expense amount will be calculated as Quantity * Price.'
format: double
example: 350.32
amount:
type: number
description: 'Total amount of the expense. Calculated as Price * Quantity.
This amount ignores GST (if applicable). See AmountExcTax and AmountIncTax.'
format: double
example: 900.21
amountExcTax:
type: number
description: 'Amount excluding tax. Calculated from Amount and Tax depending on the TaxInclusive property.
If tax is not applicable (outside AU), this will be the same as Amount.'
format: double
example: 810.01
amountIncTax:
type: number
description: 'Amount including tax. Calculated from Amount and Tax depending on the TaxInclusive property.
If tax is not applicable (outside AU), this will be the same as Amount.'
format: double
example: 900.21
tax:
type: number
description: GST amount of the expense in dollars. Only applicable in AU.
format: double
example: 90
outputTax:
type: number
description: 'Output tax amount of the expense in dollars. Only applicable in AU and UK regions.
When TaxOutOfScope or TaxZeroRated is true, this value must be 0.
When TaxExempt is true, this value can be greater than 0.'
format: double
example: 85
taxInclusive:
type: boolean
description: 'If true, the amount is GST inclusive, otherwise GST exclusive. Only applicable in AU.
GST inclusive means: Amount exc. GST = Amount - GST, Amount inc. GST = Amount.
GST exclusive means: Amount exc. GST = Amount, Amount inc. GST = Amount + GST.
(Amount = Price * Quantity, GST = value of the Tax field)'
example: false
taxZeroRated:
type: boolean
description: True if the expense is zero-rated for tax purposes.
example: false
taxOutOfScope:
type: boolean
description: True if the expense is out of scope for tax purposes.
example: false
taxExempt:
type: boolean
description: True if the expense is exempt from tax.
example: false
finalized:
type: boolean
description: True if the expense has been finalized.
example: false
isWrittenOff:
type: boolean
description: "True if the expense is written off. True only allowed if IsBillable is true. \n\nWritten off expenses will show on an invoice with their amount, but will not be counted in the invoice total."
example: false
isBillable:
type: boolean
description: True if the expense is billable. Non-billable expense will, by default, not be shown on invoices (and, if shown, the amount will be 0).
example: false
isInvoicedExternally:
type: boolean
description: True if the expense is invoiced externally.
example: false
isDeleted:
type: boolean
description: True if the expense is deleted.
example: false
additionalProperties: false
securitySchemes:
api-key:
type: apiKey
name: x-api-key
in: header
token:
type: apiKey
name: Authorization
in: header
x-amazon-apigateway-authtype: cognito_user_pools