> ## 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: title: '' description: '' version: 1.0.0 contact: {} servers: - url: https://api.spherepay.co description: Production security: - bearer: [] tags: [] paths: /v2/customer: get: summary: List Customers description: List customers with optional server-side search, filters, and sort. parameters: - name: '' required: true in: query schema: type: object properties: page: description: 'Page number of the list (default: 1)' example: 1 type: string default: '1' limit: description: 'Number of items per page (default: 10)' example: 10 type: string default: '10' search: description: >- Substring search across customer first name, last name, legal name, trade name, and email fields example: jane type: string minLength: 1 maxLength: 255 email: description: Filter by exact customer email (individual or business) example: jane@example.com type: string format: email 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 sort: 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 default: '-created' required: - page - limit - sort responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/CustomerListResponseDto' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ProblemDetailsDto' examples: Bad Request: summary: Bad Request value: status: 400 detail: Invalid request parameters code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ProblemDetailsDto' examples: Not Found: summary: Not Found value: status: 404 detail: Resource not found code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c '422': description: Unprocessable Entity - Validation Error content: application/json: schema: $ref: '#/components/schemas/ProblemDetailsDto' examples: Validation Error: summary: Validation Error value: status: 422 detail: Validation failed code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name components: schemas: CustomerListResponseDto: type: object properties: customers: description: Array of customer objects type: array items: oneOf: - title: Individual description: Response containing information about an individual customer. type: object properties: id: description: Customer ID example: customer_f31121c389624d3697cbf3ea8830b7a4 type: string email: description: Customer email address example: jane.smith@example.com type: string phone: description: Customer phone number example: '+14155550123' 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: - 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: [] type: array items: type: object properties: name: description: The name of the verification profile. example: kyc_profile_a type: string 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 status: description: The status of the verification profile. example: incomplete type: string enum: - incomplete - pending - approved - rejected - resubmission_required criteria: description: The criteria for the verification profile. example: complete: - email_address - phone_number - residential_address - tax_identification_number pending: [] required: - identity_document - liveness_report_document errors: [] type: object properties: complete: description: Completed fields. example: - email_address - phone_number - residential_address - tax_identification_number type: array items: type: string pending: description: >- Pending fields. These fields are currently being verified. example: [] type: array items: type: string required: description: >- Required fields. These fields are required to be completed before the verification profile can be approved. example: - identity_document - liveness_report_document type: array items: type: string errors: description: >- The errors that occurred while verifying the fields. example: [] type: array items: type: object properties: name: type: string 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 - 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 detail: type: string required: - name required: - complete - pending - required - errors required: - name - status meta: type: object additionalProperties: {} tosStatus: description: >- Customer Terms of Service acceptance status (incomplete | pending | approved). example: incomplete type: string enum: - incomplete - pending - approved x-enumNames: - Incomplete - Pending - Approved createdAt: description: ISO 8601 formatted customer creation timestamp example: '2026-03-09T20:46:31.305Z' type: string updatedAt: description: ISO 8601 formatted customer update timestamp example: '2026-03-09T20:46:31.305Z' type: string type: description: Customer type example: individual type: string enum: - individual firstName: description: Customer first name (individual customers only) example: Jane type: string lastName: description: Customer last name (individual customers only) example: Smith type: string dateOfBirth: description: >- The customer's date of birth in YYYY-MM-DD format (individual customers only). example: '1990-01-15' type: string 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. type: object properties: 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 type: string minLength: 1 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 type: string minLength: 1 taxIdentificationNumberDescription: description: >- Description of the tax identification number. Required when type is `other` type: string gender: description: >- The gender of the customer. Required by some verification providers. example: male type: string enum: - male - female - other 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 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 middleName: description: >- The customer's middle name. Required for some verification flows. example: James type: string minLength: 1 maxLength: 255 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: 15-1132 type: string minLength: 1 maxLength: 20 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: description: >- The customer's primary source of funds. Required by some verification providers. example: salary type: string enum: - salary - business_income - investment_returns - inheritance - gift - savings - other required: - id - verificationProfiles - tosStatus - createdAt - updatedAt - type - title: Business description: Response containing information about a business customer. type: object properties: id: description: Customer ID example: customer_f31121c389624d3697cbf3ea8830b7a4 type: string email: description: Customer email address example: jane.smith@example.com type: string phone: description: Customer phone number example: '+14155550123' 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: - 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: [] type: array items: type: object properties: name: description: The name of the verification profile. example: kyc_profile_a type: string 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 status: description: The status of the verification profile. example: incomplete type: string enum: - incomplete - pending - approved - rejected - resubmission_required criteria: description: The criteria for the verification profile. example: complete: - email_address - phone_number - residential_address - tax_identification_number pending: [] required: - identity_document - liveness_report_document errors: [] type: object properties: complete: description: Completed fields. example: - email_address - phone_number - residential_address - tax_identification_number type: array items: type: string pending: description: >- Pending fields. These fields are currently being verified. example: [] type: array items: type: string required: description: >- Required fields. These fields are required to be completed before the verification profile can be approved. example: - identity_document - liveness_report_document type: array items: type: string errors: description: >- The errors that occurred while verifying the fields. example: [] type: array items: type: object properties: name: type: string 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 - 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 detail: type: string required: - name required: - complete - pending - required - errors required: - name - status meta: type: object additionalProperties: {} tosStatus: description: >- Customer Terms of Service acceptance status (incomplete | pending | approved). example: incomplete type: string enum: - incomplete - pending - approved x-enumNames: - Incomplete - Pending - Approved createdAt: description: ISO 8601 formatted customer creation timestamp example: '2026-03-09T20:46:31.305Z' type: string updatedAt: description: ISO 8601 formatted customer update timestamp example: '2026-03-09T20:46:31.305Z' type: string type: description: Customer type example: business type: string enum: - business 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 required: - id - verificationProfiles - tosStatus - createdAt - updatedAt - type pagination: type: object properties: page: description: Current page number example: 1 type: number limit: description: Number of items per page example: 10 type: number minimum: 1 exclusiveMinimum: false maximum: 100 exclusiveMaximum: false total: description: Total number of items example: 1 type: number totalPages: description: Total number of pages example: 1 type: number hasNext: description: Whether there is a next page example: false type: boolean hasPrevious: description: Whether there is a previous page example: false type: boolean required: - page - limit - total - totalPages - hasNext - hasPrevious required: - customers - pagination ProblemDetailsDto: type: object properties: title: type: string status: type: integer detail: type: string code: type: string errors: type: array items: type: object properties: detail: type: string pointer: type: string parameter: type: string header: type: string required: - detail correlationId: type: string required: - status - detail securitySchemes: bearer: scheme: bearer bearerFormat: JWT type: http ````