The Expenses API from Smokeball — 2 operation(s) for expenses.
openapi: 3.0.1
info:
title: Smokeball Activity Codes 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:
ExpenseDto:
type: object
properties:
updatedByUserId:
type: string
description: "Unique identifier of the user updating the expense.\r\n\r\nThis field is reserved for server-to-server operations."
nullable: true
example: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
staffId:
type: string
description: "Unique identifier of the associated staff member.\r\n\r\nWhen StaffId is not provided, the API will attempt to match your User Id to a Staff Id automatically."
nullable: true
example: 47efff74-3e4b-45b3-bddf-affc6649db0b
invoiceId:
type: string
description: Unique identifier of the associated invoice.
nullable: true
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
description: The activity code associated to the expense.
nullable: true
example: PRT
subject:
type: string
description: The subject - this should be a short description of the expense.
nullable: true
example: Review contract
description:
type: string
description: Optional detailed description of the expense.
nullable: true
example: Print documents
costType:
type: string
description: "The cost type of the expense.\r\n\r\n* Hard - Direct cost such as travel, accommodation, or materials.\r\n\r\n* 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).\r\n\r\nThe 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).\r\n\r\nThe expense amount will be calculated as Quantity * Price."
format: double
example: 350.32
tax:
type: number
description: "Tax amount of the expense in dollars. Only applicable in AU and UK regions.\r\n\r\nWhen TaxOutOfScope or TaxExempt is true, this value must be 0.\r\nWhen TaxZeroRated is true, this value can be greater than 0."
format: double
nullable: true
example: 90
outputTax:
type: number
description: "Output tax amount of the expense in dollars. Only applicable in AU and UK regions.\r\n\r\nWhen TaxOutOfScope or TaxZeroRated is true, this value must be 0.\r\nWhen TaxExempt is true, this value can be greater than 0."
format: double
nullable: true
example: 85
taxInclusive:
type: boolean
description: "If true, the amount is tax inclusive, otherwise tax exclusive. Only applicable in AU and UK regions.\r\n\r\nTax inclusive means: Amount exc. tax = Amount - Tax, Amount inc. tax = Amount.\r\n\r\nTax exclusive means: Amount exc. tax = Amount, Amount inc. tax = Amount + Tax.\r\n(Amount = Price * Quantity, Tax = value of the Tax field)\r\n\r\nThis 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.\r\n\r\nThis field is mutually exclusive with TaxInclusive, TaxOutOfScope and TaxExempt.\r\nWhen 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.\r\n\r\nThis field is mutually exclusive with TaxInclusive, TaxZeroRated and TaxExempt.\r\nWhen true, both Tax and OutputTax must be 0."
example: false
taxExempt:
type: boolean
description: "True if the expense is exempt from tax.\r\n\r\nThis field is mutually exclusive with TaxInclusive, TaxZeroRated and TaxOutOfScope.\r\nWhen 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. \r\n\r\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.\r\n\r\nNote: If there are multiple firm owners, it is not guaranteed that the same firm owner will be assigned everytime."
additionalProperties: false
ExpensePagedCollection:
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
self:
allOf:
- $ref: '#/components/schemas/Link'
nullable: true
value:
type: array
items:
$ref: '#/components/schemas/Expense'
nullable: true
offset:
type: integer
format: int32
nullable: true
limit:
type: integer
format: int32
nullable: true
size:
type: integer
format: int64
first:
allOf:
- $ref: '#/components/schemas/Link'
nullable: true
previous:
allOf:
- $ref: '#/components/schemas/Link'
nullable: true
next:
allOf:
- $ref: '#/components/schemas/Link'
nullable: true
last:
allOf:
- $ref: '#/components/schemas/Link'
nullable: true
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
ProblemDetails:
type: object
properties:
type:
type: string
nullable: true
title:
type: string
nullable: true
status:
type: integer
format: int32
nullable: true
detail:
type: string
nullable: true
instance:
type: string
nullable: true
additionalProperties: {}
Expense:
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
self:
allOf:
- $ref: '#/components/schemas/Link'
nullable: true
versionId:
type: string
description: Unique version identifier of the expense.
nullable: true
example: 23d2a4bc-8529-462e-8560-dfbf4fa24e49
createdByUserId:
type: string
description: Unique identifier of the user that created the expense.
nullable: true
example: 8a7f40ea-4123-4ebe-bb05-e9b4b666e706
staff:
allOf:
- $ref: '#/components/schemas/Link'
description: The staff member associated to the expense.
nullable: true
matter:
allOf:
- $ref: '#/components/schemas/Link'
description: The matter associated to the expense.
nullable: true
invoice:
allOf:
- $ref: '#/components/schemas/Link'
description: The invoice associated to the expense.
nullable: true
staffId:
type: string
description: Deprecated, use Staff.
nullable: true
matterId:
type: string
description: Deprecated, use Matter.
nullable: true
invoiceId:
type: string
description: Unique identifier of the associated invoice.
nullable: true
example: fdb766bc-eb20-4bc1-9417-08b51a7b2286
origin:
type: string
description: Where the expense originated from.
nullable: true
activityCode:
type: string
description: The activity code associated to the expense.
nullable: true
example: PRT
utbmsTaskCode:
type: string
description: The UTBMS task code associated to the expense, where UTBMS is enabled. Only applicable in US.
nullable: true
example: E101
subject:
type: string
description: The subject - this should be a short description of the expense.
nullable: true
example: Review contract
description:
type: string
description: Optional detailed description of the expense.
nullable: true
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.\r\n\r\n* Hard - Direct cost such as travel, accommodation, or materials.\r\n\r\n* 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).\r\n\r\nThe 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).\r\n\r\nThe 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.\r\n\r\nThis 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.\r\n\r\nIf 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.\r\n\r\nIf 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.\r\n\r\nWhen TaxOutOfScope or TaxZeroRated is true, this value must be 0.\r\nWhen 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.\r\n\r\nGST inclusive means: Amount exc. GST = Amount - GST, Amount inc. GST = Amount.\r\n\r\nGST exclusive means: Amount exc. GST = Amount, Amount inc. GST = Amount + GST.\r\n(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. \r\n\r\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