# List all approvals with filtering and pagination

> 🔒 **Private label — [contact sales](mailto:sales@boyahq.com).** Requires a private-label entitlement on your API client.

List all approvals with filtering and pagination

Endpoint: GET /approvals/all
Version: 2.0.0
Security: oauth2ClientCredentials

## Query parameters:

  - `status` (string)
    Approval status (PENDING, APPROVED, REJECTED, CANCELLED, DRAFT)

  - `page` (number)
    Page number for pagination

  - `limit` (number)
    Number of items per page

  - `action_type` (string)
    Filter by approval action type (e.g., PAYOUT, INVOICE, SUBSCRIPTION_REQUEST)

  - `from` (string)
    Start date filter (ISO format)

  - `to` (string)
    End date filter (ISO format)

## Header parameters:

  - `org_wallet_ref` (string)
    Organization wallet reference, defaults to "1" if not provided

  - `business_id` (string, required)
    Business identifier for the request

## Response 200 fields (application/json):

  - `docs` (array, required)

  - `docs._id` (string, required)
    Example: 698eae9e8e02c65ba2c4d0ea

  - `docs.id` (string, required)
    Example: 698eae9e8e02c65ba2c4d0ea

  - `docs.ref` (string, required)
    Example: SUB-84f6ecb209

  - `docs.narrative` (string, required)
    Example: Rob is requesting creation of a Lucidchart subscription

  - `docs.initiated_by` (string, required)
    Example: sgggbrfldhqcudjvhhwjpzcdcpcwws

  - `docs.business` (object, required)

  - `docs.business._id` (string, required)
    Example: 631b067a46830ae81217f860

  - `docs.business.business_id` (string, required)
    Example: zyatjjbfhwwrzzmpgrpsbkcpnldfge

  - `docs.business.name` (string, required)
    Example: Boya Limited

  - `docs.status` (number, required)
    0 = pending, 1 = approved, 2 = rejected
    Example: 0

  - `docs.is_batch` (number, required)
    0 = single, 1 = batch
    Example: 0

  - `docs.action_type` (number, required)
    Enum: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12

  - `docs.mandate` (number, required)
    Example: 1

  - `docs.participants` (array, required)

  - `docs.participants.employee` (string)
    Participant employee ObjectId

  - `docs.participants.id` (string)
    Employee identifier string

  - `docs.participants.status` (number)
    Participant status: 1=pending, 0=approved, 2=rejected

  - `docs.participants.reason` (string)
    Reason for decision

  - `docs.participants.approval_type` (number)
    Approval type: 1=mandatory, 0=optional

  - `docs.participants.requested_on` (string)
    Requested on timestamp

  - `docs.participants.actioned_on` (string)
    Actioned on timestamp

  - `docs.participants.level` (number)
    Approval hierarchy level

  - `docs.records` (array, required)

  - `docs.records._id` (string)
    Example: 698eae9e8e02c65ba2c4d0ea

  - `docs.records.ref` (string)
    Example: SUB-3e70cd6484

  - `docs.records.amount` (number)
    Example: 100

  - `docs.records.currency` (string)
    Example: USD

  - `docs.records.description` (string)
    Example: Mpesa transaction

  - `docs.records.notes` (string)
    Example: Rob is requesting creation of a subscription

  - `docs.records.receiver_name` (string)
    Example: Lucidchart

  - `docs.records.fees` (number)
    Example: 0

  - `docs.records.transaction_ref` (string)
    Example: D-UGUKVSPHMJGFE

  - `docs.records.team` (object)

  - `docs.records.team._id` (string, required)
    Example: 64ec5b57ffaef6ff2a2845b3

  - `docs.records.team.code` (string, required)
    Example: 0003

  - `docs.records.team.name` (string, required)
    Example: Tech

  - `docs.records.payment_instruction` (object)

  - `docs.records.payment_instruction._id` (string, required)
    Example: 6808e7c3b7a3aab7e41fbe7f

  - `docs.records.payment_instruction.channel` (string, required)
    Example: bank

  - `docs.records.payment_instruction.phone` (string)

  - `docs.records.payment_instruction.accno` (string)
    Example: 1400284063131

  - `docs.records.payment_instruction.bank` (string)
    Example: EQUITY BANK LTD

  - `docs.records.payment_instruction.bank_code` (string)
    Example: 68

  - `docs.records.payment_instruction.till` (string)

  - `docs.records.payment_instruction.business_no` (string)

  - `docs.records.status` (string)
    Example: pending

  - `docs.callback_url` (string)
    Example: https://api.boyahq.com/subscription/process-subscription-request

  - `docs.org_wallet_ref` (string, required)
    Example: 5

  - `docs.is_expenses_batch` (boolean, required)
    Example: false

  - `docs.auto_approve` (boolean, required)
    Example: false

  - `docs.isPolicyrequest` (boolean, required)
    Example: false

  - `docs.budget` (object)

  - `docs.initiated_on` (string, required)
    Example: 2026-02-13T04:54:54.492Z

  - `docs.createdAt` (string, required)
    Example: 2026-02-13T04:54:54.493Z

  - `docs.updatedAt` (string, required)
    Example: 2026-02-13T04:55:35.967Z

  - `docs.attachments` (array)

  - `docs.events` (array)

  - `docs.events._id` (string, required)
    Example: 698eaec7c3e3ddd24c2dfa47

  - `docs.events.recordType` (string, required)
    Example: APPROVAL

  - `docs.events.description` (string, required)
    Example: Approved request: #SUB-84f6ecb209

  - `docs.events.person` (string, required)
    Example: Rob

  - `docs.events.createdAt` (string, required)
    Example: 2026-02-13T04:55:35.850Z

  - `docs.request_status` (number, required)
    Example: 0

  - `docs.initiatedByName` (string, required)
    Example: Rob

  - `docs.business_id` (string, required)
    Example: zyatjjbfhwwrzzmpgrpsbkcpnldfge

  - `docs.email` (string)
    Example: rob@boyahq.com

  - `docs.phone` (string)
    Example: +254710702289

  - `docs.requested_on` (string, required)
    Example: 2026-02-13T14:26:47Z

  - `docs.updated_on` (string, required)
    Example: 2026-02-13T07:55:35Z

  - `page` (number, required)
    Example: 1

  - `limit` (number, required)
    Example: 10