> ## 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. # Listar Clientes con Filtros y Paginación > List customers with optional server-side search, filters, and sort. Usa este endpoint para recuperar todos los clientes asociados a tu cuenta de SpherePay. Los resultados se devuelven en páginas, y puedes filtrar por estado o tipo de cliente para limitar la lista. Cada elemento en la respuesta incluye el perfil de verificación del cliente, para que puedas identificar rápidamente qué clientes están listos para transferencias. ## 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 ````