Verification Profiles

A verification profile is the set of KYC or KYB requirements SpherePay needs to approve a customer — individual or business — for a group of products. Each profile unlocks its own products and assets. A customer can hold several profiles at once, and each one moves through its own statuses independently. Profiles are returned in the verificationProfiles array of GET /v2/customer/{id}. Monitoring them is the primary way to determine whether a customer is ready to transfer on a given rail.

Available profiles

Your application is enabled for a set of profiles by SpherePay. Each customer is evaluated against the profiles you select for them with enabledVerificationProfiles — see Selecting profiles.

Profile	Name in the API	Products	Rails	Assets	Eligible residents	Limitations
A	`kyc_profile_a` (individuals), `kyb_profile_a` (businesses), `ubo_kyc_profile_a` (business representatives)	Transfers, offloader wallets, on-ramper accounts	ACH, Wire, SEPA, stablecoin networks	USD, EUR, USDC, USDT, EURC	US and non-US residents	—
C	`kyc_profile_c`, `kyb_profile_c`, `ubo_kyc_profile_c`	Transfers	Wire, SWIFT, Ethereum, Solana, Tron	USD, USDC, USDT	Non-US residents only	Off-ramp only
D	`kyc_profile_d`, `kyb_profile_d`, `ubo_kyc_profile_d`	Transfers	SPEI	MXN	Non-US residents only	MXN to USD only; requires profile C on the same customer

When SpherePay enables a new profile for your application, existing customers are not enrolled automatically. Verifying a customer for an additional profile has a cost, so you add the profile explicitly with PATCH /v2/customer/{id}. See Add a profile to an existing customer.

Profile selection applies to customers you onboard through the API. Customers onboarded through hosted KYC links are enrolled in your application’s default profiles; enabledVerificationProfiles is not available on the hosted flow.

Verification statuses

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

Status	Description	Can transact on this profile?
`incomplete`	Not all requirements have been supplied. This is the initial state. `criteria.required` lists what is outstanding.	No
`pending`	All requirements are in and SpherePay is reviewing.	No
`approved`	SpherePay approved the customer for this profile.	Yes
`rejected`	SpherePay could not approve the customer based on the submitted information.	No
`resubmission_required`	SpherePay needs corrected information. `criteria.errors` lists what to fix.	No

Status lifecycle

incomplete → pending → approved
                    ↘ rejected
                    ↘ resubmission_required → pending

The customer starts in incomplete. The criteria.required array lists all outstanding requirements for that profile.
Once every requirement is fulfilled, SpherePay submits the customer for review and the profile moves to pending. No submit call is needed.
The review completes and the profile moves to approved, rejected, or resubmission_required.
Each profile moves on its own. Profile C can reach approved while profile A is still pending on the same customer.

A customer is submitted for review only once every enabled profile has an empty criteria.required. If you enable two profiles, supply the requirements for both before expecting either to leave incomplete.

Verification criteria arrays

Each verification profile contains a criteria object with four arrays.

Array	Description
`complete`	Requirements that have been fulfilled. No further action needed.
`pending`	Requirements currently being processed. 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, as `{ name, detail }` objects. Correct these before resubmitting.

Requirements shared between profiles are satisfied once for all of them. If a customer already holds an approved profile A, adding profile C only asks for the criteria C needs that A did not.

How to check verification status

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

{
  "id": "customer_f31121c389624d3697cbf3ea8830b7a4",
  "enabledVerificationProfiles": ["a", "c"],
  "verificationProfiles": [
    {
      "name": "kyc_profile_a",
      "status": "approved",
      "criteria": {
        "complete": ["email_address", "phone_number", "residential_address", "tax_identification_number", "identity_document", "liveness_report_document", "account_purpose", "source_of_funds", "expected_monthly_payments", "employment_status", "acting_as_intermediary", "occupation_soc_code", "source_of_funds_document"],
        "pending": [],
        "required": [],
        "errors": []
      }
    },
    {
      "name": "kyc_profile_c",
      "status": "incomplete",
      "criteria": {
        "complete": ["email_address", "phone_number", "residential_address", "tax_identification_number", "identity_document", "liveness_report_document", "source_of_funds", "occupation_soc_code", "source_of_funds_document"],
        "pending": [],
        "required": ["sex", "country_of_birth", "nationality", "proof_of_address_document", "w8_ben_document"],
        "errors": []
      }
    }
  ],
  "type": "individual"
}

