Skip to main content
GET
List customers

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]

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

created[lte]

Upper bound on created_at, inclusive.

updated[gte]

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

updated[lte]

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

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).

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.