---
title: "Get All Consumers"
method: GET
path: "/api/v2/consumers"
tags: ["Consumers"]
---

# Get All Consumers

`GET /api/v2/consumers`

List consumers with pagination, sorting, and optional filters.

**Query filters** (all optional; combine as needed):
- `search_term` — partial match on name, email, phone, alias, external_id,
  associated entity name, or associated entity field values

**External metadata filters** (optional, combine with other filters):
- Use any external metadata key you stored on create/update as a query parameter: `external_metadata.<key>=<value>`
- Exact match, case-sensitive. Multiple keys are ANDed.
- Example: if a consumer was created with `"external_metadata": {"segment": "enterprise", "tier": "gold"}`, filter with
  `?external_metadata.segment=enterprise&external_metadata.tier=gold`

**Pagination**: `page` (default 1), `limit` (default 10, max 100)

**Sorting**: `sort_field` (`name`, `created_at`, `email`, `phone_number`, `external_id`; default `created_at`),
`sort_direction` (`asc` or `desc`; default `desc`)

**Example**: `/api/v2/consumers?search_term=Acme&external_metadata.segment=enterprise&page=1&limit=20`

## Query parameters

- `page` integer — Page number, defaults to 1.
- `limit` integer — Size of a page, defaults to 10. Maximum is 100.
- `search_term` string, nullable — Free-text search (case-insensitive, partial match). Matches product name and description. Omit to skip text search. Example: `?search_term=premium`.
- `sort_field` string, nullable — Field to sort by, e.g., 'amount', 'scheduled_on'
- `sort_direction` string, nullable — Sorting direction ('asc' or 'desc')

## Response `200`

Successful Response

- ListResourceConsumerResponse
  - `data` ConsumerResponse[]
    - `id` string, uuid4 — Unique identifier (UUID) of the organization consumer
    - `name` string — Name of the consumer
    - `phone_number` string, phone, nullable — Phone number of the consumer
    - `email` string, email, nullable — Email address of the consumer
    - `external_id` string, nullable — External identifier for the consumer
    - `consumer` AppConsumerV2DtosConsumer
      - `id` string, uuid4, nullable — Unique identifier (UUID) of the consumer
      - `phone_number` string, phone, nullable — Phone number of the consumer
      - `preferred_language` 'AR' | 'EN'
    - `iban` string, nullable — IBAN (International Bank Account Number) of the consumer
    - `is_deleted` boolean — Whether the consumer has been deleted
    - `alias` string, nullable — Alias of the consumer
    - `created_at` string, date-time — Date and time when the consumer was created
    - `branch` Branch
      - `id` string, uuid4 — Unique identifier (UUID) of the branch
      - `name` string — Name of the branch
    - `comment` string, nullable — Additional comments or notes about the consumer
    - `communication_methods` ConsumerCommunicationMethod[] — Preferred communication methods for the consumer
    - `preferred_language` 'AR' | 'EN'
    - `consumer_type` 'INDIVIDUAL' | 'BUSINESS'
    - `address` AddressResponse — Address response model.
      - `address_line_1` string — Address line 1
      - `address_line_2` string, nullable — Address line 2
      - `city` string — City
      - `postal_code` string, nullable — Postal code
      - `country` string — Country
    - `vat_number` string, nullable — VAT number (optional for business type)
    - `commercial_registration` string, nullable — Commercial registration number (optional for business type)
    - `external_metadata` ExternalMetadataStorage
    - `beneficiaries` Beneficiary[] — List of beneficiaries
      - `id` string, uuid4 — Unique identifier (UUID) of the beneficiary
      - `name` string — Name of the beneficiary
      - `fields` object — Catalog field values for this associated entity
    - `last_invoice_activity` LastInvoiceActivity
      - `id` string, uuid4 — Unique identifier (UUID) of the invoice
      - `org_invoice_number` integer — Organization-specific invoice number
      - `subcription_id` string, uuid4, nullable — Unique identifier (UUID) of the subscription if applicable
  - `pagination` Pagination
    - `total_count` integer
    - `max_page` integer
    - `current_page` integer
    - `limit` integer
    - `has_next_page` boolean
    - `has_previous_page` boolean

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/streampay/apis/stream-app.md) · [All operations](https://skmtc.dev/streampay/apis/stream-app/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/streampay/stream-app/revisions/515eeea7d260/schema)