> ## Documentation Index > Fetch the complete documentation index at: https://docs.keebai.com/llms.txt > Use this file to discover all available pages before exploring further. # GET /v1/loyalty/memberships > List memberships across your company, filterable by program, customer, phone, name, or status. Lists memberships. This is how you get from something you know about a customer — their id in your system, or their phone number — to the `membership_id` that every other loyalty write needs. ## Endpoint ``` GET https://api.keebai.com/v1/loyalty/memberships ``` ## Required scope `loyalty:read` ## Headers | Header | Required | Value | | --------------- | -------- | ------------------------ | | `Authorization` | Yes | `Bearer kbai_pk_` | ## Query parameters | Parameter | Type | Default | Description | | ------------- | --------- | ------- | --------------------------------------------------------- | | `program_id` | `string` | — | Only memberships of this program. | | `customer_id` | `string` | — | Exact match on the identifier you supplied at enrollment. | | `phone` | `string` | — | Matches on a digit subsequence — see the notes. | | `name` | `string` | — | Partial, case-insensitive match on the customer name. | | `status` | `string` | — | `active`, `suspended`, or `revoked`. | | `limit` | `integer` | `50` | Records per page, 1–200. | | `offset` | `integer` | `0` | Records to skip. | ## Example request ```bash curl theme={null} curl "https://api.keebai.com/v1/loyalty/memberships?phone=912345678" \ -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ``` ```js JavaScript theme={null} const params = new URLSearchParams({ customer_id: "pos-8842" }); const response = await fetch( `https://api.keebai.com/v1/loyalty/memberships?${params}`, { headers: { Authorization: `Bearer ${process.env.KEEBAI_API_TOKEN}` } }, ); const { data } = await response.json(); const membershipId = data[0]?._id; ``` ```python Python theme={null} import os, requests resp = requests.get( "https://api.keebai.com/v1/loyalty/memberships", headers={"Authorization": f"Bearer {os.environ['KEEBAI_API_TOKEN']}"}, params={"phone": "912345678"}, timeout=10, ) resp.raise_for_status() memberships = resp.json()["data"] ``` ## Response ### 200 OK ```json theme={null} { "data": [ { "_id": "6650aaaa1111bbbb2222cccc", "program_id": "6650a1b2c3d4e5f6a7b8c9d0", "customer": { "id": "pos-8842", "name": "Camila Rojas", "phone": "+56912345678", "email": "camila@example.com" }, "serial_number": "c0e9561b-4c2f-4f0a-9c1e-8b7d6a5f4e3d", "balance_points": 1240, "stamps_count": 0, "tier": "silver", "status": "active", "enrolled_at": "2026-03-01T00:00:00.000Z", "created_at": "2026-03-01T00:00:00.000Z", "updated_at": "2026-06-18T11:42:03.550Z" } ], "total": 1, "limit": 50, "offset": 0 } ``` ### 401 Unauthorized Missing, invalid, revoked, or expired token. ### 403 Forbidden The token does not have the `loyalty:read` scope. ### 502 Bad Gateway The loyalty service is unreachable. ## Operational notes * **Phone search does not need normalising.** The lookup matches on a subsequence of digits, so `912345678` finds a membership stored as `+56 9 1234 5678`. Strip or keep the country code as you like. * **A customer can hold one membership per program.** Searching by `customer_id` alone across several programs returns one row per program they belong to; add `program_id` to narrow it. * **`balance_points` may read `0` on a program with point expiry** even when the ledger shows movements. That is the display value, not a correction — see the [overview](/dev/loyalty/overview#balances-are-a-projection). * **`customer` may be absent** on memberships created before an identifier was required, or through the portal's bulk import without a matching row. Treat it as optional when reading. * **Reads span the whole company**, across every project. ## OpenAPI ````yaml GET /v1/loyalty/memberships openapi: 3.0.0 info: title: Keebai Public API description: Superficie pública REST autenticada con Personal Access Tokens (PAT). version: 1.0.0 contact: {} servers: - url: https://api.keebai.com description: Production security: [] tags: [] paths: /v1/loyalty/memberships: get: tags: - loyalty summary: Listar membresías description: >- Devuelve las membresías de la company, filtrables por programa, cliente, teléfono, nombre o estado. El saldo de puntos puede leerse 0 si el programa vence puntos y ya pasó el plazo. operationId: PublicLoyaltyController_listMemberships parameters: - name: limit required: false in: query schema: minimum: 1 maximum: 200 default: 50 type: number - name: offset required: false in: query schema: minimum: 0 default: 0 type: number - name: program_id required: false in: query description: ObjectId del programa schema: type: string - name: customer_id required: false in: query description: Identificador del cliente elegido por el integrador al inscribir schema: type: string - name: phone required: false in: query description: >- Teléfono del cliente. Busca por subsecuencia de dígitos, así que +56 9 1234 5678 matchea con 912345678 schema: type: string - name: name required: false in: query description: Búsqueda parcial por nombre schema: type: string - name: status required: false in: query schema: type: string enum: - active - suspended - revoked responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/PublicMembershipListResponseDto' security: - PAT: [] components: schemas: PublicMembershipListResponseDto: type: object properties: total: type: number limit: type: number offset: type: number data: type: array items: $ref: '#/components/schemas/PublicMembershipDto' required: - total - limit - offset - data PublicMembershipDto: type: object properties: _id: type: string program_id: type: string customer: $ref: '#/components/schemas/PublicMembershipCustomerViewDto' serial_number: type: string description: >- Identificador del pase en Apple y Google. Es lo que codifica el código de barras por defecto balance_points: type: number description: >- Saldo de puntos. Si el programa vence puntos y ya pasó el plazo, se lee 0 sin que el ledger cambie example: 1240 stamps_count: type: number example: 7 tier: type: string description: Clave del nivel alcanzado. Vacío si el programa no es de tiers example: gold status: type: string enum: - active - suspended - revoked enrolled_at: type: string created_at: type: string updated_at: type: string required: - _id - program_id - serial_number - balance_points - stamps_count - tier - status - enrolled_at - created_at - updated_at PublicMembershipCustomerViewDto: type: object properties: id: type: string example: crm-8842 name: type: string example: Camila Rojas phone: type: string example: '+56912345678' email: type: string example: camila@ejemplo.cl required: - id securitySchemes: PAT: scheme: bearer bearerFormat: kbai_pk_ type: http description: >- Personal Access Token con prefijo `kbai_pk_`. Generar desde el portal con permiso `developer.manage_tokens`. ````