The Fees API from Smokeball — 2 operation(s) for fees.
openapi: 3.0.1
info:
title: Smokeball Activity Codes Fees 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: Fees
paths:
/matters/{matterId}/fees:
get:
tags:
- Fees
summary: Get fees
description: Returns a list of fees for the specified matter.
operationId: GetFees
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 fees 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 'Fee' objects.
content:
application/json:
schema:
$ref: '#/components/schemas/FeePagedCollection'
'400':
description: When an unsupported request is made.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
post:
tags:
- Fees
summary: Create a fee
description: Creates a fee for the specified matter.
operationId: CreateFee
parameters:
- name: matterId
in: path
required: true
schema:
type: string
requestBody:
content:
application/json-patch+json:
schema:
allOf:
- $ref: '#/components/schemas/FeeDto'
application/json:
schema:
allOf:
- $ref: '#/components/schemas/FeeDto'
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/FeeDto'
responses:
'202':
description: When request is accepted. Returns a hypermedia 'Link' object of the fee 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}/fees/{id}:
get:
tags:
- Fees
summary: Get a fee
description: Retrieves a specified fee.
operationId: GetFeeById
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 a 'Fee' object.
content:
application/json:
schema:
$ref: '#/components/schemas/Fee'
'400':
description: When an unsupported request is made.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'403':
description: When fee with specified id is not associated with authenticated client.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When fee with specified id does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
put:
tags:
- Fees
summary: Update a fee
description: Updates a fee for the specified matter.
operationId: UpdateFee
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/FeeDto'
application/json:
schema:
allOf:
- $ref: '#/components/schemas/FeeDto'
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/FeeDto'
responses:
'202':
description: When request is accepted. Returns a hypermedia 'Link' object of the fee 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 fee with specified id is not associated with authenticated client.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When fee with specified id does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
patch:
tags:
- Fees
summary: Patch a fee
description: Patches a fee for the specified matter.
operationId: PatchFee
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/FeeDto'
application/json:
schema:
$ref: '#/components/schemas/FeeDto'
application/*+json:
schema:
$ref: '#/components/schemas/FeeDto'
responses:
'202':
description: When request is accepted. Returns a hypermedia 'Link' object of the fee 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 fee with specified id is not associated with authenticated client.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When fee with specified id does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
delete:
tags:
- Fees
summary: Delete a fee
description: Deletes a fee.
operationId: DeleteFee
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 fee 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 fee with specified id is not associated with authenticated client.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When fee with specified id does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
components:
schemas:
FeeSourceItem:
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
description:
type: string
description: The description.
nullable: true
duration:
type: integer
description: The duration in minutes.
format: int64
isBillable:
type: boolean
description: True if the fee source item is billable.
additionalProperties: false
FeeDto:
required:
- feeDate
- subject
type: object
properties:
updatedByUserId:
type: string
description: "Unique identifier of the user updating the fee.\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: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
invoiceId:
type: string
description: Unique identifier of the associated invoice.
nullable: true
example: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
activityCode:
type: string
description: The activity code associated to the fee.
nullable: true
example: PRT
feeType:
allOf:
- $ref: '#/components/schemas/FeeType'
description: The type of the fee (Fixed = 0, Time = 1).
example: 0
feeDate:
type: string
description: The date of the fee.
format: date-time
example: '2022-07-01'
subject:
minLength: 1
type: string
description: The subject - this should be a short description of the fee.
example: Review contract
description:
type: string
description: Optional detailed description of the fee.
nullable: true
example: Print documents
duration:
type: integer
description: The duration billed - in minutes. This duration is used if there are no sub activities.
format: int64
example: 60
durationWorked:
type: integer
description: The duration worked - in minutes. This duration is used if there are no sub activities.
format: int64
nullable: true
example: 50
rate:
type: number
description: The rate of the fee in dollars.
format: double
example: 350
tax:
type: number
description: "Tax amount of the fee in dollars. Only applicable in AU and UK regions.\r\n\r\nWhen TaxOutOfScope or TaxExempt is true, this value must be 0."
format: double
nullable: true
example: 35
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\r\n(Amount = Rate for fixed fees, or Rate * Duration for time fees, Tax = value of the Tax field)"
example: false
taxExempt:
type: boolean
description: "True if the fee is exempt from tax.\r\n\r\nThis field is mutually exclusive with TaxOutOfScope.\r\nWhen true, Tax must be 0."
example: false
taxOutOfScope:
type: boolean
description: "True if the fee is out of scope for tax purposes. Only supported in UK regions.\r\n\r\nThis field is mutually exclusive with TaxExempt.\r\nWhen true, Tax must be 0."
example: false
finalized:
type: boolean
description: True if the fee has been finalized.
example: false
isWrittenOff:
type: boolean
description: "True if the fee is written off. True only allowed if IsBillable is true.\r\n\r\nWritten off fee 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 fee is billable. Non-billable fee 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 fee is invoiced externally.
example: false
sourceItems:
type: array
items:
$ref: '#/components/schemas/FeeSourceItemDto'
description: The source items on the fee.
nullable: true
createdFromActivityId:
type: string
description: "Associates an existing activity id to a fee.\r\nOnly valid for Fee creation. \r\nValue is supplied by Smokeball for some partners."
nullable: true
example: 504b9f77-20c7-4dee-8227-d3007c8f6cea
additionalProperties: false
FeeSourceItemDto:
type: object
properties:
description:
type: string
description: The description.
nullable: true
example: Print document
duration:
type: integer
description: The duration in minutes.
format: int64
example: 5
isBillable:
type: boolean
description: True if the fee source item is billable.
example: false
additionalProperties: false
FeeType:
enum:
- 0
- 1
type: integer
description: The type of the fee (Fixed = 0, Time = 1).
format: int32
FeePagedCollection:
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/Fee'
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: {}
Fee:
type: object
properties:
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
id:
type: string
description: Unique identifier of the fee.
nullable: true
example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
versionId:
type: string
description: Unique version identifier of the fee.
nullable: true
example: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
matter:
allOf:
- $ref: '#/components/schemas/Link'
description: The matter associated to the fee.
nullable: true
staff:
allOf:
- $ref: '#/components/schemas/Link'
description: The staff member associated to the fee.
nullable: true
matterId:
type: string
description: Deprecated, use Matter.
nullable: true
staffId:
type: string
description: Deprecated, use Staff.
nullable: true
createdByUserId:
type: string
description: Unique identifier of the user that created the fee.
nullable: true
example: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
createdDate:
type: string
description: Date the fee was created.
format: date-time
example: '2026-04-13T11:00:00Z'
lastUpdatedByUserId:
type: string
description: Unique identifier of the user that updated the fee.
nullable: true
example: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
invoiceId:
type: string
description: Unique identifier of the associated invoice.
nullable: true
example: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
activityCode:
type: string
description: The activity code associated to the fee.
nullable: true
example: PRT
utbmsTaskCode:
type: string
description: The UTBMS task code associated to the fee, where UTBMS is enabled. Only applicable in US.
nullable: true
example: L110
subject:
type: string
description: The subject - this should be a short description of the fee.
nullable: true
example: Review contract
description:
type: string
description: Optional detailed description of the fee.
nullable: true
example: Print documents
feeDate:
type: string
description: The date of the fee.
format: date-time
example: '2022-07-01'
feeType:
allOf:
- $ref: '#/components/schemas/FeeType'
description: The type of the fee (Fixed = 0, Time = 1).
example: 0
finalized:
type: boolean
description: True if the fee has been finalized.
example: false
isInvoicedExternally:
type: boolean
description: True if the fee is invoiced externally.
example: false
isWrittenOff:
type: boolean
description: "True if the fee is written off. True only allowed if IsBillable is true.\r\n\r\nWritten off fee 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 fee is billable. Non-billable fee will, by default, not be shown on invoices (and, if shown, the amount will be 0).
nullable: true
example: false
tax:
type: number
description: GST amount of the fee in dollars. Only applicable in AU.
format: double
example: 35
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."
example: false
taxExempt:
type: boolean
description: True if the fee is tax exempt. In that case, Tax will always be 0.
example: false
taxOutOfScope:
type: boolean
description: True if the fee is out of scope for tax. In that case, Tax will always be 0.
example: false
duration:
type: integer
description: The duration billed - in minutes.
format: int64
example: 60
durationWorked:
type: integer
description: The duration worked - in minutes.
format: int64
nullable: true
example: 50
rate:
type: number
description: The rate of the fee in dollars.
format: double
example: 350
amount:
type: number
description: "Total amount of the fee in dollars. Calculated using Rate and Duration depending on the fee type.\r\n\r\nThis amount includes tax depending on the TaxInclusive property. See AmountExcTax and AmountIncTax."
format: double
example: 350
amountExcTax:
type: number
description: "Amount excluding tax in dollars. 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: 315
amountIncTax:
type: number
description: "Amount including tax in dollars. 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: 350
billableAmountExcTax:
type: number
description: "Billable amount excluding tax in dollars. If fee is billable, value will be the same as AmountExcTax. If it's non-billable,\r\nvalue will be 0.\r\n\r\nIf the fee is partially billable (i.e. has source items, some of which are billable and some not),\r\nthis value will contain the amount calculated from billable items only."
format: double
example: 315
billableTax:
type: number
description: "Billable tax in dollars. If fee is billable, value will be the same as Tax. If it's non-billable,\r\nvalue will be 0.\r\n\r\nIf the fee is partially billable (i.e. has source items, some of which are billable\r\nand some not), this value will contain the tax calculated from billable items only.\r\nIn all other cases, the value will be the same as Tax."
format: double
example: 35
isDeleted:
type: boolean
description: True if the fee is deleted.
example: false
sourceItems:
type: array
items:
$ref: '#/components/schemas/FeeSourceItem'
description: The source items on the fee.
nullable: true
createdFromActivityId:
type: string
description: Unique identifier of the Activity used to create the fee, if applicable.
nullable: true
example: 504b9f77-20c7-4dee-8227-d3007c8f6cea
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