Sub-account Onboarding

This guide details how to programmatically submit compliance and onboarding data for a sub-account using the Verto API.

This guide is specifically for Atlas for Platform use cases, and the specific API endpoint can be reviewed here

📘

Sub Account onboarding under Atlas for Platforms requires full KYC/KYB of the underlying customer. We require that you pass the documentaion as per requirements of Verto.

Kindly note that ALL operational activity (creating wallets, FX trades, payouts etc) is restricted for the specific sub account until this data is submitted, reviewed, and approved.

Before you Pass Onboarding Data:

1. Create the sub-account via the Create Sub-account Endpoint.
2. Identify and extract the companyId of the created sub-account from response object of the Create Sub-account endpoint above, or Get All Sub-accounts endpoint.

Endpoint Overview

• Method: POST
• URL: https://api-onboarding-sandbox.vertofx.com/companies/{companyId}/onboarding-data
• Headers: Content-Type: application/json (Along with your standard Verto Authorization tokens)

Path Parameters

• companyId (string, Required): The unique identifier for the company being onboarded. This is retrieved from the response object of the Create Sub-account endpoint above, or Get All Sub-accounts endpoint.

Core Request Architecture

The request payload accepts complex, nested objects to handle company details, physical addresses, corporate documentation, and beneficial ownership structural trees.

1. Selected Products

An array of strings identifying which financial products the company wants to enable.

• Allowed Values: Collect, Convert, Pay, Hold, API
• Constraint: Minimum length of 1.

2. Company Details & Addresses

The company object maps corporate registration data. Inside, the companyAddresses array tracks physical locations.

• State Operations: Elements inside array objects require an action key (ADD, UPDATE, or DELETE).
• Address Types: COMPANY_ADDRESS (Registered legal address) or OPERATING_ADDRESS.

3. Shareholders & Ultimate Beneficial Owners (UBOs)

⚠️

Compliance Rule: You must collect and submit comprehensive data for any UBO that holds 25% or more ownership in the company.

The shareholders array handles dynamic models via the ownerType field:

• INDIVIDUAL (Uses ClientIndividualShareholder schema)
• CORPORATE (Uses ClientCorporateShareholder schema)

Complete JSON Payload Example

Below is a production-ready structural example demonstrating how to submit a company selecting two products, providing its registered address, and declaring both a major individual shareholder (UBO) and a corporate holding entity.

{
  "selectedProducts": [
    "Convert",
    "Pay"
  ],
  "company": {
    "type": "Private Limited Company",
    "companyAddresses": [
      {
        "action": "ADD",
        "data": {
          "addressLine1": "100 Currency Way",
          "addressLine2": "Suite 400",
          "city": "London",
          "state": "Greater London",
          "zipCode": "EC1A 1BB",
          "country": "United Kingdom"
        },
        "type": "COMPANY_ADDRESS"
      }
    ]
  },
  "shareholders": [
    {
      "action": "ADD",
      "data": {
        "ownerType": "INDIVIDUAL",
        "firstName": "Jane",
        "lastName": "Doe",
        "email": "[email protected]",
        "percentOwnershipInCompany": 35.5,
        "nationality": "United Kingdom",
        "isControllingOfficer": true,
        "shareholderRole": "Director",
        "dateOfBirth": "1988-11-23",
        "countryCallingCode": "+44",
        "phoneNumber": "7123456789",
        "status": "ACTIVE",
        "address": {
          "addressLine1": "12 Maloko Lane",
          "city": "London",
          "zipCode": "SW1A 1AA",
          "country": "United Kingdom",
          "type": "HOME_ADDRESS"
        },
        "documents": [
          {
            "typeId": "DOC-PASSPORT-01",
            "link": "https://secure-storage.internal/docs/jane_passport.pdf",
            "country": "United Kingdom"
          }
        ]
      }
    },
    {
      "action": "ADD",
      "data": {
        "ownerType": "CORPORATE",
        "businessName": "Acme Holdings Ltd",
        "businessEntityType": "Private Limited Company",
        "businessRegistrationNumber": "12345678",
        "email": "[email protected]",
        "percentOwnershipInCompany": 40.0,
        "ownershipTopology": "DIRECT",
        "nationality": "United Kingdom",
        "status": "ACTIVE",
        "address": {
          "addressLine1": "55 Corporate Blvd",
          "city": "Edinburgh",
          "zipCode": "EH1 1BB",
          "country": "United Kingdom"
        },
        "documents": [
          {
            "typeId": "DOC-CERT-INC-02",
            "link": "https://secure-storage.internal/docs/acme_inc.pdf",
            "country": "United Kingdom"
          }
        ]
      }
    }
  ],
  "companyDocuments": [
    {
      "action": "UPDATE",
      "data": {
        "id": "existing-doc-uuid-111",
        "typeId": "COMP-MEM-ART-09",
        "link": "https://secure-storage.internal/docs/updated_memo.pdf",
        "country": "United Kingdom"
      }
    }
  ]
}

API Lifecycle & Response Validation

Response Status Codes

Post-Submission

Once the 200 OK response is received, the company moves into a Review state. Operational APIs remain locked for transaction handling until the company moves completely out of the pending onboarding pipeline.

Sub-account statuses