Poll GET /v2/customer/{id} to detect when a profile reaches approved, then proceed with payment method registration and transfers on the rails that profile unlocks.

Webhook events

Instead of polling, subscribe to customer webhook events. SpherePay emits one event per verification profile per status change — customer.pending, customer.approved and customer.rejected — and data.verificationProfile names the profile that changed, for example kyc_profile_c or ubo_kyc_profile_a. A customer with two profiles produces two independent event streams, so key your handling on the profile name, not only on the customer ID.

Requirements by profile

Each profile evaluates its own set of criteria. Expand a customer type to see which profiles evaluate each item and how to satisfy it.

Individual customers

Each item in the criteria arrays corresponds to a requirement. The columns show which profiles evaluate it.

Item	Action required	A	C	D
`email_address`	Provide `email`	✓	✓	✓
`phone_number`	Provide `phone`	✓	✓	✓
`residential_address`	Provide the full `address` object	✓	✓	✓
`tax_identification_number`	Provide `personalInformation.taxIdentificationNumber` and its type and country	✓	✓	✓
`identity_document`	Upload a government-issued ID via `POST /v2/document` (`passport`, `id_card` front and back, or `drivers`)	✓	✓	✓
`liveness_report_document`	Upload a liveness report via `POST /v2/document` with `documentType: "liveness_report_document"`	✓	✓	✓
`source_of_funds_document`	Upload via `POST /v2/document` with `documentType: "source_of_funds_document"`	✓	✓	✓
`source_of_funds`	Provide `personalInformation.sourceOfFunds`	✓	✓	✓
`occupation_soc_code`	Provide `personalInformation.occupationSocCode`	✓	✓	✓
`account_purpose`	Provide `personalInformation.accountPurpose` (and `accountPurposeDescription` when the purpose is `other`)	✓	—	—
`employment_status`	Provide `personalInformation.employmentStatus`	✓	—	—
`acting_as_intermediary`	Provide `personalInformation.actingAsIntermediary`	✓	—	—
`expected_monthly_payments`	Provide `personalInformation.expectedMonthlyPayments`	✓	—	✓
`country_of_birth`	Provide `personalInformation.countryOfBirth` (ISO 3166-1 alpha-3)	EEA+ residents only	✓	✓
`nationality`	Provide `personalInformation.nationality` (ISO 3166-1 alpha-3)	EEA+ residents only	✓	✓
`sex`	Provide `personalInformation.gender`	—	✓	✓
`proof_of_address_document`	Upload via `POST /v2/document` with `documentType: "proof_of_address_document"`	—	✓	✓
`w8_ben_document`	Upload via `POST /v2/document` with `documentType: "w8_ben_document"`	—	✓	✓
`state_of_birth`	Provide `personalInformation.stateOfBirth`	—	—	✓
`expected_monthly_transaction_count`, `transaction_frequency`, `expected_counterparty_types`, `expected_geographies`	Provide `personalExpectedActivity`	—	—	✓
`ip_address`, `ip_address_approved`	Provide `ipAddress` (the customer’s sign-up IP). `ip_address_approved` is resolved by SpherePay from the address’s geolocation.	—	—	✓
`terms_of_service`	Accept TOS via the hosted link from `POST /v2/customer/{id}/tos-link` — only when TOS is enabled for your application	✓	✓	✓
`liveness_check`, `email_verification`, `phone_verification`	Enhanced checks via the face-verification link and OTP endpoints — only required for some integrations	✓	—	—

Business customers

