List customers

Returns a cursor-paginated list of customers in the calling organization, sorted by created_at descending (newest first).

Filtering

Filters combine with AND. Two categories:

• Lookup filters (rate-limited more strictly - used to find a specific record): email, phone, external_id
• Scan filters (standard rate limit - used to iterate a subset): card_id, location_id, status, device, created[gte|lte], updated[gte|lte]
• Serial number lookup (standard rate limit - returns at most one customer): serial_number, the value in the customer’s wallet pass QR code or barcode, or the number on a physical card. Send it exactly as you have it; it is not the customer id.

Lookup filters are stricter because they can be used to enumerate the organization’s customers.

See Pagination for the cursor pattern and Rate Limits for the per-key ceilings.

Date filters

created[gte|lte] and updated[gte|lte] accept ISO-8601 timestamps (with timezone) or Unix seconds - either format works interchangeably.

GET /v1/customers

List customers

cURL

curl --request GET \
  --url https://api.vexioncards.one/v1/customers \
  --header 'Authorization: Bearer <token>'

200

First page

{ "object": "list", "url": "/v1/customers", "has_more": true, "data": [ { "id": "cus_b8c2e0a4f59d4a73a1e9", "object": "customer", "external_id": null, "email": "[e-mail]", "phone": null, "first_name": null, "last_name": null, "language": "sk", "gdpr_redacted_at": null, "card_id": "crd_sophcrprtvpmmnwxah2lomnkee", "card_type": "stamp", "card": { "card_id": "crd_sophcrprtvpmmnwxah2lomnkee", "card_type": "stamp", "status": "installed", "total_visits": 0, "first_transaction_at": null, "last_transaction_at": null, "created_at": 1782604800, "updated_at": 1782604800, "remaining_stamps": 10, "total_stamps": 10, "stamps_pending": 0 }, "status": "not_installed", "device": null, "installed_at": null, "claim_url": "https://vexioncards.one/card/add/2ea6adef9d5ba7a4d358ad46", "custom": {}, "metadata": {}, "referral_stats": null, "created_at": 1782604800, "updated_at": 1782604800, "last_visited_at": null, "last_visited_location_id": null, "deleted_at": null }, { "id": "cus_yovo5wk634htfojgkzdpmzvu5a", "object": "customer", "external_id": "crm-customer-7421", "email": "[e-mail]", "first_name": "Tomáš", "last_name": "Varga", "language": "sk", "gdpr_redacted_at": null, "card_id": "crd_2hh2fekk5zazfyyvian4uhepyq", "card_type": "reward", "card": { "card_id": "crd_2hh2fekk5zazfyyvian4uhepyq", "card_type": "reward", "status": "installed", "total_visits": 12, "first_transaction_at": 1779580800, "last_transaction_at": 1782345600, "created_at": 1779494400, "updated_at": 1782345600, "points": 480, "points_pending": 0, "reward_tier": { "tier_name": "Silver", "earn_multiplier": 1.5, "tier_effective_date": 1781481600, "previous_tier_name": "Bronze" } }, "status": "installed", "device": "apple_wallet", "installed_at": 1779494400, "claim_url": "https://vexioncards.one/card/add/afbd9cbc8b9ab72f43bf6ffc", "custom": {}, "metadata": {}, "referral_stats": null, "created_at": 1779494400, "updated_at": 1782345600, "last_visited_at": 1782345600, "last_visited_location_id": null, "deleted_at": null } ] }

Authorizations

Authorization · string · header · required

Your secret API key as a Bearer token: Authorization: Bearer vxn_sk_.... Keys are created and scoped in the dashboard - see Authentication.

Query Parameters

card_id · string

Restrict to customers enrolled on this card template.

Pattern: ^crd_[A-Za-z0-9]+$

email · string<email>

Exact-match lookup. Rate-limited (5/sec/org). Case-insensitive.

Required string length: 3 - 254

phone · string

Exact-match lookup in E.164 form. Rate-limited (5/sec/org).

Required string length: 4 - 20

Pattern: ^\+[1-9]\d{1,14}$

external_id · string

Exact-match lookup against your partner-side reference. Highest-priority dedupe field on POST.

Required string length: 1 - 191

serial_number · string

Look up a customer by serial number: the value encoded in their wallet pass QR code or barcode and printed on physical cards (see Customer.serial_number). Send it exactly as you have it, for example as scanned, typed or stored from a webhook. Accepts the platform-assigned serial (a 24-character hex value), a referral-link QR (https://www.vexioncards.one/ref/<serial>), a gift-card QR (https://www.vexioncards.one/gfc/<serial>, returns the gift-card customer) and a merchant-assigned custom serial (serial_number_locked: true). Returns at most one customer; an unknown value returns an empty list, not an error. Standard rate limit (not the 5/sec lookup tier).

Required string length: 1 - 256

created[gte] · integer string<date-time>

Lower bound on created_at, inclusive. ISO-8601 datetime with timezone, or unix seconds.

created[lte] · integer string<date-time>

Upper bound on created_at, inclusive.

updated[gte] · integer string<date-time>

Lower bound on updated_at, inclusive. Use this for delta-sync loops driven by customer.updated webhooks.

updated[lte] · integer string<date-time>

Upper bound on updated_at, inclusive.

limit · integer · default: 25

Page size, 1-100. Default 25. Server may return fewer if the page reaches the end.

Required range: 1 <= x <= 100

starting_after · string

Cursor: customer id from the previous page. Returns customers created strictly BEFORE this one. Mutually exclusive with ending_before. Numeric offset or page parameters are not supported; cursors are the only supported paging mechanism.

Pattern: ^cus_[A-Za-z0-9]+$

ending_before · string

Cursor: customer id from the previous page. Returns customers created strictly AFTER this one (reverse pagination). Mutually exclusive with starting_after.

Pattern: ^cus_[A-Za-z0-9]+$

location_id · string

Filter by signup_location_id (where the customer first joined).

Pattern: ^loc_[A-Za-z0-9]+$

status · enum<string>

Filter by the customer's card pass-install status. Matches the status field on the customer's card object in the response.

Available options: installed, not_installed, deleted, disputed

device · enum<string>

Filter by which wallet the customer's pass is installed on. Matches the device field on the customer's card object in the response.

Available options: apple_wallet, google_wallet

Response

200

application/json

The customer object.

Cursor-paginated list of Customer objects.

object · enum<string> · required

Always 'list'. Type discriminator.

Available options: list

data · object[] · required

Array of Customer objects on this page. Up to limit items (default 25, max 100).

Show child attributes

has_more · boolean · required

True if more results exist beyond this page.

next_cursor · string | null

Cursor for the next page in the direction you are already paging, or null when this page ends the collection. has_more: true always comes with a non-null next_cursor.

Feed it back to the SAME parameter you used: starting_after when paging forward (the default), or ending_before when paging backward. Treat it as opaque and do not parse it.

You no longer need to take the last object's id yourself. That still works and is unchanged, but deriving the cursor from the page put the burden of knowing the sort direction on you, and it broke silently on any endpoint whose cursor is not the object id.

Example:

"cus_iofv5j4hn6bphinmmyat27tc5y"

url · string

Stable collection URL.