Customer Verification Profile and Statuses

A verification profile is a record of the requirements SpherePay needs to approve a customer — individual or business — before they can initiate or receive transfers. It is returned as part of the verificationProfiles array whenever you call GET /v2/customer/{id}. Monitoring the verification profile is the primary way to determine whether a customer is ready to transfer. Most integrations will see a single profile in the verificationProfiles array. A customer is ready to transfer when that profile’s status reaches approved. If you see unexpected profile names, contact your SpherePay representative.

Different verification profiles unlock different transfer capabilities. For example, USD/EUR transfers use kyc_profile_a, while BRL/PIX transfers require kyc_profile_b — a separate onboarding path. Contact your SpherePay representative to understand which profiles apply to your integration.

Verification statuses

The status field on a verification profile has four possible values.

Status	Description	Can initiate transfers?
`incomplete`	The customer has not yet completed all verification requirements. This is the initial state.	No
`pending`	The customer has completed all requirements and is waiting for SpherePay’s review.	No
`approved`	SpherePay has approved the customer. They are fully onboarded and can initiate transfers.	Yes
`rejected`	SpherePay could not approve the customer based on the submitted information.	No

Status lifecycle

A verification profile moves through states in the following order:

incomplete → pending → approved
                    ↘
                     rejected

The customer starts in incomplete. The criteria.required array lists all outstanding requirements.
Once all requirements are fulfilled, SpherePay automatically processes the verification and moves the profile to pending. No submit call is needed.
SpherePay completes the review and transitions the profile to either approved or rejected.

Verification criteria arrays

Each verification profile contains a criteria object with four arrays that describe the current state of each requirement.

Array	Description
`complete`	Requirements that have been fulfilled. No further action needed.
`pending`	Requirements currently being processed by SpherePay. Wait for this to resolve.
`required`	Requirements that must still be completed. You or your customer must act on these.
`errors`	Requirements with validation errors. Correct these before resubmitting.

When required is empty and status is approved, the customer is fully onboarded.

What triggers state transitions

Action	Effect
Customer creation with email, phone, and address	Populates `complete` for `email_address`, `phone_number`, `residential_address`
Upload of identity document	Moves `identity_document` from `required` to `pending`, then `complete` after processing
Upload of liveness report or completion of face liveness check	Fulfills `liveness_report_document` or `liveness_check` requirement
TOS acceptance via hosted link	Fulfills `terms_of_service` requirement
All `required` items resolved	SpherePay automatically submits for review; status moves to `pending`
Manual review completed by SpherePay	Status moves to `approved` or `rejected`

How to check verification status

Call GET /v2/customer/{id} to retrieve the current state of a customer’s verification profile.

GET https://api.spherepay.co/v2/customer/{id}

{
  "id": "customer_f31121c389624d3697cbf3ea8830b7a4",
  "email": "jane.smith@example.com",
  "phone": "+14155550123",
  "verificationProfiles": [
    {
      "name": "kyc_profile_a",
      "status": "approved",
      "criteria": {
        "complete": [
          "email_address",
          "phone_number",
          "residential_address",
          "tax_identification_number",
          "identity_document",
          "liveness_report_document"
        ],
        "pending": [],
        "required": [],
        "errors": []
      }
    }
  ],
  "createdAt": "2026-03-09T20:46:31.305Z",
  "updatedAt": "2026-03-09T20:46:31.305Z",
  "type": "individual"
}

Poll GET /v2/customer/{id} to detect when approval occurs, then proceed with payment method registration and transfer setup.

Verification profile fields — individual customers

Each item in the criteria arrays corresponds to a specific requirement. The table below describes each field and what action resolves it.

Item	Action required
`email_address`	Provide an email address when creating or updating the customer
`phone_number`	Provide a phone number when creating or updating the customer
`residential_address`	Provide a full residential address when creating or updating the customer
`tax_identification_number`	Provide a tax ID via `personalInformation.taxIdentificationNumber`
`identity_document`	Upload a government-issued ID via `POST /v2/document`
`liveness_report_document`	Upload a liveness report from your KYC provider via `POST /v2/document`
`liveness_check`	Complete face liveness verification via the link from `POST /v2/enhanced-due-diligence/face-verification-link` — enhanced, only required for some integrations
`terms_of_service`	Accept TOS via the hosted link from `POST /v2/customer/{id}/tos-link` — enhanced, only required for some integrations
`email_verification`	Verify email via OTP send and verify endpoints — enhanced, only required for some integrations
`phone_verification`	Verify phone via OTP send and verify endpoints — enhanced, only required for some integrations

Verification profile fields — business customers

Item	Action required
`email_address`	Provide an email address when creating or updating the customer
`phone_number`	Provide a phone number when creating or updating the customer
`operating_address`	Provide an operating address in the `addresses` array
`registered_address`	Provide a registered address in the `addresses` array
`legal_name`	Provide `businessInformation.legalName`
`trade_name`	Provide `businessInformation.tradeName`
`entity_type`	Provide `businessInformation.entityType`
`description`	Provide `businessInformation.description`
`naics_code`	Provide `businessInformation.naicsCode`
`website`	Provide `businessInformation.website`
`incorporated_on`	Provide `businessInformation.incorporatedOn`
`identification_number`	Provide `businessInformation.identificationNumber` — types vary by country
`estimated_annual_revenue`	Provide `businessInformation.estimatedAnnualRevenueInUsd`
`expected_monthly_payments`	Provide `businessInformation.expectedMonthlyPaymentsInUsd`
`account_purpose`	Provide `businessInformation.accountPurpose`
`source_of_funds`	Provide `businessInformation.primarySourceOfFunds`
`regulated_activities`	Provide `businessInformation.regulatedActivities`
`business_representatives`	Register and verify all UBOs via `POST /v2/business-representative`
`incorporation_cert_document`	Upload via `POST /v2/document` with `documentType: "incorporation_certificate"`
`shareholder_registry_document`	Upload via `POST /v2/document` with `documentType: "shareholder_registry"`
`proof_of_address_document`	Upload via `POST /v2/document` with `documentType: "proof_of_address"`
`terms_of_service`	Accept TOS via hosted link — enhanced, only required for some integrations
`master_service_agreement`	Sign MSA via the hosted form presented after TOS acceptance — enhanced, only required for some integrations

Handling rejected customers

A rejected status means the verification could not be approved based on the submitted information. Customers with a rejected profile cannot initiate or receive transfers. If a customer is incorrectly rejected or requires re-review, contact support@spherepay.co with the customerId.

Individual KYC

Step-by-step guide for onboarding individual customers via API.

Business KYB

Step-by-step guide for onboarding business customers via API.

KYC via hosted link

Onboard customers using SpherePay’s hosted verification experience.

Customers overview

Overview of customer types, onboarding models, and integration methods.

Introduction

Onboarding

Transfers

Automation

Reference data

Operational

Customer Verification Profile and Statuses

Verification statuses

Status lifecycle

Verification criteria arrays

What triggers state transitions

How to check verification status

Verification profile fields — individual customers

Verification profile fields — business customers

Handling rejected customers

Individual KYC

Business KYB

KYC via hosted link

Customers overview

​Verification statuses

​Status lifecycle

​Verification criteria arrays

​What triggers state transitions

​How to check verification status

​Verification profile fields — individual customers

​Verification profile fields — business customers

​Handling rejected customers

​Related guides

Individual KYC

Business KYB

KYC via hosted link

Customers overview

Verification statuses

Status lifecycle

Verification criteria arrays

What triggers state transitions

How to check verification status

Verification profile fields — individual customers

Verification profile fields — business customers

Handling rejected customers

Related guides