Documentation Index Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt
Use this file to discover all available pages before exploring further.
Use this endpoint to retrieve all customers associated with your SpherePay account. Results are returned in pages, and you can filter by customer status or type to narrow the list. Each item in the response includes the customer’s verification profile, so you can quickly identify which customers are ready for transfers.
Endpoint GET https://api.spherepay.co/v2/customer
Authentication All requests require a Bearer token in the Authorization header.
Authorization: Bearer <token>
Query parameters Page number to retrieve. Defaults to 1.
Number of customers to return per page. Defaults to 10.
Filter by verification status. Accepted values: incomplete, pending, approved, rejected.
Filter by customer type. Accepted values: individual, business.
-H "Authorization: Bearer $SPHEREPAY_API_KEY "
Response fields Array of customer objects for the current page. Unique customer identifier, prefixed with customer_.
Customer type: individual or business.
Registered email address.
Registered phone number in E.164 format.
First name (individual customers only).
Last name (individual customers only).
Verification profiles tracking KYC/KYB completion. Show verificationProfile properties
Profile identifier (e.g. kyc_profile_a).
Status: incomplete, pending, approved, or rejected.
Breakdown of individual verification criteria steps.
Arbitrary metadata associated with the customer.
ISO 8601 creation timestamp.
ISO 8601 last-updated timestamp.
Pagination metadata for the current result set. Show pagination properties
Number of items per page.
Total number of customers matching the query.
Whether a next page exists.
Whether a previous page exists.
"customers" : [ { "id" : "customer_f31121c389624d3697cbf3ea8830b7a4" , "type" : "individual" , "email" : "jane.smith@example.com" , "phone" : "+14155550123" , "firstName" : "Jane" , "lastName" : "Smith" , "verificationProfiles" : [ { "name" : "kyc_profile_a" , "status" : "incomplete" , "criteria" : { "complete" : [ "email_address" , "phone_number" , "residential_address" , "tax_identification_number" ], "pending" : [], "required" : [ "identity_document" , "liveness_report_document" ], "errors" : [] } } ], "meta" : {}, "createdAt" : "2026-03-09T20:46:31.305Z" , "updatedAt" : "2026-03-09T20:46:31.305Z" } ], "pagination" : { "page" : 1 , "limit" : 10 , "total" : 1 , "totalPages" : 1 , "hasNext" : false , "hasPrevious" : false } }
Error codes Status Code Description 400address/invalidInvalid query parameters. 404resource/not-foundThe requested resource was not found. 422validation/failedOne or more query parameters failed validation.