Item	Action required	A	C	D
`email_address`, `phone_number`	Provide `email` and `phone`	✓	✓	✓
`operating_address`, `registered_address`	Provide both entries in the `addresses` array	✓	✓	✓
`legal_name`, `trade_name`, `entity_type`, `description`, `website`, `incorporated_on`, `naics_code`	Provide the matching `businessInformation` fields	✓	✓	✓
`identification_number`	Provide `businessInformation.identificationNumber` and `identificationNumberType`	✓	✓	✓
`estimated_annual_revenue`, `expected_monthly_payments`, `account_purpose`	Provide `estimatedAnnualRevenueInUsd`, `expectedMonthlyPaymentsInUsd`, `accountPurpose`	✓	✓	✓
`source_of_funds`, `source_of_funds_description`	Provide `primarySourceOfFunds` and `primarySourceOfFundsDescription`	✓	✓	✓
`is_dao`, `regulated_activities`, `participates_in_regulated_financial_activity`, `operates_in_prohibited_countries`	Provide the matching `businessInformation` fields	✓	✓	✓
`business_representatives`, `control_person_added`	Register associated persons via `POST /v2/business-representative`. For EEA+ businesses this includes directors, signers, control persons and ≥ 25% owners; otherwise 25%+ owners and a control person	✓	✓	✓
`eea_control_person_present`	Register at least one representative with `isControlPerson: true`	EEA+ businesses only	—	—
`eea_ap_kyc_scope`	At least one director on file, and every director, signer, control person and ≥ 25% owner completes full identity verification	EEA+ businesses only	—	—
`incorporation_cert_document`, `shareholder_registry_document`, `proof_of_address_document`	Upload via `POST /v2/document` with the matching `documentType`	✓	✓	✓
`registration_number`	Provide `businessInformation.registrationNumber` and `registrationNumberType`	EEA+ businesses only	✓	✓
`incorporation_articles_document`, `w8_ben_e_document`, `bank_statement_document`, `source_of_funds_document`, `corporate_resolution_document`, `financial_statements_document`	Upload via `POST /v2/document` with the matching `documentType`	—	✓	✓
`expected_monthly_transaction_count`, `transaction_frequency`, `expected_counterparty_types`, `expected_geographies`	Provide `businessExpectedActivity`	—	—	✓
`ip_address`, `ip_address_approved`	Provide `ipAddress`	—	—	✓
`terms_of_service`	Accept TOS via hosted link — only when TOS is enabled for your application	✓	✓	✓

Business representatives

Each representative has its own ubo_kyc_profile_* entry, returned on GET /v2/business-representative/{id}. Documents for a representative are uploaded with target="business-representative".

Item	Action required	A	C	D
`email_address`, `phone_number`	Provide `email` and `phone`	✓	✓	✓
`residential_address`	Provide the full `address` object	✓	✓	✓
`tax_identification_number`	Provide `personalInformation.taxIdentificationNumber` and its type and country	✓	✓	✓
`ownership_percentage`, `is_control_person`, `is_signer`, `relationship_established_at`, `title`	Provide `representationDetails`	✓	✓	✓
`identity_document`, `liveness_report_document`, `proof_of_address_document`	Upload via `POST /v2/document` with `target="business-representative"`	✓	✓	✓
`country_of_birth`, `nationality`	Provide `personalInformation.countryOfBirth` and `nationality` (ISO 3166-1 alpha-3)	EEA+ businesses only	✓	✓
`middle_name`, `sex`	Provide `middleName` and `personalInformation.gender` — validated when the representative is created	—	✓	✓
`occupation_soc_code`, `source_of_funds`	Provide `personalInformation.occupationSocCode` and `sourceOfFunds`	—	✓	✓
`w8_ben_document`, `source_of_funds_document`	Upload via `POST /v2/document` with `target="business-representative"`	—	✓	✓
`state_of_birth`	Provide `personalInformation.stateOfBirth`	—	—	✓

See EEA+ businesses for the full associated-person requirements.

Handling rejected customers

A rejected status means SpherePay could not approve the customer for that profile. The customer cannot transact on the products that profile unlocks; other approved profiles on the same customer are unaffected. If a customer is incorrectly rejected or requires re-review, contact support@spherepay.co with the customerId and the profile name.

Selecting profiles

How enabledVerificationProfiles works and what the API returns.

Onboard a customer with profiles

Choose profiles at creation and add one to an existing customer.

Remove a profile

Drop a profile a customer no longer needs.

Individual KYC

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

Introduction

Onboarding

Transfers

Automation

Webhooks

Reference data

Operational

Verification Profiles

Available profiles

Verification statuses

Status lifecycle

Verification criteria arrays

How to check verification status

Webhook events

Requirements by profile

Handling rejected customers

Selecting profiles

Onboard a customer with profiles

Remove a profile

Individual KYC

​Available profiles

​Verification statuses

​Status lifecycle

​Verification criteria arrays

​How to check verification status

​Webhook events

​Requirements by profile

​Handling rejected customers

​Related guides

Selecting profiles

Onboard a customer with profiles

Remove a profile

Individual KYC

Available profiles

Verification statuses

Status lifecycle

Verification criteria arrays

How to check verification status

Webhook events

Requirements by profile

Handling rejected customers

Related guides