> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Garnishments

> Returns a cursor-paginated list of garnishments for a company.

Returns a cursor-paginated list of garnishments. Use `start_at` from `meta.next` / `meta.previous` to page. `workerID` and `workerType` must be provided together when filtering by worker.


## OpenAPI

````yaml openapi/zeal-api.json get /garnishments
openapi: 3.1.0
info:
  title: zeal-api
  version: '1.0'
servers:
  - url: https://api.zeal.com
security:
  - sec0: []
paths:
  /garnishments:
    get:
      summary: Get Garnishments
      description: Returns a cursor-paginated list of garnishments for a company.
      operationId: list-garnishments
      parameters:
        - name: companyID
          in: query
          description: Company ID of employer
          required: true
          schema:
            type: string
        - name: workerID
          in: query
          required: false
          schema:
            type: string
          description: Filter by worker ID. Must be provided together with workerType.
        - name: workerType
          in: query
          required: false
          schema:
            type: string
            enum:
              - employee
              - contractor
          description: Filter by worker type. Must be provided together with workerID.
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - active
              - satisfied
              - modified
              - vacated
              - canceled
          description: Filter by garnishment status
        - name: garnishment_type
          in: query
          required: false
          schema:
            type: string
          description: >-
            Filter by garnishment type. Accepts a single value or a
            comma-separated list.
        - name: external_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by external ID
        - name: q
          in: query
          required: false
          schema:
            type: string
          description: >-
            Free-text search across worker name, worker ID, garnishment ID, case
            ID, order number, and agency
        - name: effective_start_date_from
          in: query
          required: false
          schema:
            type: string
          description: Inclusive lower bound for effective_start_date (YYYY-MM-DD)
        - name: effective_start_date_to
          in: query
          required: false
          schema:
            type: string
          description: Inclusive upper bound for effective_start_date (YYYY-MM-DD)
        - name: effective_end_date_from
          in: query
          required: false
          schema:
            type: string
          description: Inclusive lower bound for effective_end_date (YYYY-MM-DD)
        - name: effective_end_date_to
          in: query
          required: false
          schema:
            type: string
          description: Inclusive upper bound for effective_end_date (YYYY-MM-DD)
        - name: sort_by
          in: query
          required: false
          schema:
            type: string
            enum:
              - priority
              - created_at
              - total_amount_owed
              - effective_start_date
              - effective_end_date
          description: Field to sort by
        - name: sort_direction
          in: query
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
          description: Sort direction
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          description: Page size (1-100). Defaults to 25.
        - name: start_at
          in: query
          required: false
          schema:
            type: string
          description: Cursor for pagination
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value:
                    success: true
                    data:
                      - garnishmentID: 3cab1c18d38a45e7a688aceeb4fcfcaa
                        companyID: 1eeec343485723ee58afef12
                        workerID: 674759a85785745748e3847a
                        workerType: contractor
                        garnishment_type: creditor
                        priority: 50
                        total_amount_owed: 500
                        total_amount_withheld: 0
                        status: active
                        effective_start_date: '2025-01-01'
                        agency_name: Acme Agency
                        agency_address: 123 Court St
                        cap_percentage: 25
                        case_id: CASE-1
                        order_number: ORD-1
                        created_at: '2025-01-01T00:00:00.000Z'
                        updated_at: '2025-01-01T00:00:00.000Z'
                    meta:
                      next: null
                      previous: null
                      totalCount: 1
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                    default: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        garnishmentID:
                          type: string
                          description: Unique identifier for this garnishment
                          example: 3cab1c18d38a45e7a688aceeb4fcfcaa
                        companyID:
                          type: string
                          description: Company ID of employer
                          example: 1eeec343485723ee58afef12
                        workerID:
                          type: string
                          description: >-
                            Employee or contractor ID this garnishment applies
                            to
                          example: 674759a85785745748e3847a
                        workerType:
                          type: string
                          enum:
                            - employee
                            - contractor
                          description: Whether the worker is an employee or contractor
                          example: contractor
                        garnishment_type:
                          type: string
                          enum:
                            - child_support
                            - federal_tax_levy
                            - state_tax_levy
                            - creditor
                            - student_loan
                            - other
                          description: Type of garnishment order
                          example: creditor
                        priority:
                          type: integer
                          description: >-
                            Withholding priority. Lower numbers are withheld
                            first. When omitted on create, Zeal applies a
                            type-based default.
                          example: 50
                        total_amount_owed:
                          type: number
                          description: >-
                            Total balance owed in dollars. Omit for open-ended /
                            forever orders.
                          example: 500
                        total_amount_withheld:
                          type: number
                          description: Total amount withheld to date in dollars
                          example: 0
                        status:
                          type: string
                          enum:
                            - active
                            - satisfied
                            - modified
                            - vacated
                            - canceled
                          description: Lifecycle status of the garnishment
                          example: active
                        effective_start_date:
                          type: string
                          description: ISO date (YYYY-MM-DD) when withholding begins
                          example: '2025-01-01'
                        effective_end_date:
                          type: string
                          description: >-
                            ISO date (YYYY-MM-DD) when withholding ends. Omit
                            for open-ended orders.
                          example: '2025-12-31'
                        agency_name:
                          type: string
                          description: Name of the collecting agency
                          example: Acme Agency
                        agency_address:
                          type: string
                          description: Address of the collecting agency
                          example: 123 Court St
                        cap_amount:
                          type: number
                          description: >-
                            Per-paycheck maximum withhold amount in dollars. At
                            least one of cap_amount or cap_percentage is
                            required on create.
                          example: 150
                        cap_percentage:
                          type: number
                          description: >-
                            Per-paycheck maximum withhold percentage of
                            disposable earnings (0-100). At least one of
                            cap_amount or cap_percentage is required on create.
                          example: 25
                        garnishment_state:
                          type: string
                          description: US state code (2-letter) associated with the order
                          example: CA
                        case_id:
                          type: string
                          description: Court/agency case identifier
                          example: CASE-1
                        order_number:
                          type: string
                          description: Court/agency order number
                          example: ORD-1
                        custom_name:
                          type: string
                          description: Optional display name for this garnishment
                          example: Acme creditor
                        external_id:
                          type: string
                          description: Optional external identifier for your own systems
                          example: ext-create-1
                        previous_garnishmentID:
                          type: string
                          description: >-
                            ID of the garnishment this record supersedes.
                            Present when this garnishment was created via a
                            modify (status: modified) transition; omitted
                            otherwise.
                          example: 2bab1c18d38a45e7a688aceeb4fcfcbb
                        canceled_reason:
                          type: string
                          description: Reason provided when status is canceled
                        satisfied_at:
                          type: string
                          description: >-
                            ISO timestamp when the garnishment was fully
                            satisfied
                        created_at:
                          type: string
                          description: ISO timestamp when the garnishment was created
                          example: '2025-01-01T00:00:00.000Z'
                        updated_at:
                          type: string
                          description: ISO timestamp when the garnishment was last updated
                          example: '2025-01-01T00:00:00.000Z'
                        withholding_schedule:
                          $ref: '#/components/schemas/WithholdingSchedule'
                  meta:
                    type: object
                    properties:
                      next:
                        type: string
                        nullable: true
                        description: URL for the next page, or null
                      previous:
                        type: string
                        nullable: true
                        description: URL for the previous page, or null
                      totalCount:
                        type: integer
                        description: Total number of matching garnishments
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value:
                    success: false
                    errors:
                      - message: workerID and workerType must be provided together.
                        code: 0
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                        code:
                          type: integer
                          example: 0
      deprecated: false
