Add KYC/KYB Details

To move from PENDING to ACTIVE status, every sub-account must undergo compliance vetting. This guide details how to submit Ultimate Beneficial Owner (UBO) and Business Identity data programmatically.

[!NOTE] The onboarding sections, questions, and document uploads you submit depend on your approved compliance model and level. Do not assume every sub-account must answer every risk question or upload every document at the start of onboarding.

[!IMPORTANT] Who is a UBO? You must provide details for any individual who owns directly or indirectly 25% or more of the company.

🚀 Onboarding Workflow

Submit a structured object containing the company's operational address and shareholder details.

curl -X POST https://api.sandbox.vertofx.com/v2/sub-accounts/{sub_acc_id}/onboarding \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "companyAddresses": [{
      "action": "ADD",
      "data": {
        "addressLine1": "123 Tech Lane",
        "city": "Lagos",
        "country": "Nigeria",
        "type": "COMPANY_ADDRESS"
      }
    }],
    "shareholders": [{
      "action": "ADD",
      "data": {
        "percentOwnershipInCompany": 100,
        "ownerType": "INDIVIDUAL",
        "firstName": "Sola",
        "lastName": "Aina",
        "nationality": "Nigeria",
        "isControllingOfficer": true,
        "dateOfBirth": "1990-05-15",
        "address": {
          "addressLine1": "123 Tech Lane",
          "city": "Lagos",
          "country": "Nigeria",
          "type": "HOME_ADDRESS"
        }
      }
    }]
  }'

📋 Risk Assessment and Document Requirements

The required onboarding payload depends on your approved product model, compliance level, and rollout scope.

Use these rules when you design your onboarding flow:

1. Submit only the sections your approved model requires at that stage.
2. Treat riskAssessment, companyDocuments, and shareholderDocuments as conditional sections, not universal requirements for every integration.
3. Require the fields inside a section only when that section is part of the onboarding submission.
4. Confirm your required onboarding set with your sales contact or account manager before you lock your production workflow.

For lower-complexity setups, including Atlas for Fintech – Level 0, onboarding can begin with a reduced payload. In those cases, do not present all risk questions or document uploads as universally mandatory unless your approved compliance setup explicitly requires them.

When your model requires a risk assessment, each question has a unique id that must be submitted via the Upload Onboarding Data API.

[!TIP] Production vs. Sandbox: Ensure you use the correct IDs for your environment. Sandbox IDs differ from the production IDs listed above to prevent environmental bleed.

📎 How to interpret required onboarding sections

Use the matrix below to separate conditionally required sections from fields that become required once you include that section. The Model guidance column reflects only the rules documented on this page.

📋 Data Schema

Build your onboarding payload in layers. Some sections are conditional, but once you send a section, its internal structure must match the expected compliance primitive.

[!IMPORTANT] Implementation rule Treat onboarding requirements as model-driven, not globally mandatory. Your application should render and validate only the questions, entities, and documents required for the approved compliance level you are implementing.

⚖️ Verification States

Once submitted, the sub-account enters the review queue.

🎯 Next Steps