> ## 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.
# Customer Verification Profile and Statuses
> The verification profile tracks a customer's KYC or KYB approval state. Learn what each status means and what triggers transitions between states.
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.
```bash theme={"dark"}
GET https://api.spherepay.co/v2/customer/{id}
```
```json theme={"dark"}
{
"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](mailto:support@spherepay.co) with the `customerId`.
***
## Related guides
Step-by-step guide for onboarding individual customers via API.
Step-by-step guide for onboarding business customers via API.
Onboard customers using SpherePay's hosted verification experience.
Overview of customer types, onboarding models, and integration methods.