openapi: 3.0.1
info:
  title: Smokeball Activity Codes Expenses 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: Expenses
paths:
  /matters/{matterId}/expenses:
    get:
      tags:
      - Expenses
      summary: Get expenses
      description: Returns a list of expenses for the specified matter.
      operationId: GetExpenses
      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 expenses 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 'Expense' objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpensePagedCollection'
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    post:
      tags:
      - Expenses
      summary: Create an expense
      description: Creates an expense for the specified matter.
      operationId: CreateExpense
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ExpenseDto'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ExpenseDto'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ExpenseDto'
      responses:
        '202':
          description: When request is accepted. Returns a hypermedia 'Link' object of the expense 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}/expenses/{id}:
    get:
      tags:
      - Expenses
      summary: Get an expense
      description: Retrieves a specified expense.
      operationId: GetExpenseById
      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 an 'Expense' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Expense'
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: When expense with specified id is not associated with authenticated client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When expense with specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    put:
      tags:
      - Expenses
      summary: Update an expense
      description: Updates an expense for the specified matter.
      operationId: UpdateExpense
      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/ExpenseDto'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ExpenseDto'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ExpenseDto'
      responses:
        '202':
          description: When request is accepted. Returns a hypermedia 'Link' object of the expense 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 expense with specified id is not associated with authenticated client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When expense with specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    patch:
      tags:
      - Expenses
      summary: Patch an expense
      description: Patches an expense for the specified matter.
      operationId: PatchExpense
      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/ExpenseDto'
          application/json:
            schema:
              $ref: '#/components/schemas/ExpenseDto'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ExpenseDto'
      responses:
        '202':
          description: When request is accepted. Returns a hypermedia 'Link' object of the expense 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 expense with specified id is not associated with authenticated client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When expense with specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    delete:
      tags:
      - Expenses
      summary: Delete an expense
      description: Deletes an expense.
      operationId: DeleteExpense
      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 expense 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 expense with specified id is not associated with authenticated client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When expense with specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    ExpenseDto:
      type: object
      properties:
        updatedByUserId:
          type: string
          description: "Unique identifier of the user updating the expense.\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: 47efff74-3e4b-45b3-bddf-affc6649db0b
        invoiceId:
          type: string
          description: Unique identifier of the associated invoice.
          nullable: true
          example: fdb766bc-eb20-4bc1-9417-08b51a7b2286
        expenseDate:
          type: string
          description: The date of the expense.
          format: date-time
          example: '2022-07-01'
        activityCode:
          type: string
          description: The activity code associated to the expense.
          nullable: true
          example: PRT
        subject:
          type: string
          description: The subject - this should be a short description of the expense.
          nullable: true
          example: Review contract
        description:
          type: string
          description: Optional detailed description of the expense.
          nullable: true
          example: Print documents
        costType:
          type: string
          description: "The cost type of the expense.\r\n\r\n* Hard - Direct cost such as travel, accommodation, or materials.\r\n\r\n* Soft - Indirect cost such as administrative fees or overhead."
          example: Hard
        quantity:
          type: number
          description: "The quantity of the expense in units (if not applicable, use 1).\r\n\r\nThe expense amount will be calculated as Quantity * Price."
          format: double
          example: 3
        price:
          type: number
          description: "The price of the expense in dollars. Limited to 2 decimal places (cents).\r\n\r\nThe expense amount will be calculated as Quantity * Price."
          format: double
          example: 350.32
        tax:
          type: number
          description: "Tax amount of the expense in dollars. Only applicable in AU and UK regions.\r\n\r\nWhen TaxOutOfScope or TaxExempt is true, this value must be 0.\r\nWhen TaxZeroRated is true, this value can be greater than 0."
          format: double
          nullable: true
          example: 90
        outputTax:
          type: number
          description: "Output tax amount of the expense in dollars. Only applicable in AU and UK regions.\r\n\r\nWhen TaxOutOfScope or TaxZeroRated is true, this value must be 0.\r\nWhen TaxExempt is true, this value can be greater than 0."
          format: double
          nullable: true
          example: 85
        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(Amount = Price * Quantity, Tax = value of the Tax field)\r\n\r\nThis field is mutually exclusive with TaxZeroRated, TaxOutOfScope and TaxExempt."
          example: false
        taxZeroRated:
          type: boolean
          description: "True if the expense is zero-rated for tax purposes. Only supported in UK regions.\r\n\r\nThis field is mutually exclusive with TaxInclusive, TaxOutOfScope and TaxExempt.\r\nWhen true, OutputTax must be 0."
          example: false
        taxOutOfScope:
          type: boolean
          description: "True if the expense is out of scope for tax purposes. Only supported in UK regions.\r\n\r\nThis field is mutually exclusive with TaxInclusive, TaxZeroRated and TaxExempt.\r\nWhen true, both Tax and OutputTax must be 0."
          example: false
        taxExempt:
          type: boolean
          description: "True if the expense is exempt from tax.\r\n\r\nThis field is mutually exclusive with TaxInclusive, TaxZeroRated and TaxOutOfScope.\r\nWhen true, Tax must be 0 but OutputTax can be greater than 0."
          example: false
        finalized:
          type: boolean
          description: True if the expense has been finalized.
          example: false
        isWrittenOff:
          type: boolean
          description: "True if the expense is written off. True only allowed if IsBillable is true. \r\n\r\nWritten off expenses 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 expense is billable. Non-billable expense 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 expense is invoiced externally.
          example: false
        assignToFirmOwner:
          type: boolean
          description: "Assigns expense to a firm owner if true. Ignored if a StaffId is provided.\r\n\r\nNote: If there are multiple firm owners, it is not guaranteed that the same firm owner will be assigned everytime."
      additionalProperties: false
    ExpensePagedCollection:
      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/Expense'
          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: {}
    Expense:
      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
        versionId:
          type: string
          description: Unique version identifier of the expense.
          nullable: true
          example: 23d2a4bc-8529-462e-8560-dfbf4fa24e49
        createdByUserId:
          type: string
          description: Unique identifier of the user that created the expense.
          nullable: true
          example: 8a7f40ea-4123-4ebe-bb05-e9b4b666e706
        staff:
          allOf:
          - $ref: '#/components/schemas/Link'
          description: The staff member associated to the expense.
          nullable: true
        matter:
          allOf:
          - $ref: '#/components/schemas/Link'
          description: The matter associated to the expense.
          nullable: true
        invoice:
          allOf:
          - $ref: '#/components/schemas/Link'
          description: The invoice associated to the expense.
          nullable: true
        staffId:
          type: string
          description: Deprecated, use Staff.
          nullable: true
        matterId:
          type: string
          description: Deprecated, use Matter.
          nullable: true
        invoiceId:
          type: string
          description: Unique identifier of the associated invoice.
          nullable: true
          example: fdb766bc-eb20-4bc1-9417-08b51a7b2286
        origin:
          type: string
          description: Where the expense originated from.
          nullable: true
        activityCode:
          type: string
          description: The activity code associated to the expense.
          nullable: true
          example: PRT
        utbmsTaskCode:
          type: string
          description: The UTBMS task code associated to the expense, where UTBMS is enabled. Only applicable in US.
          nullable: true
          example: E101
        subject:
          type: string
          description: The subject - this should be a short description of the expense.
          nullable: true
          example: Review contract
        description:
          type: string
          description: Optional detailed description of the expense.
          nullable: true
          example: Print documents
        expenseDate:
          type: string
          description: The date of the expense.
          format: date-time
          example: '2022-07-01'
        costType:
          type: string
          description: "The cost type of the expense.\r\n\r\n* Hard - Direct cost such as travel, accommodation, or materials.\r\n\r\n* Soft - Indirect cost such as administrative fees or overhead."
          example: Hard
        quantity:
          type: number
          description: "The quantity of the expense in units (if not applicable, use 1).\r\n\r\nThe expense amount will be calculated as Quantity * Price."
          format: double
          example: 3
        price:
          type: number
          description: "The price of the expense in dollars. Limited to 2 decimal places (cents).\r\n\r\nThe expense amount will be calculated as Quantity * Price."
          format: double
          example: 350.32
        amount:
          type: number
          description: "Total amount of the expense. Calculated as Price * Quantity.\r\n\r\nThis amount ignores GST (if applicable). See AmountExcTax and AmountIncTax."
          format: double
          example: 900.21
        amountExcTax:
          type: number
          description: "Amount excluding tax. 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: 810.01
        amountIncTax:
          type: number
          description: "Amount including tax. 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: 900.21
        tax:
          type: number
          description: GST amount of the expense in dollars. Only applicable in AU.
          format: double
          example: 90
        outputTax:
          type: number
          description: "Output tax amount of the expense in dollars. Only applicable in AU and UK regions.\r\n\r\nWhen TaxOutOfScope or TaxZeroRated is true, this value must be 0.\r\nWhen TaxExempt is true, this value can be greater than 0."
          format: double
          example: 85
        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.\r\n(Amount = Price * Quantity, GST = value of the Tax field)"
          example: false
        taxZeroRated:
          type: boolean
          description: True if the expense is zero-rated for tax purposes.
          example: false
        taxOutOfScope:
          type: boolean
          description: True if the expense is out of scope for tax purposes.
          example: false
        taxExempt:
          type: boolean
          description: True if the expense is exempt from tax.
          example: false
        finalized:
          type: boolean
          description: True if the expense has been finalized.
          example: false
        isWrittenOff:
          type: boolean
          description: "True if the expense is written off. True only allowed if IsBillable is true. \r\n\r\nWritten off expenses 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 expense is billable. Non-billable expense 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 expense is invoiced externally.
          example: false
        isDeleted:
          type: boolean
          description: True if the expense is deleted.
          example: false
      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