Onboard a Customer with Verification Profiles

This guide walks through onboarding an individual customer to two verification profiles at once, then adding a profile to a customer who was created with one. For the full list of requirements per profile, see the overview.

Onboard a new customer

The example onboards a Mexican individual to profiles A and C.

Create the customer with the profiles selected

Send every field you already have. Fields required by either profile count once for both.

curl -X POST https://api.spherepay.co/v2/customer \
  -H "Authorization: Bearer $SPHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "firstName": "Ana",
    "lastName": "García",
    "email": "ana.garcia@example.com",
    "phone": "+525551234567",
    "dateOfBirth": "1990-05-15",
    "address": {
      "line1": "Avenida Reforma 222",
      "city": "Ciudad de Mexico",
      "state": "CMX",
      "postalCode": "06600",
      "country": "MEX"
    },
    "enabledVerificationProfiles": ["a", "c"],
    "personalInformation": {
      "nationality": "MEX",
      "countryOfBirth": "MEX",
      "residencyCountry": "MEX",
      "taxIdentificationNumber": "GAAA900515AB1",
      "taxIdentificationNumberType": "rfc",
      "taxIdentificationNumberCountry": "MEX",
      "gender": "female",
      "occupationSocCode": "151252",
      "sourceOfFunds": "salary",
      "accountPurpose": "receive_salary",
      "expectedMonthlyPayments": "5000_9999",
      "employmentStatus": "employed",
      "actingAsIntermediary": false
    }
  }'

Read what each profile still needs

The response lists both profiles as incomplete. Only documents remain.

{
  "id": "customer_244a09f15e254288886e419071c92da6",
  "enabledVerificationProfiles": ["a", "c"],
  "verificationProfiles": [
    {
      "name": "kyc_profile_a",
      "status": "incomplete",
      "criteria": {
        "required": ["identity_document", "liveness_report_document", "source_of_funds_document"]
      }
    },
    {
      "name": "kyc_profile_c",
      "status": "incomplete",
      "criteria": {
        "required": ["identity_document", "proof_of_address_document", "w8_ben_document", "source_of_funds_document", "liveness_report_document"]
      }
    }
  ]
}

Upload the documents

Upload each document type once. A document that appears in required on both profiles satisfies both.

curl -X POST https://api.spherepay.co/v2/document \
  -H "Authorization: Bearer $SPHERE_API_KEY" \
  --form 'target="customer"' \
  --form 'targetId="customer_244a09f15e254288886e419071c92da6"' \
  --form 'documentType="id_card"' \
  --form 'country="MEX"' \
  --form 'side="front"' \
  --form 'file=@id-front.jpg'

Repeat for the back of the ID card and for proof_of_address_document, w8_ben_document, source_of_funds_document and liveness_report_document.

Wait for each profile to be decided

Once every enabled profile has an empty criteria.required, SpherePay submits the customer for review and both profiles move to pending. No submit call is needed. Each profile is decided independently, so poll GET /v2/customer/{id} and act per profile. Or subscribe to customer webhook events: one event fires per profile per status change, with the profile name in data.verificationProfile.

{
  "verificationProfiles": [
    { "name": "kyc_profile_a", "status": "pending" },
    { "name": "kyc_profile_c", "status": "approved" }
  ]
}

The customer can transact on the products profile C unlocks as soon as kyc_profile_c is approved, even while kyc_profile_a is still pending.

Submission waits for every enabled profile. If you select A and C but only supply A’s requirements, neither profile leaves incomplete. Supply the requirements for all selected profiles, or select fewer profiles.

Add a profile later

When a customer created with one profile needs another — for example SpherePay enables profile C for your application and the customer wants to send USD abroad — send the full new array.

Widen the selection

curl -X PATCH https://api.spherepay.co/v2/customer/customer_244a09f15e254288886e419071c92da6 \
  -H "Authorization: Bearer $SPHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabledVerificationProfiles": ["a", "c"] }'

Supply only what the new profile still needs

The new profile appears in verificationProfiles. Fields already supplied for A carry over as complete; documents you already uploaded are re-checked for C and listed in criteria.pending until that finishes. Only the C-specific requirements are required: sex, country_of_birth, nationality, proof_of_address_document and w8_ben_document for a customer who completed A.

curl -X PATCH https://api.spherepay.co/v2/customer/customer_244a09f15e254288886e419071c92da6 \
  -H "Authorization: Bearer $SPHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "personalInformation": {
      "gender": "female",
      "countryOfBirth": "MEX",
      "nationality": "MEX"
    }
  }'

Then upload proof_of_address_document and w8_ben_document as in the previous section.

Wait for the new profile

kyc_profile_c moves to pending on its own and is decided independently. Profile A is not re-reviewed.

This works whether profile A is incomplete, pending or approved. Fields A already evaluated stay locked while A is pending or approved; a PATCH that touches one returns 400 customer/field-locked-by-verification-profile. See When customer data can be updated.

Selecting profiles

What enabledVerificationProfiles accepts and returns.

Remove a profile

Drop a profile the customer no longer needs.

Onboarding

Transfers

Automation

Webhooks

Reference data

Operational

Onboard a Customer with Verification Profiles

Onboard a new customer

Add a profile later

Selecting profiles

Remove a profile

​Onboard a new customer

​Add a profile later

​Related guides

Selecting profiles

Remove a profile

Onboard a new customer

Add a profile later

Related guides