Selecting Verification Profiles

Your application is enabled for a set of verification profiles by SpherePay. enabledVerificationProfiles lets you choose, per customer, which of those profiles the customer is evaluated against. A customer is only verified for the profiles you select, and only incurs the verification cost for those.

The field

enabledVerificationProfiles is an array of profile letters on POST /v2/customer and PATCH /v2/customer/{id}. It applies to customers onboarded through the API; customers onboarded through hosted KYC links are enrolled in your application’s default profiles.

{
  "type": "individual",
  "email": "jane.smith@example.com",
  "enabledVerificationProfiles": ["a", "c"]
}

You send	Result
`["a"]`	The customer is evaluated against profile A only.
`["a", "c"]`	The customer is evaluated against A and C. Shared requirements are satisfied once for both.
Field omitted	The customer is enrolled in every profile your application is enabled for at the time of creation. Profiles SpherePay enables for you later are not added.
`["d"]` without `c`	Rejected — profile D requires profile C on the same customer. Send `["c", "d"]`, or add `d` to a customer that already has `c`.
`[]`	Rejected — a customer must have at least one profile.
A letter not enabled for your application	Rejected with `customer/verification-profile-family-not-enabled-for-application`.
A letter repeated	Rejected as a validation error.

SpherePay recommends always sending an explicit array. It makes the customer’s enrolment visible in your own records and independent of later changes to your application’s configuration.

The set of profiles your application can use is configured by SpherePay. To request an additional profile for your application, contact support@spherepay.co.

What the API returns

GET /v2/customer/{id} returns two related fields:

enabledVerificationProfiles — the profiles the customer is enrolled in, always as an explicit array. If you omitted the field at creation, this is the set your application was enabled for at that moment.
verificationProfiles — the profiles actually being evaluated, each with a status and criteria. Selecting a profile does not guarantee it appears here: a profile the customer is not eligible for is left out (see below).

Country eligibility

Eligibility follows the customer’s country of residence (address.country). US residents can use profile A only. Non-US residents can use profile A, C and D. A selected profile the customer is not eligible for is left out of verificationProfiles; if none of the selected profiles applies, the request is rejected.

Customer residence	Profile A	Profile C	Profile D
United States	✓	—	—
Outside the United States	✓	✓	✓

A US resident created with ["a", "c"] is accepted, but only kyc_profile_a appears in verificationProfiles.
A US resident created with ["c"] or ["d"] is rejected with 422 customer/verification-profile-not-enabled, because no selected profile applies.

Changing the selection later

Send the full new array in PATCH /v2/customer/{id}. Omitting the field leaves the selection unchanged.

Adding a profile exposes its outstanding requirements in criteria.required on the new profile. Requirements already satisfied for another profile are carried over as complete. See Add a profile later.
Removing a profile is allowed only while that profile is incomplete. See Remove a profile.

Adding a profile never re-reviews the customer’s existing profiles. Fields those profiles already evaluated stay locked while they are pending or approved — see When customer data can be updated.

Business customers

Set enabledVerificationProfiles on the business when you create it. Every business representative you add is evaluated against the same profiles, as ubo_kyc_profile_*; representatives do not carry their own selection. Changing a business’s selection after creation is not yet supported through PATCH. Contact your SpherePay representative if an existing business needs a new profile.

Error reference

Code	HTTP	Meaning
`customer/verification-profile-family-not-enabled-for-application`	422	The array names a profile your application is not enabled for.
`customer/verification-profile-not-enabled`	422	None of the selected profiles applies to this customer, for example a US resident selecting only C or D.
`validation/failed`	422	The array is empty, contains duplicates, contains an unknown letter, or includes `d` without `c`.
`customer/field-locked-by-verification-profile`	400	A field, document or profile removal is locked by a profile that is `pending` or `approved`. The body lists each locked item. See When customer data can be updated.
`customer/operation-not-allowed`	400	Business customers only: the selection cannot be changed after creation yet.

Verification profiles overview

Which profiles exist, what each requires and unlocks.

Onboard a customer with profiles

Choose profiles at creation and add one later.

Onboarding

Transfers

Automation

Webhooks

Reference data

Operational

Selecting Verification Profiles

The field

What the API returns

Country eligibility

Changing the selection later

Business customers

Error reference

Verification profiles overview

Onboard a customer with profiles

​The field

​What the API returns

​Country eligibility

​Changing the selection later

​Business customers

​Error reference

​Related guides

Verification profiles overview

Onboard a customer with profiles

The field

What the API returns

Country eligibility

Changing the selection later

Business customers

Error reference

Related guides