Smokeball Invoices API

openapi: 3.2.0
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:
    Discount:
      type: object
      properties:
        type:
          allOf:
          - $ref: '#/components/schemas/DiscountType'
          description: 'The type of discount applied to the invoice.


            Fixed for a fixed amount, or Percentage for a percentage-based discount.


            Possible values: Fixed = 0, Percentage = 1.'
          example: 0
        fixedDiscount:
          type: number
          description: 'The fixed discount amount to be subtracted from the invoice total.


            Only applicable when Type is Fixed.'
          format: double
          example: 100
        percentage:
          type: number
          description: 'The percentage discount to be applied to the invoice total.


            Only applicable when Type is Percentage.


            Expressed as a number between 0 and 100.'
          format: double
          example: 10
        description:
          type:
          - string
          - 'null'
          description: A description of the discount, such as the reason or category.
          example: Friend of the Firm
      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.


            This 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.


            If this value is zero on an interest-bearing invoice, it indicates the principal has been fully paid,

            although 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.


            Waived 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.


            This 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
    DiscountType:
      enum:
      - 0
      - 1
      type: integer
      format: int32
    Invoice:
      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: The unique identifier of the invoice.
          example: 16567e88-784c-470e-8952-e5a70fe2eb0c
        versionId:
          type:
          - string
          - 'null'
          description: The unique identifier representing the current version of the invoice.
          example: 39ffde97-eeeb-4747-bb8f-7c7c10b3c985
        matter:
          allOf:
          - $ref: '#/components/schemas/Link'
          description: A link to the matter associated with the invoice.
        matterId:
          type:
          - string
          - 'null'
          description: The unique identifier of the matter this invoice belongs to.
          example: 6398a045-509e-49a2-9268-bb8231fa9340
        lastUpdatedByUserId:
          type:
          - string
          - 'null'
          description: The unique identifier of the user who last updated the invoice.
          example: 5fc5ee85-6643-4623-b019-a0dccceafe47
        description:
          type:
          - string
          - 'null'
          description: A short description of the invoice contents or purpose.
          example: Services provided.
        status:
          allOf:
          - $ref: '#/components/schemas/InvoiceStatus'
          description: 'The status of the invoice.


            Possible values: Draft = 0, Final = 1, Paid = 2, Deleted = 3 or Void = 4.'
          example: 0
        invoiceNumber:
          type:
          - integer
          - 'null'
          description: The sequential number assigned to the invoice.
          format: int64
          example: 10001
        invoiceTitle:
          type:
          - string
          - 'null'
          description: The main title of the invoice.
          example: My First Invoice
        invoiceTitleLine2:
          type:
          - string
          - 'null'
          description: The optional second line of the invoice title.
          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.


            Only 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).


            See InvoiceTotals.Discount for the actual amount discounted.'
        surcharge:
          allOf:
          - $ref: '#/components/schemas/Surcharge'
          description: The surcharge configuration for the invoice (e.g., fixed or percentage).
        debtors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Debtor'
          description: The list of debtors associated with this invoice.
        entries:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/InvoicedMatterEntryItem'
          description: The individual entries (fees or expenses) included in the invoice.
        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.
      additionalProperties: false
    InvoicedMatterEntryItem:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
        versionId:
          type:
          - string
          - 'null'
        type:
          allOf:
          - $ref: '#/components/schemas/EntryType'
          description: 'Type of the activity.


            Possible values: Fixed = ''0'', Time = ''1'', Expense = ''2'''
      additionalProperties: false
    InvoicePagedCollection:
      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/Invoice'
        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
    SurchargeApplyType:
      enum:
      - 0
      - 1
      - 2
      - 3
      type: integer
      format: int32
    SurchargeType:
      enum:
      - 0
      - 1
      - 2
      type: integer
      format: int32
    Debtor:
      type: object
      properties:
        contact:
          allOf:
          - $ref: '#/components/schemas/Link'
          description: Hypermedia link of the associated contact.
      additionalProperties: false
    Surcharge:
      type: object
      properties:
        type:
          allOf:
          - $ref: '#/components/schemas/SurchargeType'
          description: 'The type of surcharge applied to the invoice.


            Possible values: None = 0, Fixed = 1, Percentage = 2.'
          example: 1
        fixedSurcharge:
          type:
          - number
          - 'null'
          description: 'The fixed surcharge amount applied to the invoice total.


            Only applicable when Type is Fixed.'
          format: double
          example: 100
        percentage:
          type:
          - number
          - 'null'
          format: double
        description:
          type:
          - string
          - 'null'
          description: A description of the surcharge, such as the reason or category.
          example: Late Payment Fee
        applyTo:
          allOf:
          - $ref: '#/components/schemas/SurchargeApplyType'
          description: 'The surcharge application type, indicating what the surcharge applies to.


            Possible values: None = 0, Fees = 1, Expenses = 2, FeesAndExpenses = 3.'
          example: 1
      additionalProperties: false
    InvoiceStatus:
      enum:
      - 0
      - 1
      - 2
      - 3
      - 4
      type: integer
      description: 'The status of the invoice.


        Possible values: Draft = 0, Final = 1, Paid = 2, Deleted = 3 or Void = 4.'
      format: int32
    InvoiceFileInfo:
      type: object
      properties:
        invoiceId:
          type:
          - string
          - 'null'
          description: Unique identifier of the requested invoice
          example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
        versionId:
          type:
          - string
          - 'null'
          description: Unique identifier of the invoice version
          example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
        downloadUrl:
          type:
          - string
          - 'null'
          description: Link to download file
          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
          - 'null'
          description: Current status of the invoice
          example: Draft
      additionalProperties: false
    Link:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
        href:
          type:
          - string
          - 'null'
        relation:
          type:
          - string
          - 'null'
        method:
          type:
          - string
          - 'null'
          default: GET
      additionalProperties: false
    EntryType:
      enum:
      - 0
      - 1
      - 2
      type: integer
      description: 'Type of the activity.


        Possible values: Fixed = ''0'', Time = ''1'', Expense = ''2'''
      format: int32
    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: {}
  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