components:
  schemas:
    WithholdingSchedule:
      type: array
      minItems: 1
      description: >-
        Advanced withholding schedule (mutually exclusive with cap_amount /
        cap_percentage). Employee-only: contractors have no pay frequency, so a
        schedule on a contractor is rejected — use cap_amount / cap_percentage
        instead. Use for fixed amounts per pay frequency or disposable-earnings
        brackets. At least one of cap_amount, cap_percentage, or
        withholding_schedule is required. Money fields are in dollars. When
        present, every frequency branch must tile disposable earnings from $0.00
        to infinity with no gaps or overlaps: the first bracket min must be 0,
        each next min must be exactly $0.01 after the previous max, and the last
        bracket max must be null. At least one bracket in the schedule must
        withhold (not all exempt).
      items:
        type: object
        required:
          - frequency
          - brackets
        properties:
          frequency:
            type: string
            enum:
              - daily
              - weekly
              - biweekly
              - semimonthly
              - monthly
              - quarterly
            description: Pay frequency this branch applies to
          brackets:
            type: array
            minItems: 1
            description: >-
              Disposable-earnings brackets for this frequency. Must tile $0.00
              to infinity with no gaps or overlaps (first min is 0; each next
              min is previous max + 0.01; last max is null).
            items:
              type: object
              required:
                - min
                - max
                - action
              properties:
                min:
                  type: number
                  minimum: 0
                  description: >-
                    Inclusive lower bound of disposable earnings in dollars. The
                    first bracket in a branch must start at 0.
                max:
                  type: number
                  minimum: 0
                  nullable: true
                  description: >-
                    Inclusive upper bound of disposable earnings in dollars.
                    Only the last bracket may be null (open-ended); earlier
                    brackets require a max.
                action:
                  oneOf:
                    - type: object
                      required:
                        - kind
                      properties:
                        kind:
                          type: string
                          enum:
                            - exempt
                          description: Do not withhold in this band
                    - type: object
                      required:
                        - kind
                        - amount
                      properties:
                        kind:
                          type: string
                          enum:
                            - amount
                        amount:
                          type: number
                          minimum: 0
                          description: Fixed dollar amount to withhold
                    - type: object
                      required:
                        - kind
                        - floor
                      properties:
                        kind:
                          type: string
                          enum:
                            - excess_over_floor
                        floor:
                          type: number
                          minimum: 0
                          description: >-
                            Withhold disposable earnings above this floor
                            (dollars)
                    - type: object
                      required:
                        - kind
                        - percentage
                      properties:
                        kind:
                          type: string
                          enum:
                            - percentage
                        percentage:
                          type: number
                          minimum: 0
                          maximum: 100
                          description: >-
                            Percentage of disposable earnings to withhold
                            (0-100)
                  description: How to compute the withhold amount for this bracket
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: Authorization
      x-bearer-format: bearer

````