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