List customers
GET /customers - Page through your partner-scoped customer (identity) records.
0Gate is the primary public integration path for hosted payment, ramp, and swap experiences. Keep secret-key operations on your server and hand only browser-safe values to the widget.
List your customer (identity) records, most-recent first, with cursor pagination. Filter by external_id or email to resolve a single record without storing the 0Bit id. This is a standard CRM-style list read; deleted customers are excluded.
Endpoint
| Field | Value |
|---|---|
| Method | GET |
| Path | /v1/customers |
| Area | Customers |
| Operation id | listCustomers |
| Auth boundary | Secret key from your server. |
Use it for
Page through your customers for an internal admin view, or resolve one customer by your own reference with ?external_id=… (or ?email=…). Both filters are exact-match.
Production rules
- Keep secret keys on your server. This endpoint requires an
sk_*key. - Page with
starting_after— pass theidof the last item from the previous page. Do not assume unbounded list reads; respecthas_more. - Soft-deleted customers are never returned.
- Treat examples and placeholder ids as fake data only.
Query parameters
| Field | Required | Type | Use it for |
|---|---|---|---|
limit | No | integer | Page size, 1–100, default 10. |
starting_after | No | string | A customer id; returns the page after it. Use the last id from the previous page. |
external_id | No | string | Exact-match filter on your own reference. |
email | No | string | Exact-match filter on the contact email. |
Response
Returns 200 with a cursor-paginated list.
| Field | Type | Use it for |
|---|---|---|
object | string | Always list. |
data | array | Array of customer objects, most-recent first. |
has_more | boolean | true when more records exist past this page — fetch the next with starting_after. |
url | string | The list resource path, /v1/customers. |
Examples
curl "https://gate-api.0bit.app/v1/customers?limit=10" \
-H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"curl "https://gate-api.0bit.app/v1/customers?external_id=user_42" \
-H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Returns a list of zero or one item — external_id is unique per partner.
{
"object": "list",
"data": [
{
"id": "67a1f3b9e4b0c10001234567",
"object": "customer",
"partner_id": "ptnr_test_000000000001",
"mode": "test",
"livemode": false,
"external_id": "user_42",
"email": "jordan@example.com",
"phone": "+447700900000",
"first_name": "Jordan",
"last_name": "Doe",
"country_code": "GB",
"kyc_status": "unverified",
"metadata": { "plan": "pro" },
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-01T00:00:00Z"
}
],
"has_more": false,
"url": "/v1/customers"
}To fetch the next page, call again with ?starting_after=67a1f3b9e4b0c10001234567 once has_more is true.
Errors
All errors use the unified envelope and carry an X-Request-Id response header. Branch on code/type/statusCode, not on the free-form message.
{
"type": "unauthorized",
"code": "unauthorized",
"message": "Missing or invalid secret key.",
"request_id": "req_test_000000000123",
"doc_url": null,
"statusCode": 401
}| Status | type | When it happens |
|---|---|---|
401 | unauthorized | Missing or invalid secret key. |
429 | rate_limited | Request throttled. Back off and retry. |
5xx | server_error | Transient server or upstream failure. Retry with bounded backoff. |
Public boundary
This reference covers partner-scoped endpoint behavior, authentication, idempotency, webhook verification, and support-safe records. Internal operations, administrative routes, and unsupported availability claims are outside the public API contract.