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

# List payrolls

> List a company's worker payrolls, newest first. Filter by `external_id` to
find a payroll without storing the Bitwage `payroll_id`. Vendor payrolls
and balance-account withdrawals are not included. Requires the
`payroll.read` permission group.




## OpenAPI

````yaml /api-reference/openapi.yaml get /api/company/{company_id}/payrolls
openapi: 3.1.0
info:
  title: Bitwage Partner API
  version: '2.0'
  description: |
    The Bitwage Partner API allows you to integrate Bitwage payroll and payment
    functionality into your own application. You can manage users, companies,
    distributions, payroll, and more.
  contact:
    name: Development Team
    email: developers@bitwage.com
    url: https://www.bitwage.com/support
  license:
    name: Copyright Bitwage, Inc. All rights reserved.
    url: https://www.bitwage.com/policies/#terms
servers:
  - url: https://api.sandbox.bitwage.com
    description: Sandbox
  - url: https://api2.bitwage.com
    description: Production
security:
  - api_key: []
  - oauth: []
tags:
  - name: Authorization
    description: OAuth 2.0 authorization code flow endpoints.
  - name: Users
    description: Create and manage user accounts.
  - name: User Documents
    description: Upload and manage user KYC documents.
  - name: User Payers
    description: Manage external payers (employers/clients) for users.
  - name: User Distributions
    description: Manage payment distribution destinations for users.
  - name: User Funding
    description: Manage funding (virtual bank) accounts for users.
  - name: Companies
    description: Create and manage company accounts, UBO, KYC/KYB.
  - name: Company Workers
    description: Invite and manage company workers.
  - name: Company Recipients
    description: Manage company recipients (workers and vendors).
  - name: Company Payroll
    description: Create and manage payrolls.
  - name: Merchant
    description: Crypto pay-in and BTC checkout endpoints.
  - name: Wallets
    description: Request and view wallets for payroll funding.
  - name: Webhooks
    description: Webhook event schemas sent by Bitwage.
paths:
  /api/company/{company_id}/payrolls:
    get:
      tags:
        - Company Payroll
      summary: List payrolls
      description: >
        List a company's worker payrolls, newest first. Filter by `external_id`
        to

        find a payroll without storing the Bitwage `payroll_id`. Vendor payrolls

        and balance-account withdrawals are not included. Requires the

        `payroll.read` permission group.
      operationId: listPayrolls
      parameters:
        - $ref: '#/components/parameters/CompanyIdPath'
        - name: external_id
          in: query
          required: false
          schema:
            type: string
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: Payrolls returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PartnerPayroll'
                  meta:
                    $ref: '#/components/schemas/Pagination'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationFailed'
