> ## 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 com Filtros e Paginação

> List customers with optional server-side search, filters, and sort.

Use este endpoint para recuperar todos os clientes associados à sua conta SpherePay. Os resultados são retornados em páginas, e você pode filtrar por status ou tipo de cliente para restringir a lista. Cada item na resposta inclui o perfil de verificação do cliente, para que você possa identificar rapidamente quais clientes estão prontos para transferências.


## 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
                  enabledVerificationProfiles:
                    description: >-
                      Which verification profile families this customer may
                      onboard through. Set explicitly at creation — from the
                      request when supplied, otherwise a snapshot of the
                      application's families at that moment — and thereafter
                      changed only by an explicit update, so it does not follow
                      later changes to the application. Always a subset of the
                      application's families. Distinct from
                      `verificationProfiles`, which reports the evaluated
                      profiles and their statuses.
                    example:
                      - a
                      - c
                    items:
                      enum:
                        - a
                        - b
                        - c
                        - d
                      type: string
                    nullable: true
                    type: array
                  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:
                        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
                        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'
                        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
                      stateOfBirth:
                        description: >-
                          The subdivision code of the state/province where the
                          customer was born, without the country prefix (e.g.
                          `JAL`, not `MX-JAL`). Requires `countryOfBirth`.
                          Required by some verification providers.
                        example: JAL
                        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
                        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
                        type: string
                    type: object
                  phone:
                    description: Customer phone number
                    example: '+14155550123'
                    type: string
                  statusDetails:
                    description: >-
                      Additional context on why the customer's verification
                      reached its current status.
                    example:
                      message: >-
                        Please re-upload a clear photo of the front and back of
                        the director's ID and correct the tax ID number.
                      reasons:
                        - externalReason: >-
                            Cannot validate ID — upload a photo of the ID that
                            is clear
                          reasonCode: poor_image_quality
                          verificationProfiles:
                            - kyb_profile_a
                        - externalReason: >-
                            The tax identification number is not in a valid
                            format for the selected country and ID type.
                          reasonCode: invalid_tax_identification_number
                          verificationProfiles:
                            - kyb_profile_a
                      updatedAt: '2026-07-16T21:04:00Z'
                    properties:
                      message:
                        type: string
                      reasons:
                        items:
                          properties:
                            externalReason:
                              type: string
                            reasonCode:
                              type: string
                            verificationProfiles:
                              items:
                                type: string
                              type: array
                          required:
                            - reasonCode
                            - verificationProfiles
                          type: object
                        type: array
                      updatedAt:
                        type: string
                    required:
                      - reasons
                      - updatedAt
                    type: object
                  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: >-
                      The evaluated verification profiles for this customer and
                      their statuses — what the customer is being assessed
                      against right now, as opposed to
                      `enabledVerificationProfiles`, which says which families
                      they are permitted to use. 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
                                      - employment_status
                                      - acting_as_intermediary
                                      - sex
                                      - country_of_birth
                                      - nationality
                                      - middle_name
                                      - occupation_soc_code
                                      - w8_ben_document
                                      - w9_document
                                      - state_of_birth
                                      - ip_address
                                      - ip_address_approved
                                      - expected_monthly_transaction_count
                                      - transaction_frequency
                                      - expected_counterparty_types
                                      - expected_geographies
                                      - 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
                            - rejected_final
                            - manual_review
                            - resubmission_required
                          example: incomplete
                          type: string
                      required:
                        - name
                        - status
                      type: object
                    type: array
                required:
                  - id
                  - enabledVerificationProfiles
                  - 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
                  enabledVerificationProfiles:
                    description: >-
                      Which verification profile families this customer may
                      onboard through. Set explicitly at creation — from the
                      request when supplied, otherwise a snapshot of the
                      application's families at that moment — and thereafter
                      changed only by an explicit update, so it does not follow
                      later changes to the application. Always a subset of the
                      application's families. Distinct from
                      `verificationProfiles`, which reports the evaluated
                      profiles and their statuses.
                    example:
                      - a
                      - c
                    items:
                      enum:
                        - a
                        - b
                        - c
                        - d
                      type: string
                    nullable: true
                    type: array
                  id:
                    description: Customer ID
                    example: customer_f31121c389624d3697cbf3ea8830b7a4
                    type: string
                  meta:
                    additionalProperties: {}
                    type: object
                  phone:
                    description: Customer phone number
                    example: '+14155550123'
                    type: string
                  statusDetails:
                    description: >-
                      Additional context on why the customer's verification
                      reached its current status.
                    example:
                      message: >-
                        Please re-upload a clear photo of the front and back of
                        the director's ID and correct the tax ID number.
                      reasons:
                        - externalReason: >-
                            Cannot validate ID — upload a photo of the ID that
                            is clear
                          reasonCode: poor_image_quality
                          verificationProfiles:
                            - kyb_profile_a
                        - externalReason: >-
                            The tax identification number is not in a valid
                            format for the selected country and ID type.
                          reasonCode: invalid_tax_identification_number
                          verificationProfiles:
                            - kyb_profile_a
                      updatedAt: '2026-07-16T21:04:00Z'
                    properties:
                      message:
                        type: string
                      reasons:
                        items:
                          properties:
                            externalReason:
                              type: string
                            reasonCode:
                              type: string
                            verificationProfiles:
                              items:
                                type: string
                              type: array
                          required:
                            - reasonCode
                            - verificationProfiles
                          type: object
                        type: array
                      updatedAt:
                        type: string
                    required:
                      - reasons
                      - updatedAt
                    type: object
                  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: >-
                      The evaluated verification profiles for this customer and
                      their statuses — what the customer is being assessed
                      against right now, as opposed to
                      `enabledVerificationProfiles`, which says which families
                      they are permitted to use. 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
                                      - employment_status
                                      - acting_as_intermediary
                                      - sex
                                      - country_of_birth
                                      - nationality
                                      - middle_name
                                      - occupation_soc_code
                                      - w8_ben_document
                                      - w9_document
                                      - state_of_birth
                                      - ip_address
                                      - ip_address_approved
                                      - expected_monthly_transaction_count
                                      - transaction_frequency
                                      - expected_counterparty_types
                                      - expected_geographies
                                      - 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
                            - rejected_final
                            - manual_review
                            - resubmission_required
                          example: incomplete
                          type: string
                      required:
                        - name
                        - status
                      type: object
                    type: array
                required:
                  - id
                  - enabledVerificationProfiles
                  - 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

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.