The Invoices API from Smokeball — 3 operation(s) for invoices.
openapi: 3.0.1
info:
title: Smokeball Activity Codes Invoices 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: Invoices
paths:
/matters/{matterId}/invoices:
get:
tags:
- Invoices
summary: Get invoices
description: Returns a list of invoices for the specified matter.
operationId: GetInvoices
parameters:
- name: matterId
in: path
description: The unique identifier of the matter that the invoice belongs to.
required: true
schema:
type: string
- name: LastUpdated
in: query
description: Returns items updated since the specified date and time.
schema:
type: string
format: date-time
example: '2022-04-23T14:00:00Z'
example: '2022-04-23T14:00:00Z'
- name: UpdatedSince
in: query
description: Returns items updated since a specified time (.net ticks representation of the UTC datetime).
schema:
type: integer
format: int64
- 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
responses:
'200':
description: When request is successful. Returns a paged collection of 'Invoice' objects.
content:
application/json:
schema:
$ref: '#/components/schemas/InvoicePagedCollection'
'400':
description: When an unsupported request is made.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/matters/{matterId}/invoices/{invoiceId}:
get:
tags:
- Invoices
summary: Get an invoice
description: Retrieves a specified invoice.
operationId: GetInvoiceById
parameters:
- name: matterId
in: path
required: true
schema:
type: string
- name: invoiceId
in: path
required: true
schema:
type: string
responses:
'200':
description: When request is successful. Returns a 'Invoice' object.
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice'
'400':
description: When an unsupported request is made.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'403':
description: When invoice with specified id is not associated with authenticated client or matter.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/matters/{matterId}/invoices/{invoiceId}/download:
get:
tags:
- Invoices
summary: Get download url for an invoice
description: Retrieves download details for a specified invoice.
operationId: DownloadInvoiceFile
parameters:
- name: matterId
in: path
required: true
schema:
type: string
- name: invoiceId
in: path
required: true
schema:
type: string
responses:
'200':
description: When request is successful. Returns an 'InvoiceFileInfo' object.
content:
application/json:
schema:
$ref: '#/components/schemas/InvoiceFileInfo'
'400':
description: When an unsupported request is made.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'403':
description: When the requested file does not belong to the account making the request.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When invoice with the specified id does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
components:
schemas:
InvoiceStatus:
enum:
- 0
- 1
- 2
- 3
- 4
type: integer
description: "The status of the invoice.\r\n\r\nPossible values: Draft = 0, Final = 1, Paid = 2, Deleted = 3 or Void = 4."
format: int32
InvoicedMatterEntryItem:
type: object
properties:
id:
type: string
nullable: true
versionId:
type: string
nullable: true
type:
allOf:
- $ref: '#/components/schemas/EntryType'
description: "Type of the activity.\r\n\r\nPossible values: Fixed = '0', Time = '1', Expense = '2'"
additionalProperties: false
Surcharge:
type: object
properties:
type:
allOf:
- $ref: '#/components/schemas/SurchargeType'
description: "The type of surcharge applied to the invoice.\r\n\r\nPossible values: None = 0, Fixed = 1, Percentage = 2."
example: 1
fixedSurcharge:
type: number
description: "The fixed surcharge amount applied to the invoice total.\r\n\r\nOnly applicable when Type is Fixed."
format: double
nullable: true
example: 100
percentage:
type: number
format: double
nullable: true
description:
type: string
description: A description of the surcharge, such as the reason or category.
nullable: true
example: Late Payment Fee
applyTo:
allOf:
- $ref: '#/components/schemas/SurchargeApplyType'
description: "The surcharge application type, indicating what the surcharge applies to.\r\n\r\nPossible values: None = 0, Fees = 1, Expenses = 2, FeesAndExpenses = 3."
example: 1
additionalProperties: false
InvoiceFileInfo:
type: object
properties:
invoiceId:
type: string
description: Unique identifier of the requested invoice
nullable: true
example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
versionId:
type: string
description: Unique identifier of the invoice version
nullable: true
example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
downloadUrl:
type: string
description: Link to download file
nullable: true
example: ''
expiry:
type: string
description: Expiry date/time when the download link is no longer accessible
format: date-time
example: '2022-04-23T14:30:00Z'
status:
type: string
description: Current status of the invoice
nullable: true
example: Draft
additionalProperties: false
Invoice:
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: The unique identifier of the invoice.
nullable: true
example: 16567e88-784c-470e-8952-e5a70fe2eb0c
versionId:
type: string
description: The unique identifier representing the current version of the invoice.
nullable: true
example: 39ffde97-eeeb-4747-bb8f-7c7c10b3c985
matter:
allOf:
- $ref: '#/components/schemas/Link'
description: A link to the matter associated with the invoice.
nullable: true
matterId:
type: string
description: The unique identifier of the matter this invoice belongs to.
nullable: true
example: 6398a045-509e-49a2-9268-bb8231fa9340
lastUpdatedByUserId:
type: string
description: The unique identifier of the user who last updated the invoice.
nullable: true
example: 5fc5ee85-6643-4623-b019-a0dccceafe47
description:
type: string
description: A short description of the invoice contents or purpose.
nullable: true
example: Services provided.
status:
allOf:
- $ref: '#/components/schemas/InvoiceStatus'
description: "The status of the invoice.\r\n\r\nPossible values: Draft = 0, Final = 1, Paid = 2, Deleted = 3 or Void = 4."
example: 0
invoiceNumber:
type: integer
description: The sequential number assigned to the invoice.
format: int64
nullable: true
example: 10001
invoiceTitle:
type: string
description: The main title of the invoice.
nullable: true
example: My First Invoice
invoiceTitleLine2:
type: string
description: The optional second line of the invoice title.
nullable: true
example: Subtitle
issuedDate:
type: string
description: The date the invoice was issued.
format: date-time
example: '2022-09-16T00:00:00+00:00'
dueDate:
type: string
description: The date by which payment for the invoice is due.
format: date-time
example: '2022-09-25T00:00:00+00:00'
paidDate:
type: string
description: "The date the invoice was fully paid.\r\n\r\nOnly populated if the invoice has been paid in full."
format: date-time
example: '2022-09-20T00:00:00+00:00'
discount:
allOf:
- $ref: '#/components/schemas/Discount'
description: "The discount configuration for the invoice (e.g., fixed or percentage).\r\n\r\nSee InvoiceTotals.Discount for the actual amount discounted."
nullable: true
surcharge:
allOf:
- $ref: '#/components/schemas/Surcharge'
description: The surcharge configuration for the invoice (e.g., fixed or percentage).
nullable: true
debtors:
type: array
items:
$ref: '#/components/schemas/Debtor'
description: The list of debtors associated with this invoice.
nullable: true
entries:
type: array
items:
$ref: '#/components/schemas/InvoicedMatterEntryItem'
description: The individual entries (fees or expenses) included in the invoice.
nullable: true
waived:
type: boolean
description: Indicates whether the invoice has been waived.
example: false
invoiceTotals:
allOf:
- $ref: '#/components/schemas/InvoiceTotals'
description: The calculated totals for the invoice, including billed, paid, unpaid, tax, interest, discounts, etc.
nullable: true
additionalProperties: false
SurchargeType:
enum:
- 0
- 1
- 2
type: integer
format: int32
DiscountType:
enum:
- 0
- 1
type: integer
format: int32
EntryType:
enum:
- 0
- 1
- 2
type: integer
description: "Type of the activity.\r\n\r\nPossible values: Fixed = '0', Time = '1', Expense = '2'"
format: int32
Discount:
type: object
properties:
type:
allOf:
- $ref: '#/components/schemas/DiscountType'
description: "The type of discount applied to the invoice.\r\n\r\nFixed for a fixed amount, or Percentage for a percentage-based discount.\r\n\r\nPossible values: Fixed = 0, Percentage = 1."
example: 0
fixedDiscount:
type: number
description: "The fixed discount amount to be subtracted from the invoice total.\r\n\r\nOnly applicable when Type is Fixed."
format: double
example: 100
percentage:
type: number
description: "The percentage discount to be applied to the invoice total.\r\n\r\nOnly applicable when Type is Percentage.\r\n\r\nExpressed as a number between 0 and 100."
format: double
example: 10
description:
type: string
description: A description of the discount, such as the reason or category.
nullable: true
example: Friend of the Firm
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
InvoiceTotals:
type: object
properties:
paid:
type: number
description: The total amount that has been paid towards the invoice.
format: double
example: 100
billed:
type: number
description: "The total amount billed on the invoice, excluding tax and interest.\r\n\r\nThis includes all fees and expenses before discounts or write-offs."
format: double
example: 200
unpaid:
type: number
description: The remaining amount due on the invoice, including any unpaid tax or interest.
format: double
example: 100
unpaidExcInterest:
type: number
description: "The total unpaid amount excluding interest.\r\n\r\nIf this value is zero on an interest-bearing invoice, it indicates the principal has been fully paid,\r\nalthough interest may still be outstanding."
format: double
example: 100
writtenOff:
type: number
description: The total amount that has been written off from the invoice and is no longer expected to be paid.
format: double
example: 0
waived:
type: number
description: "The total amount that has been waived on the invoice.\r\n\r\nWaived amounts are not charged but are also not written off."
format: double
example: 0
discount:
type: number
description: "The total amount discounted on the invoice.\r\n\r\nThis includes all applied discounts reducing the billed amount."
format: double
example: 0
total:
type: number
description: The grand total for the invoice, including tax and interest, before any payments, discounts, or write-offs.
format: double
example: 100
tax:
type: number
description: The total tax amount applied to the invoice.
format: double
example: 10
interest:
type: number
description: The total interest charged on the invoice, regardless of what has been paid so far.
format: double
example: 0
feeTotal:
type: number
description: The total amount of all fees on the invoice, including both written off and non-written off fees.
format: double
example: 100
writtenOffFeeTotal:
type: number
description: The total amount of fees that have been written off.
format: double
example: 100
expenseTotal:
type: number
description: The total amount of all expenses on the invoice, including both written off and non-written off expenses.
format: double
example: 100
writtenOffExpenseTotal:
type: number
description: The total amount of expenses that have been written off.
format: double
example: 180
additionalProperties: false
InvoicePagedCollection:
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/Invoice'
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
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: {}
SurchargeApplyType:
enum:
- 0
- 1
- 2
- 3
type: integer
format: int32
Debtor:
type: object
properties:
contact:
allOf:
- $ref: '#/components/schemas/Link'
description: Hypermedia link of the associated contact.
nullable: true
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