components:
  parameters:
    CompanyIdPath:
      name: company_id
      in: path
      required: true
      schema:
        type: string
      description: Company ID.
  schemas:
    PartnerPayroll:
      type: object
      properties:
        payroll_id:
          type: string
        company_id:
          type: string
        external_id:
          type: string
          nullable: true
        currency:
          type: string
          nullable: true
        status:
          $ref: '#/components/schemas/PayrollStatus'
        created:
          type: string
          format: date-time
          nullable: true
        datereceived:
          type: string
          format: date-time
          nullable: true
        dateapproved:
          type: string
          format: date-time
          nullable: true
        datereleased:
          type: string
          format: date-time
          nullable: true
        datefulfilled:
          type: string
          format: date-time
          nullable: true
        datecanceled:
          type: string
          format: date-time
          nullable: true
        invoice_ids:
          type: array
          nullable: true
          description: Claim IDs linked to the payroll, or null.
          items:
            type: string
        payments:
          type: array
          description: |
            Same object as `payment` on `user.payment_status_update`, not the
            summary sent on `company.payroll_status`.
          items:
            $ref: '#/components/schemas/Payment'
    Pagination:
      type: object
      properties:
        page:
          type: integer
        total:
          type: integer
        pages:
          type: integer
        has_prev:
          type: boolean
        has_next:
          type: boolean
        prev_num:
          type: integer
        next_num:
          type: integer
        per_page:
          type: integer
    PayrollStatus:
      type: string
      enum:
        - created
        - received
        - processing
        - fulfilled
        - canceled
      description: >
        Payroll status.


        - `created`: the payroll exists and is waiting for funds.

        - `received`: Bitwage received the funding.

        - `processing`: the payroll is approved or released and payments are in
        flight.

        - `fulfilled`: all payments are complete.

        - `canceled`: the payroll was canceled or deleted.
    Payment:
      type: object
      properties:
        subpayroll_id:
          type: string
        received:
          type: boolean
        received_at:
          type: string
          format: date-time
          nullable: true
        released:
          type: boolean
        released_at:
          type: string
          format: date-time
          nullable: true
        fulfilled:
          type: boolean
        fulfilled_at:
          type: string
          format: date-time
          nullable: true
        receiver_user_id:
          type: string
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/PaymentAllocation'
    Error:
      type: object
      description: |
        Error body returned by most endpoints. Branch on `code`. See the
        [Errors guide](/guides/errors) for the full list of codes.
      required:
        - request_id
        - message
      properties:
        request_id:
          type: string
          description: Include this when you contact support.
        message:
          type: string
          description: English fallback text. Can change.
        code:
          type: string
          description: Stable kebab-case error code. Omitted when there is none.
          example: recipient-worker-email-already-exists
        data:
          type: object
          description: Extra fields. Most `400` errors include `retryable`.
          properties:
            retryable:
              type: boolean
          additionalProperties: true
    ValidationErrorBody:
      type: object
      required:
        - request_id
        - message
        - schema
      properties:
        request_id:
          type: string
        message:
          type: string
          description: The first error in `schema`.
        code:
          type: string
        schema:
          type: object
          description: Validation errors keyed by field name. Nested fields are nested.
          additionalProperties: true
          example:
            payments:
              - Total amount of payroll must be greater than 10
    PaymentAllocation:
      type: object
      properties:
        input_currency:
          type: string
        output_currency:
          type: string
        volume_input_in_input_currency:
          type: number
          format: double
        volume_output_in_output_currency:
          type: number
          format: double
        fees:
          type: number
          format: double
        spread:
          type: number
          format: double
        tx_hash:
          type: string
  responses:
    Forbidden:
      description: |
        Authentication failed, the partner lacks the required permission group
        (`partner-permission-denied`), or the resource is not yours
        (`partner-company-not-found`, `invalid-api-key`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationFailed:
      description: The request failed validation. Field errors are under `schema`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorBody'
  securitySchemes:
    api_key:
      type: http
      scheme: basic
      description: |
        API key authentication. Include your access token as:
        `Authorization: Basic <ACCESS_TOKEN>`
    oauth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.bitwage.com/authorize
          tokenUrl: https://api2.bitwage.com/oauth2/token
          scopes:
            c_company_detail: Company Detail
            c_company_worker_list: Company Worker List
            c_company_worker_invitations_list: Company Worker Invitation List
            c_company_workers_invite: Company Workers Invite
            c_company_workers_pay: Company Workers Pay
            u_user_create: User Create
            u_user_update: User Update
            u_user_update_doc: User Update Document
            u_user_payer_create: User Payer Create
            u_user_payer_update: User Payer Update
            u_user_invoice_create: User Invoice Create
            u_user_invoice_delete: User Invoice Delete
            u_user_detail: User Detail
            u_user_document_list: User Document List
            u_user_payer_detail: User Payer Detail
            u_user_payer_list: User Payer List
            u_user_bank_details: User Bank Details
            u_user_invoice_detail: User Invoice Detail
            u_user_invoice_list: User Invoice List
            u_user_distribution_detail: User Distribution Detail
            u_user_distribution_list: User Distribution List
            u_user_distribution_create: User Distribution Create
            u_user_distribution_update: User Distribution Update
            u_user_kyc_initiate: User Initiate KYC

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.