> ## 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. # List Customers with Filters and Pagination > List customers with optional server-side search, filters, and sort. 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. ## OpenAPI ````yaml openapi/spherepay.yaml GET /v2/customer openapi: 3.0.0 info: contact: {} description: The Sphere REST API for payments, transfers, and accounts. title: Sphere API version: '2' servers: - description: Production url: https://api.spherepay.co security: - bearer: [] tags: [] paths: /v2/customer: get: summary: List Customers description: List customers with optional server-side search, filters, and sort. operationId: getV2Customer parameters: - in: query name: '' required: true schema: properties: country: description: >- Filter by customer address country (ISO 3166-1 Alpha-3, e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries). example: USA type: string email: description: Filter by exact customer email (individual or business) example: jane@example.com format: email type: string limit: default: '10' description: 'Number of items per page (default: 10)' example: 10 type: string page: default: '1' description: 'Page number of the list (default: 1)' example: 1 type: string search: description: >- Substring search across customer first name, last name, legal name, trade name, and email fields example: jane maxLength: 255 minLength: 1 type: string sort: default: '-created' description: >- Comma-separated sort fields. Prefix with "-" for descending, "+" (or no prefix) for ascending. Allowed fields: created, updated. Example: "created,-updated". example: '-created' type: string required: - page - limit - sort type: object responses: '200': content: application/json: schema: $ref: '#/components/schemas/CustomerListResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error components: schemas: CustomerListResponseDto: properties: customers: description: Array of customer objects items: oneOf: - description: Response containing information about an individual customer. properties: createdAt: description: ISO 8601 formatted customer creation timestamp example: '2026-03-09T20:46:31.305Z' type: string dateOfBirth: description: >- The customer's date of birth in YYYY-MM-DD format (individual customers only). example: '1990-01-15' type: string email: description: Customer email address example: jane.smith@example.com type: string firstName: description: Customer first name (individual customers only) example: Jane type: string id: description: Customer ID example: customer_f31121c389624d3697cbf3ea8830b7a4 type: string lastName: description: Customer last name (individual customers only) example: Smith type: string meta: additionalProperties: {} type: object personalInformation: description: >- Personal information for an individual customer, echoed back from the most recent submission. The tax identification number is omitted from responses for privacy. properties: accountPurpose: type: string accountPurposeDescription: description: >- A free-text description of the account purpose. Required when `accountPurpose` is `other`. type: string actingAsIntermediary: description: >- Whether the customer is acting as an intermediary on behalf of a third party. Required by some verification providers. example: false type: boolean countryOfBirth: description: >- The ISO3166-1 Alpha-3 country code of the country where the customer was born. See [Country Codes](/concepts/reference/supported-countries). example: USA type: string employmentStatus: type: string expectedMonthlyPayments: type: string gender: type: string middleName: description: >- The customer's middle name. Required for some verification flows. example: James maxLength: 255 minLength: 1 type: string nationality: description: >- The ISO3166-1 Alpha-3 country code of the customer's nationality. Required by some verification providers. See [Country Codes](/concepts/reference/supported-countries). example: USA type: string occupationSocCode: description: >- The customer's occupation as a 6-digit Standard Occupational Classification (SOC) code, validated against the supported occupation list. Required for some verification flows. example: '151252' maxLength: 20 minLength: 1 type: string residencyCountry: description: >- The ISO3166-1 Alpha-3 country code of the customer's country of residency. Often satisfied by the address country, but some verification providers require it as a separate attribute. See [Country Codes](/concepts/reference/supported-countries). example: USA type: string sourceOfFunds: type: string taxIdentificationNumberCountry: description: >- The ISO3166-1 Alpha-3 country code for the tax identification number. Required when providing tax identification information. See [Country Codes](/concepts/reference/supported-countries). example: USA minLength: 1 type: string taxIdentificationNumberDescription: description: >- Description of the tax identification number. Required when type is `other` type: string taxIdentificationNumberType: description: >- The type of tax identification number of the customer. Required when providing tax identification information. Please refer to the [Individual Verification Criteria](/concepts/onboarding/verification-profile) for the full list of reference. example: ssn minLength: 1 type: string type: object phone: description: Customer phone number example: '+14155550123' type: string tosStatus: description: >- Customer Terms of Service acceptance status (incomplete | pending | approved). enum: - incomplete - pending - approved example: incomplete type: string x-enumNames: - Incomplete - Pending - Approved type: description: Customer type enum: - individual example: individual type: string updatedAt: description: ISO 8601 formatted customer update timestamp example: '2026-03-09T20:46:31.305Z' type: string verificationProfiles: description: >- Array of verification profiles. For individual customers, this will include kyc_profile_a. For business customers, this will include kyb_profile_a. See [KYC Flow](/concepts/onboarding/individual-kyc) for individuals or [KYB Flow](/concepts/onboarding/business-kyb) for businesses. See [Verification Profile](/concepts/onboarding/verification-profile) for individual status definitions and criteria breakdown or [Verification Profile](/concepts/onboarding/verification-profile) for business status definitions and criteria breakdown. example: - criteria: complete: - email_address - phone_number - residential_address - tax_identification_number errors: [] pending: [] required: - identity_document - liveness_report_document name: kyc_profile_a status: incomplete items: properties: criteria: description: The criteria for the verification profile. example: complete: - email_address - phone_number - residential_address - tax_identification_number errors: [] pending: [] required: - identity_document - liveness_report_document properties: complete: description: Completed fields. example: - email_address - phone_number - residential_address - tax_identification_number items: type: string type: array errors: description: >- The errors that occurred while verifying the fields. example: [] items: properties: detail: type: string name: enum: - email_verification - phone_verification - residential_address - identity_document - tax_identification_number - liveness_check - terms_of_service - email_address - phone_number - master_service_agreement - legal_name - trade_name - entity_type - entity_type_description - description - registered_address - operating_address - business_representatives - naics_code - website - incorporated_on - identification_number - registration_number - estimated_annual_revenue - expected_monthly_payments - account_purpose - account_purpose_description - source_of_funds - source_of_funds_description - is_dao - regulated_activities - regulated_activities_description - >- participates_in_regulated_financial_activity - regulated_financial_activity_description - money_services_description - compliance_screening_explanation - operates_in_prohibited_countries - incorporation_cert_document - incorporation_articles_document - shareholder_registry_document - proof_of_nature_of_business_document - proof_of_address_document - liveness_report_document - ownership_percentage - is_control_person - control_person_added - is_signer - relationship_established_at - title - sex - country_of_birth - nationality - middle_name - occupation_soc_code - w8_ben_document - w9_document - w8_ben_e_document - corporate_resolution_document - source_of_funds_document - financial_statements_document - bank_statement_document - regulated_activity_document - flow_of_funds_document - kyc_b_approval - kyb_b_approval type: string required: - name type: object type: array pending: description: >- Pending fields. These fields are currently being verified. example: [] items: type: string type: array required: description: >- Required fields. These fields are required to be completed before the verification profile can be approved. example: - identity_document - liveness_report_document items: type: string type: array required: - complete - pending - required - errors type: object name: description: The name of the verification profile. enum: - kyc_profile_a - kyb_profile_a - ubo_kyc_profile_a - kyc_profile_b - kyb_profile_b - kyb_profile_c - kyc_profile_c - ubo_kyc_profile_c - kyb_profile_d - kyc_profile_d - ubo_kyc_profile_d example: kyc_profile_a type: string status: description: The status of the verification profile. enum: - incomplete - pending - approved - rejected - resubmission_required example: incomplete type: string required: - name - status type: object type: array required: - id - verificationProfiles - tosStatus - createdAt - updatedAt - type title: Individual type: object - description: Response containing information about a business customer. properties: businessLegalName: description: Customer business legal name (business customers only) example: Acme Corporation Inc. type: string businessTradeName: description: Customer business trade name (business customers only) example: Acme Corp type: string createdAt: description: ISO 8601 formatted customer creation timestamp example: '2026-03-09T20:46:31.305Z' type: string email: description: Customer email address example: jane.smith@example.com type: string id: description: Customer ID example: customer_f31121c389624d3697cbf3ea8830b7a4 type: string meta: additionalProperties: {} type: object phone: description: Customer phone number example: '+14155550123' type: string tosStatus: description: >- Customer Terms of Service acceptance status (incomplete | pending | approved). enum: - incomplete - pending - approved example: incomplete type: string x-enumNames: - Incomplete - Pending - Approved type: description: Customer type enum: - business example: business type: string updatedAt: description: ISO 8601 formatted customer update timestamp example: '2026-03-09T20:46:31.305Z' type: string verificationProfiles: description: >- Array of verification profiles. For individual customers, this will include kyc_profile_a. For business customers, this will include kyb_profile_a. See [KYC Flow](/concepts/onboarding/individual-kyc) for individuals or [KYB Flow](/concepts/onboarding/business-kyb) for businesses. See [Verification Profile](/concepts/onboarding/verification-profile) for individual status definitions and criteria breakdown or [Verification Profile](/concepts/onboarding/verification-profile) for business status definitions and criteria breakdown. example: - criteria: complete: - email_address - phone_number - residential_address - tax_identification_number errors: [] pending: [] required: - identity_document - liveness_report_document name: kyc_profile_a status: incomplete items: properties: criteria: description: The criteria for the verification profile. example: complete: - email_address - phone_number - residential_address - tax_identification_number errors: [] pending: [] required: - identity_document - liveness_report_document properties: complete: description: Completed fields. example: - email_address - phone_number - residential_address - tax_identification_number items: type: string type: array errors: description: >- The errors that occurred while verifying the fields. example: [] items: properties: detail: type: string name: enum: - email_verification - phone_verification - residential_address - identity_document - tax_identification_number - liveness_check - terms_of_service - email_address - phone_number - master_service_agreement - legal_name - trade_name - entity_type - entity_type_description - description - registered_address - operating_address - business_representatives - naics_code - website - incorporated_on - identification_number - registration_number - estimated_annual_revenue - expected_monthly_payments - account_purpose - account_purpose_description - source_of_funds - source_of_funds_description - is_dao - regulated_activities - regulated_activities_description - >- participates_in_regulated_financial_activity - regulated_financial_activity_description - money_services_description - compliance_screening_explanation - operates_in_prohibited_countries - incorporation_cert_document - incorporation_articles_document - shareholder_registry_document - proof_of_nature_of_business_document - proof_of_address_document - liveness_report_document - ownership_percentage - is_control_person - control_person_added - is_signer - relationship_established_at - title - sex - country_of_birth - nationality - middle_name - occupation_soc_code - w8_ben_document - w9_document - w8_ben_e_document - corporate_resolution_document - source_of_funds_document - financial_statements_document - bank_statement_document - regulated_activity_document - flow_of_funds_document - kyc_b_approval - kyb_b_approval type: string required: - name type: object type: array pending: description: >- Pending fields. These fields are currently being verified. example: [] items: type: string type: array required: description: >- Required fields. These fields are required to be completed before the verification profile can be approved. example: - identity_document - liveness_report_document items: type: string type: array required: - complete - pending - required - errors type: object name: description: The name of the verification profile. enum: - kyc_profile_a - kyb_profile_a - ubo_kyc_profile_a - kyc_profile_b - kyb_profile_b - kyb_profile_c - kyc_profile_c - ubo_kyc_profile_c - kyb_profile_d - kyc_profile_d - ubo_kyc_profile_d example: kyc_profile_a type: string status: description: The status of the verification profile. enum: - incomplete - pending - approved - rejected - resubmission_required example: incomplete type: string required: - name - status type: object type: array required: - id - verificationProfiles - tosStatus - createdAt - updatedAt - type title: Business type: object type: array pagination: properties: hasNext: description: Whether there is a next page example: false type: boolean hasPrevious: description: Whether there is a previous page example: false type: boolean limit: description: Number of items per page example: 10 exclusiveMaximum: false exclusiveMinimum: false maximum: 100 minimum: 1 type: number page: description: Current page number example: 1 type: number total: description: Total number of items example: 1 type: number totalPages: description: Total number of pages example: 1 type: number required: - page - limit - total - totalPages - hasNext - hasPrevious type: object required: - customers - pagination type: object ProblemDetailsDto: properties: code: type: string correlationId: type: string detail: type: string errors: items: properties: detail: type: string header: type: string parameter: type: string pointer: type: string required: - detail type: object type: array status: type: integer title: type: string required: - status - detail type: object securitySchemes: bearer: bearerFormat: JWT scheme: bearer type: http ````