Clio Allocations API

openapi: 3.2.0
info:
  title: Clio API Documentation Allocations API
  contact:
    name: Clio API Support
    email: api@clio.com
  description: '# Developer Support and Feedback

    * Clio takes the availability and stability of our API seriously; please report any **degradations** or **breakages** to Clio''s API Support team at api@clio.com.'
  version: v4
  x-logo:
    url: https://www.clio.com/wp-content/uploads/2015/05/Container-5-Logo.png
servers:
- url: https://app.clio.com/api/v4
  description: US region Production Server
- url: https://eu.app.clio.com/api/v4
  description: Europe region Production Server
- url: https://ca.app.clio.com/api/v4
  description: Canada region Production Server
- url: https://au.app.clio.com/api/v4
  description: Australia region Production Server
tags:
- name: Allocations
  description: 'Once a Payment or Credit Note has been recorded, an Allocation links it to a Bill.


    It''s possible for interest Allocations ("interest" = "true") to not be linked to a Bill. This can happen if the linked interest Bill is deleted (something the system allows.)


    Support Link'
paths:
  /allocations.json:
    get:
      tags:
      - Allocations
      summary: Return the data for all Allocations
      operationId: Allocation#index
      description: Outlines the parameters, optional and required, used when requesting the data for all Allocations
      parameters:
      - name: X-API-VERSION
        in: header
        description: 'The [API minor version](#section/Minor-Versions). Default: latest version.'
        required: false
        schema:
          type: string
      - name: bill_id
        in: query
        description: The unique identifier for a single Bill. The keyword `null` is not valid for this field. The list will be filtered to include only the Allocation records with the matching property.
        required: false
        schema:
          type: integer
          format: int64
      - name: contact_id
        in: query
        description: The unique identifier for a single Contact. The keyword `null` is not valid for this field. The list will be filtered to include only the Allocation records with the matching property.
        required: false
        schema:
          type: integer
          format: int64
      - name: created_since
        in: query
        description: Filter Allocation records to those having the `created_at` field after a specific time. (Expects an ISO-8601 timestamp).
        required: false
        schema:
          type: string
          format: date-time
      - name: fields
        in: query
        description: The fields to be returned. See response samples for what fields are available. For more information see the [fields section](#section/Fields).
        required: false
        schema:
          type: string
      - name: ids[]
        in: query
        description: Filter Allocation records to those having the specified unique identifiers.
        required: false
        schema:
          type: integer
          format: int64
      - name: limit
        in: query
        description: 'A limit on the number of Allocation records to be returned. Limit can range between 1 and 200. Default: `200`.'
        required: false
        schema:
          type: integer
          format: int32
      - name: matter_id
        in: query
        description: The unique identifier for a single Matter. The keyword `null` is not valid for this field. The list will be filtered to include only the Allocation records with the matching property.
        required: false
        schema:
          type: integer
          format: int64
      - name: order
        in: query
        description: 'Orders the Allocation records by the given field. Default: `date(asc)`.'
        required: false
        schema:
          type: string
          enum:
          - id(asc)
          - id(desc)
          - date(asc)
          - date(desc)
      - name: page_token
        in: query
        description: A token specifying which page to return.
        required: false
        schema:
          type: string
      - name: parent_id
        in: query
        description: ID of parent (either a Payment or CreditMemo) this allocation belongs to
        required: false
        schema:
          type: integer
          format: int64
      - name: parent_type
        in: query
        description: Filter Allocation records based on whether the parent is a CreditMemo or a Payment.
        required: false
        schema:
          type: integer
          format: int32
      - name: status
        in: query
        description: Filter Allocation records to only those that are voided (`"invalid"`) or not voided (`"valid"`).
        required: false
        schema:
          type: string
          enum:
          - valid
          - invalid
      - name: updated_since
        in: query
        description: Filter Allocation records to those having the `updated_at` field after a specific time. (Expects an ISO-8601 timestamp).
        required: false
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Ok
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Allocation_List'
        '400':
          description: Bad Request
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too Many Requests
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
  /allocations/{id}.json:
    get:
      tags:
      - Allocations
      summary: Return the data for a single Allocation
      operationId: Allocation#show
      description: Outlines the parameters, optional and required, used when requesting the data for a single Allocation
      parameters:
      - name: IF-MODIFIED-SINCE
        in: header
        description: The server will send the requested resource with a 200 status, but only if it has been modified after the given date. (Expects an RFC 2822 timestamp).
        required: false
        schema:
          type: string
          format: date
      - name: IF-NONE-MATCH
        in: header
        description: The server will send the requested resource with a 200 status, but only if the existing resource's [ETag](#section/ETags) doesn't match any of the values listed.
        required: false
        schema:
          type: string
      - name: X-API-VERSION
        in: header
        description: 'The [API minor version](#section/Minor-Versions). Default: latest version.'
        required: false
        schema:
          type: string
      - name: fields
        in: query
        description: The fields to be returned. See response samples for what fields are available. For more information see the [fields section](#section/Fields).
        required: false
        schema:
          type: string
      - name: id
        in: path
        description: The unique identifier for the Allocation.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Ok
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Allocation_Show'
        '400':
          description: Bad Request
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too Many Requests
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '304':
          description: Not Modified
components:
  schemas:
    Contact_base:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier for the *Contact*
        etag:
          type: string
          description: ETag for the *Contact*
        name:
          type: string
          description: The full name of the *Contact*
        first_name:
          type: string
          description: First name of the Person
        middle_name:
          type: string
          description: Middle name of the Person
        last_name:
          type: string
          description: Last name of the Person
        date_of_birth:
          type: string
          format: date
          description: Date of birth
        type:
          type: string
          enum:
          - Company
          - Person
          description: The type of the *Contact*
        created_at:
          type: string
          format: date-time
          description: The time the *Contact* was created (as a ISO-8601 timestamp)
        updated_at:
          type: string
          format: date-time
          description: The time the *Contact* was last updated (as a ISO-8601 timestamp)
        prefix:
          type: string
          description: The prefix of the *Contact* (Mr, Mrs, etc)
        title:
          type: string
          description: The designated title of the *Contact*
        initials:
          type: string
          description: The initials of the *Contact*
        clio_connect_email:
          type: string
          description: Clio Connect email if the *Contact* is a ClioConnect User
        locked_clio_connect_email:
          type: boolean
          description: A boolean indicating if the ability to modify this *Contacts Clio connect email is locked.
        client_connect_user_id:
          type: integer
          format: int64
          description: The ID for the Clio Connect user associated with this *Contact*
        primary_email_address:
          type: string
          description: The primary email address associated with this *Contact*.
        secondary_email_address:
          type: string
          description: The secondary email address associated with this *Contact*.
        primary_phone_number:
          type: string
          description: The primary phone number associated with this *Contact*.
        secondary_phone_number:
          type: string
          description: The secondary phone number of the *Contact*.
        ledes_client_id:
          type: string
          description: LEDES client id of the Contact
        has_clio_for_clients_permission:
          type: boolean
          description: True if at least one resource has been shared with the contact using Clio for Clients.
        is_client:
          type: boolean
          description: Whether or not the Contact is a client
        is_clio_for_client_user:
          type: boolean
          description: Whether or not this contact has client_login and client_user (can be created due to addition to client portal or client_share_permissions)
        is_co_counsel:
          type: boolean
          description: Whether or not the Contact has matters shared as co-counsel
        is_bill_recipient:
          type: boolean
          description: Whether the Contact is a bill recipient on at least one matter.
        sales_tax_number:
          type: string
          description: The sales tax number of the *Contact*
        currency:
          type: object
          description: Currency of the *Contact*
    Allocation_List:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          description: Allocation List Response
          items:
            $ref: '#/components/schemas/Allocation'
    Matter_base:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier for the *Matter*
        etag:
          type: string
          description: ETag for the *Matter*
        number:
          type: integer
          format: int32
          description: The number given to the *Matter* within an account
        display_number:
          type: string
          description: The reference and label of the *Matter*. Depending on the account's manual_matter_numbering setting, this is either read only (generated) or customizable.
        custom_number:
          type: string
          description: User defined custom number of the *Matter*
        currency:
          type: object
          description: Currency of the matter
        description:
          type: string
          description: The detailed description of the *Matter*
        status:
          type: string
          enum:
          - Pending
          - Open
          - Closed
          description: The current status of the *Matter*
        location:
          type: string
          description: The location of the *Matter*
        client_reference:
          type: string
          description: Client Reference string for external uses
        client_id:
          type: integer
          format: int64
          description: Client ID
        billable:
          type: boolean
          description: Whether this matter is billable
        maildrop_address:
          type: string
          description: A unique Maildrop email address for the matter
        billing_method:
          type: string
          enum:
          - flat
          - contingency
          - hourly
          description: Billing method of this matter
        open_date:
          type: string
          format: date
          description: The date the matter was set to open (as a ISO-8601 date)
        close_date:
          type: string
          format: date
          description: The date the matter was set to closed (as a ISO-8601 date)
        pending_date:
          type: string
          format: date
          description: The date the matter was set to pending (as a ISO-8601 date)
        created_at:
          type: string
          format: date-time
          description: The time the *Matter* was created (as a ISO-8601 timestamp)
        updated_at:
          type: string
          format: date-time
          description: The time the *Matter* was last updated (as a ISO-8601 timestamp)
        shared:
          type: boolean
          description: Whether the matter is currently shared with Clio Connect
        has_tasks:
          type: boolean
          description: Whether or not the matter has any tasks.
        last_activity_date:
          type: string
          format: date
          description: The greatest date out of all of the activities on the matter (as a ISO-8601 date)
        matter_stage_updated_at:
          type: string
          format: date-time
          description: The date the matter stage was last updated (as a ISO-8601 date)
    BankAccount_base:
      type: object
      properties:
        account_number:
          type: string
          description: The account number for *BankAccount*
        balance:
          type: number
          format: double
          description: The current balance of the *BankAccount*
        bank_transactions_count:
          type: integer
          format: int32
          description: The number of bank transactions associated with the account.
        clio_payment_page_link:
          type: string
          description: Link to Single Payment Page which allows to transfer funds without logging in.
        clio_payment_page_qr_code:
          type: string
          description: A QR code that links to a Single Payment Page which allows to transfer funds without logging in.
        clio_payments_enabled:
          type: boolean
          description: Whether the bank account is connected to Clio Payments
        controlled_account:
          type: boolean
          description: Whether is a controlled account
        created_at:
          type: string
          format: date-time
          description: The time the *BankAccount* was created (as a ISO-8601 timestamp)
        currency:
          type: string
          description: The currency type of the *BankAccount*
        currency_symbol:
          type: string
          description: The currency symbol of the *BankAccount*
        currency_id:
          type: number
          format: double
          description: The currency ID of the *BankAccount*
        default_account:
          type: boolean
          description: Whether it is the default account
        domicile_branch:
          type: string
          description: The name of the branch where the account was opened
        etag:
          type: string
          description: ETag for the *BankAccount*
        general_ledger_number:
          type: string
          description: General ledger number
        holder:
          type: string
          description: The name of the person or business that owns the *BankAccount*
        id:
          type: integer
          format: int64
          description: Unique identifier for the *BankAccount*
        institution:
          type: string
          description: The financial institution where the *BankAccount* is registered
        name:
          type: string
          description: The name of the *BankAccount*
        swift:
          type: string
          description: A unique identification code for the financial institution
        transit_number:
          type: string
          description: Transit number for the bank account branch
        type:
          type: string
          enum:
          - Operating
          - Trust
          description: The type of the *BankAccount*
        updated_at:
          type: string
          format: date-time
          description: The time the *BankAccount* was last updated (as a ISO-8601 timestamp)
    Bill_base:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier for the *Bill*
        etag:
          type: string
          description: ETag for the *Bill*
        number:
          type: string
          description: The *Bill* identifier (not necessarily numeric)'
        issued_at:
          type: string
          format: date
          description: The time the *Bill* was issued (as a ISO-8601 date)
        created_at:
          type: string
          format: date-time
          description: The time the *Bill* was created (as a ISO-8601 timestamp)
        due_at:
          type: string
          format: date
          description: The date the *Bill* is due (as a ISO-8601 date)
        tax_rate:
          type: number
          format: double
          description: The tax rate to the *Bill*
        secondary_tax_rate:
          type: number
          format: double
          description: A secondary tax rate applied to the *Bill*
        updated_at:
          type: string
          format: date-time
          description: The time the *Bill* was last updated (as a ISO-8601 timestamp)
        subject:
          type: string
          description: The subject of the *Bill*
        purchase_order:
          type: string
          description: The purchase order of the *Bill*
        type:
          type: string
          enum:
          - MatterBill
          - ClientBill
          description: The type of the *Bill*
        memo:
          type: string
          description: A memo for the *Bill*
        start_at:
          type: string
          format: date
          description: The time the billing period starts (as a ISO-8601 date)
        end_at:
          type: string
          format: date
          description: The time the billing period ends (as a ISO-8601 date)
        balance:
          type: number
          format: double
          description: The outstanding balance of the *Bill*
        state:
          type: string
          enum:
          - draft
          - awaiting_approval
          - awaiting_payment
          - paid
          - void
          - deleted
          description: The billing state the *Bill* is in
        kind:
          type: string
          enum:
          - revenue_kind
          - summary_kind
          - trust_kind
          - aggregate_all
          - aggregate_split
          - aggregate_services
          - aggregate_expenses
          description: The kind of the *Bill*
        total:
          type: number
          format: double
          description: The total with interest of the *Bill*
        paid:
          type: number
          format: double
          description: The total amount paid for the *Bill*
        paid_at:
          type: string
          format: date-time
          description: The date of the last payment on the *Bill*
        pending:
          type: number
          format: double
          description: The amount of pending credit card payments on the *Bill*
        due:
          type: number
          format: double
          description: The total amount of the *Bill* with interest and less discounts
        discount_services_only:
          type: string
          description: The selected discount is applied to services only.
        can_update:
          type: boolean
          description: This value indicates if your *Bill*'s line items and information can be updated.
        credits_issued:
          type: number
          format: double
          description: The total credits issued for the *Bill*
        shared:
          type: boolean
          description: Whether the *Bill* is a shared
        last_sent_at:
          type: string
          format: date-time
          description: The last time the *Bill* was sent (as a ISO-8601 date)
        services_secondary_tax:
          type: number
          format: double
          description: The total secondary tax of the bill's line items of a service kind
        services_sub_total:
          type: number
          format: double
          description: The sub total of all the bill's line items of a service kind
        services_tax:
          type: number
          format: double
          description: The total tax of the bill's line items of a service kind
        services_taxable_sub_total:
          type: integer
          format: int64
          description: The services portion of the bill's primary tax
        services_secondary_taxable_sub_total:
          type: integer
          format: int64
          description: The services portion of the bill's secondary tax
        taxable_sub_total:
          type: integer
          format: int64
          description: The total taxable bill amount
        secondary_taxable_sub_total:
          type: integer
          format: int64
          description: The subtotal of the bill's secondary tax
        sub_total:
          type: number
          format: double
          description: Sub total for the *Bill*
        tax_sum:
          type: number
          format: double
          description: Sum of primary tax for the model
        secondary_tax_sum:
          type: number
          format: double
          description: Sum of secondary tax for the model
        total_tax:
          type: number
          format: double
          description: The total amount of tax for the bill.
        available_state_transitions:
          type: array
          items:
            type: string
            enum:
            - awaiting_approval
            - awaiting_payment
            - paid
            - void
            - deleted
          description: The available *Bill* state transitions.
    ErrorDetail:
      type: object
      required:
      - type
      - message
      properties:
        type:
          type: string
          description: Unique name for this error
        message:
          type: string
          description: Detailed message about the error
    Allocation:
      allOf:
      - $ref: '#/components/schemas/Allocation_base'
      - type: object
        properties:
          bill:
            $ref: '#/components/schemas/Bill_base'
            description: Bill
          source_bank_account:
            $ref: '#/components/schemas/BankAccount_base'
            description: BankAccount
          destination_bank_account:
            $ref: '#/components/schemas/BankAccount_base'
            description: BankAccount
          matter:
            $ref: '#/components/schemas/Matter_base'
            description: Matter
          contact:
            $ref: '#/components/schemas/Contact_base'
            description: Contact
          parent:
            $ref: '#/components/schemas/PolymorphicObject_base'
            description: PolymorphicObject
    Allocation_base:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier for the *Allocation*
        etag:
          type: string
          description: ETag for the *Allocation*
        date:
          type: string
          format: date
          description: The date the allocation was applied (as a ISO-8601 date)
        amount:
          type: number
          format: double
          description: The total amount of money that the user has allocated
        interest:
          type: boolean
          description: Whether the allocation is applied to interest amount
        voided_at:
          type: string
          format: date-time
          description: Time the *Allocation* was voided (as a ISO-8601 timestamp)
        created_at:
          type: string
          format: date-time
          description: The time the *Allocation* was created (as a ISO-8601 timestamp)
        updated_at:
          type: string
          format: date-time
          description: The time the *Allocation* was last updated (as a ISO-8601 timestamp)
        description:
          type: string
          description: The description from the associated Credit Memo (if applicable)
        has_online_payment:
          type: boolean
          description: Whether this allocation is associated with an online payment or not
        destroyable:
          type: boolean
          description: Whether the record can be deleted or not
        payment_type:
          type: string
          description: A string indicating whether the payment is a card or an eCheck payment.
    PolymorphicObject_base:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier for the *PolymorphicObject*
        type:
          type: string
          enum:
          - Task
          - CalendarEntry
          - MatterNote
          - ContactNote
          - Matter
          - Contact
          - User
          - CreditMemo
          - Payment
          - Document
          - Communication
          - Conversation
          - TextMessageConversation
          description: The type of the *PolymorphicObject*
        identifier:
          type: string
          description: A string to identify the *PolymorphicObject*
        secondary_identifier:
          type: string
          description: A secondary string to identify the *PolymorphicObject*
        tertiary_identifier:
          type: string
          description: A tertiary string to identify the *PolymorphicObject*
    Allocation_Show:
      type: object
      required:
      - data
      properties:
        data:
          $ref: '#/components/schemas/Allocation'
    Error:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
x-tagGroups:
- name: Api
  tags:
  - Custom Actions
  - Webhooks
- name: Activities
  tags:
  - Activities
  - Activity Descriptions
  - Activity Rates
  - Expense Categories
  - Timers
  - Utbms Codes
  - Utbms Sets
- name: Accounting
  tags:
  - Bank Accounts
  - Bank Transactions
  - Bank Transfers
- name: Billing
  tags:
  - Bills
  - Billable Clients
  - Billable Matters
  - Bill Themes
  - Interest Charges
  - Line Items
  - Outstanding Client Balances
- name: Calendars
  tags:
  - Calendars
  - Calendar Entries
  - Calendar Entry Event Types
  - Calendar Visibilities
  - Reminders
- name: Clio Payments
  tags:
  - Clio Payments Links
  - Clio Payments Payments
- name: Communications
  tags:
  - Communications
  - Conversations
  - Conversation Messages
- name: Contacts
  tags:
  - Contacts
  - Email Addresses
  - Phone Numbers
  - Notes
  - Log Entries
- name: Court Rules
  tags:
  - Jurisdictions To Triggers
  - Jurisdictions
  - Matter Dockets
  - Service Types
- name: Custom Fields
  tags:
  - Custom Fields
  - Custom Field Sets
- name: Documents
  tags:
  - Documents
  - Document Versions
  - Folders
  - Document Archives
  - Document Automations
  - Document Categories
  - Document Templates
  - Comments
- name: In-app Notifications
  tags:
  - My Events
  - Event Metrics
- name: Matters
  tags:
  - Matters
  - Relationships
  - Clients
  - Related Contacts
  - Matter Contacts
  - Notes
  - Practice Areas
  - Log Entries
  - Matter Stages
  - Medical Records Details
  - Medical Records
  - Medical Bills
  - Damages
- name: Payments
  tags:
  - Allocations
  - Credit Memos
- name: Reporting
  tags:
  - Reports
  - Report Presets
  - Report Schedules
- name: Settings
  tags:
  - Text Snippets
  - Billing Settings
  - Currencies
  - Tax Rate Configurations
- name: Tasks
  tags:
  - Tasks
  - Task Templates
  - Task Template Lists
  - Task Types
- name: Trust
  tags:
  - Trust Line Items
  - Trust Requests
- name: Users
  tags:
  - Users
  - Groups
- name: Legal Aid US
  tags:
  - Grants
  - Grant Funding Sources
- name: Legal Aid England & Wales
  tags:
  - Civil Controlled Rates
  - Civil Certificated Rates
  - Criminal Controlled Rates
  - Expense Categories