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