Sub-Account Onboarding V3

This guide is for Atlas for Platform. Every client you onboard becomes a sub-account under your parent account. Verto carries out full KYB and KYC on each client, so you need to collect the information and documents below from them, then submit them through the API. This guide covers what to collect, how to submit it, and what happens next.

📘

You can save your client's information in as many API calls as you like. Nothing is reviewed until you submit the application, and you can only submit once every required item is in place.


How onboarding works

  1. Create the sub-account. This sets up a record for your client.
  2. Add their information and documents. Everything in Part 1 below.
  3. Check the application. Verto tells you what's missing or wrong before you submit.
  4. Submit for review. Verto's compliance team reviews the application, usually within 2 working days (up to 5 for high-risk industries).

Once the application is approved, a director at your client accepts Verto's Terms & Conditions and the sub-account becomes active. Until then, wallets, FX trades and payouts are locked.


Part 1: What to collect from your client

Use this part to build your client form. These are the business rules, whichever way you send the data.

1. About the business

What we needDetails
Legal business nameExactly as it appears on the certificate of incorporation
Country of registrationThe country where the business is legally incorporated
Registration numberThe number issued by the local registry, for example CAC (Nigeria), BRS (Kenya) or Companies House (UK)
Tax IDA tax ID, VAT number or EIN. Required if the business is registered in the UAE, the US or South Africa. Optional everywhere else
Company typeThe legal entity type, from Verto's supported list. For example Private Limited Company, LLC, Partnership or Sole Proprietorship
IndustryMust match Verto's supported industries list exactly, including spelling and capitalisation
Registered addressThe full registered address: street, city, state, postal code and country
Operating or trading addressThe trading address, if it's different. If it's the same, we need that confirmed
What the business doesA description of 300 to 1,000 characters: what it does, who it serves and how it will use Verto. If the business has no online presence, it must also cover the three questions below
Date of incorporationThe date the company was registered. If it's less than 6 months ago, you need different documents (see "New businesses")
Website or online presenceSee the rule below

The online presence rule. We need one of these:

  • The business's official website.
  • Links to official social media or corporate profiles, such as LinkedIn, Facebook or an industry directory.

If the business has no online presence, do this instead:

  1. Answer these three questions in the business description: Does the business sell from a physical location? How does it market itself? How do new customers find it?
  2. Upload a contract or invoice that shows recent business activity, for example a signed client contract or a recent invoice.

Include the answers in the description. Don't send them as separate fields.

2. Directors and owners

Who we need. We need details for:

  • Every individual who owns or controls 25% or more of the business, directly or indirectly.
  • At least one director. A director can also be an owner.

The 25% threshold is the usual one, but it's lower in some cases. It's 5% for South Africa and Tanzania, and 10% for some high-risk industries. Check the figure for your client's country and industry.

For each person we need:

What we needDetails
Full legal nameAs shown on their official ID
Date of birth
Nationality
Percentage owned
Is this person a director?Yes or no
Email addressRequired for at least one director. Verto sends the Terms & Conditions to a director
Home addressThe full residential address
⚠️

Every application needs at least one director with a valid email address. This is true whatever their ownership percentage. Without one, the application can't go to review or reach Terms & Conditions acceptance.

Special cases

If...Then we also need
The business is registered in the UAEAt least one person marked as an authorised signatory
A director or owner has Nigerian nationalityTheir BVN (Bank Verification Number) and their NIN (National Identification Number), at submission. This applies whatever country the business is registered in, and both are required from day one
An owner is a company, not a personIts name, entity type, registration number, ownership percentage and how it holds its stake (directly or indirectly), plus its own ownership documents
An owner is under 18Their legal guardian's ID and the minor's birth certificate. The minor's own passport isn't accepted. Contact your Verto onboarding team, as this goes through an exception process

3. Risk questions

Ask your client all six questions.

QuestionHow they answerOptions
How much money do you expect to receive each month?Choose one$0–$9.9K, $10K–$49.9K, $50K–$99.9K, $100K–$249.9K, $250K–$499.9K, $500K–$749.9K, $750K–$999.9K, $1M–$1.49M, $1.5M–$1.99M, $2M–$2.49M, More than $2.5M
How much money do you expect to send each month?Choose oneThe same options as above
How will you receive money into your account?Choose one or moreMy own bank account, Other businesses, Both
Which countries will you receive money from?Choose one or moreA list of countries
Which countries will you send money to?Choose one or moreA list of countries
What are your transactions for?Choose one or morePaying or receiving from clients, Paying suppliers or vendors, Staff or contractor payments, Business operations or expansion, Internal company transfers, Grants or donations, Currency advantage

4. Documents

You upload each document as a file. You don't choose a document type. Verto classifies every document automatically. Documents must be clear and readable, and dated where stated below. If a document has a different name in your client's country, send the local equivalent.

To see exactly which documents a particular client needs, call Get documents to submit for their sub-account. It lists them based on the client's country and industry.

Documents for every business

DocumentExamples
Certificate of incorporation or business registrationAn official government-issued document confirming the business is legally registered
Memorandum and Articles of Association, or equivalentGoverning documents, bylaws or an operating agreement
Register of shareholders or ownership structureA shareholder register or cap table that shows who owns the business, including anyone owning or controlling 25% or more (5% or more in South Africa)
Proof of business address, dated within the last 3 monthsA corporate bank statement, utility bill, tenancy agreement or phone bill. In Kenya, a KRA PIN certificate. In the UK, an HMRC letter

Proof that the business is trading

Send at least two of these four:

  • A corporate bank statement showing active transactions, for example 3 months of history.
  • Vendor or supplier invoices.
  • Client agreements or contracts.
  • Recent tax returns or audited financial statements.

If the business relies on a related entity's proof of operations, also send an official shareholding structure or a certified group chart to show the relationship.

New businesses (incorporated less than 6 months ago)

Send these instead of proof of trading: one primary and one secondary item.

TypeExamples
PrimaryEquity or investment funding evidence (term sheets, share subscription agreements, investor letters of commitment), an accelerator or incubator acceptance letter or funding agreement (for example Y Combinator, Techstars or Seedcamp), or a crowdfunding campaign completion certificate or platform-issued funding summary
SecondaryA business plan, staff contracts, investor agreements, infrastructure invoices, or a freelancer marketplace profile

Regulated industries (financial services, healthcare, gaming, telecoms, petroleum and similar)

  • Copies of active operating licences or permits required by the relevant regulators.
  • An AML (anti-money laundering) policy, which is mandatory for every business engaged in financial services.

Documents for each director and owner

DocumentWhat's accepted
Proof of identity. One ofA valid passport, a national ID card, a driving licence (front and back), a resident permit or a government ID
Proof of residential address, dated within the last 3 months. One ofA utility bill (water, electricity or home internet), a personal bank statement, a NIN slip, a driving licence, a voter's card or a mobile phone bill
📘

You may not need to upload ID yourself. When you give an email address for a person, Verto sends them a secure link to complete their identity check directly. If they complete it, you don't need to upload their ID. If they don't, you'll need to.

Directors or owners who live in Kenya. If someone can't provide a standard proof of residential address, accept one of these instead:

  • A CR8, for directors only. Send it with one standard document and a signed confirmation that the address is still current.
  • A KRA e-Return dated within the last 12 months. It's accepted on its own only if it shows a specific street, plot or building address. Otherwise, a second document is needed within 30 days.
  • A tenancy agreement, together with a recent (3-month) rent payment receipt paid directly to the named landlord or agent.

5. Quick checklist by situation

SituationWhat to add
Every clientPart 1 sections 1 to 4: business details, directors and owners, risk answers, business documents, proof of trading, and ID and address for each person
No website or social profileThe three questions in the description, plus a contract or invoice
Regulated industryOperating licence(s) or permit(s)
Financial servicesLicence(s), plus an AML policy
Incorporated under 6 months agoOne primary and one secondary item, instead of proof of trading
Registered in the UAEAn authorised signatory, and a tax ID
Registered in South AfricaOwners from 5%, and a tax ID. See the developer reference for the South Africa-only fields
Registered in the USA tax ID
Nigerian director or ownerBVN and NIN for that person
Kenyan resident without a standard address proofAn approved alternative (see above)
A company owns part of the clientThat company's details and ownership documents
An owner under 18Contact your Verto onboarding team

Part 2: How to submit

Step 1: Create the sub-account

Call Create a sub-account with the legal name, country of registration, registration number, tax ID (where required) and industry, and set accountType to PARTNER_REFERRED. See Sub-account creation. The response gives you the sub-account's companyId. You'll use it in every later step. You can also find it with Get all Sub-Accounts.

Step 2: Add your client's information

Send everything from Part 1 with Add or update onboarding data.

  • Send only what you want to add or change, in one call or several. The exception is the list of products, which replaces the whole list each time.
  • Saving never submits the application. Each save also starts Verto's background checks.
  • The response shows the application as it now stands, including its status (IN_PROGRESS while it's being filled in, then APPROVED or REJECTED) and a progress percentage per section. Use Get submission checks, not progress, to decide what still needs fixing.

Uploading documents. Every upload link uses the same document type ID, and Verto works out each document's type.

EnvironmentdocumentTypeId to use
Production6afdef2dadee2542525466c8
Sandbox6afdef077f6d25ef6d8b3d6e
  1. Get an upload link. Call Generate Upload Link with the fileName (including its extension) and the documentTypeId. It returns a temporary upload link and a document key.
  2. Upload the file. PUT the file to that link.
  3. Attach it. Add the document key as the link, plus the country that issued it where relevant. Leave out typeId: Verto then starts reading the document straight away, and Get submission checks shows it as still being read until it's done. Use companyDocuments for the business, or shareholderDocuments for a specific person.

Step 3: Check the application

Call Get submission checks with tier=TIER_2. It lists every issue still open.

SeverityWhat it meansExamples
BLOCKINGFix it before you can submitFIELD_MISSING, FIELD_INVALID, DOCUMENT_MISSING, DIRECTOR_REQUIRED, SIGNATORY_REQUIRED, OWNER_REQUIRED, COUNTRY_NOT_SUPPORTED
WARNINGAdvisory only. It won't block you but it can delay reviewVERIFICATION_PENDING, DOCUMENT_TYPE_MISMATCH, DOCUMENT_EXPIRED, DOCUMENT_UNREADABLE, DATA_MISMATCH

Fix anything open with another save, then check again. Verto's background checks analyse your documents and data after every save. Call Get submission checks again until its status is COMPLETED before you submit.

📘

Use TIER_2. TIER_1 isn't supported for sub-accounts at this time.

Step 4: Submit

When there are no BLOCKING issues and you've reviewed every WARNING, call Submit application. If a BLOCKING issue remains, the request is rejected with a 422.


After you submit

Verto's compliance team reviews standard applications within 2 working days, and applications in high-risk industries within up to 5 working days. If they need more information, they email you a request for information (RFI).

📘

Sandbox. In sandbox, sub-accounts that need full KYB go through Verto's real review process, so you can see how it works end to end.

When the application is approved:

  1. Call Send T&C email with the email address and the shareholderId of the director who should receive Verto's Terms & Conditions. The email goes to the address you send in the request, not automatically to the director's saved email, and that director must already be approved by Verto.
  2. The director accepts the Terms & Conditions. This gives your platform permission to operate the account.
  3. Call Sub-Account Login to authenticate as the sub-account. You can now create wallets, receive funds, convert currency and make payouts.

Statuses

Where you'll see itValueMeaning
Application statusIN_PROGRESSThe application is being filled in
APPROVEDVerto has approved the application
REJECTEDVerto has rejected the application
Sub-account companyStatusCREATEDThe sub-account exists and onboarding data hasn't been submitted
APPROVEDThe application is approved
REJECTEDThe sub-account has been rejected
linkedStatusPENDINGApproved, waiting for the director to accept Terms & Conditions
ACCEPTEDThe director has accepted. The sub-account is fully active

Part 3: Developer reference

Each call uses your Verto Bearer JWT in the Authorization header. The hosts below are production. For sandbox, replace beta with sandbox. See URLs (Sandbox vs Production). Sending a request to the wrong environment returns a 403.

Endpoints

StepEndpointKey inputsNotes
CreatePOST /sub-accountsName, country, registration number, tax ID, industry, accountType: PARTNER_REFERREDReturns the companyId
DocumentsGET /companies/{companyId}/documentsToSubmit (onboarding host)The documents the sub-account needs, with the ID for each
UploadGenerate Upload LinkfileName, documentTypeIdReturns an upload link and a document key
SavePOST /companies/{companyId}/onboarding-data (onboarding host)Any of the parts below200, 400 for an invalid payload, 401 if unauthorised
ReadGET /companies/{companyId}/onboarding-dataIncludes each shareholder's id
CheckGET /companies/{companyId}/onboarding-data/checksQuery tier=TIER_2400 invalid tier, 404 not a sub-account, 409 KYC level 0 sub-account (submission not required)
SubmitPOST /companies/{companyId}/onboarding-data/submit422 if a BLOCKING issue remains
T&C emailPOST /sub-accounts/{subCompanyId}/tnc/send-email (company host)email, shareholderIdThe sub-account must be APPROVED. The shareholder must be an active, approved director
LoginPOST /sub-accounts/{subCompanyId}/login (company host)Returns the sub-account token. 403 if rejected or archived

The onboarding host is https://api-onboarding-beta.vertofx.com, and the company host is https://api-company-beta.vertofx.com.

What you can send when saving

PartWhat it holdsPer request
selectedProductsThe Verto products the sub-account wantsReplaces the whole list
companyThe business's own detailsOnly the fields you send change
companyAddressesRegistered address and, if different, operating addressUp to 2, matched by address type
shareholdersDirectors, shareholders, owners and authorised signatoriesUp to 5 changes, matched by id
companyDocumentsDocuments about the businessUp to 5 changes
shareholderDocumentsDocuments for a specific personUp to 5 changes
riskAssessmentAnswers to the risk questionsOne entry per question

Addresses, shareholders and documents each take an action: ADD, UPDATE, DELETE (approved or in-review documents can't be deleted), and for shareholders ARCHIVE and UNARCHIVE.

Allowed selectedProducts values: Collect, Convert, Pay, Hold, API, Business Accounts, FX, Expense Management, Core API, Invoice Payment, Treasury Management.

Where each business rule goes

What you collectField
Legal name, country, registration number, tax IDname, country, identificationNumber, taxIdOrEin (at creation)
IndustrysubCategory (at creation), and company.category and company.subCategory
Company typecompany.type
Registered and operating addresscompanyAddresses[] with type of COMPANY_ADDRESS or OPERATING_ADDRESS
What the business doescompany.description (300 to 1,000 characters)
Date of incorporationcompany.incorporationDate (YYYY-MM-DD)
Website and other profilescompany.website, company.socialMediaLinks[] as { platform, url } (lower-case platform)
Licencecompany.licensedCountry and company.licensedType, sent together
Trading name, employees, officescompany.tradingName, company.numberOfEmployees, company.countriesOfOffice (optional)
Prohibited activitiescompany.prohibitedActivities (leave empty if none; if anything is sent, the application can't be submitted)
Confirmationscompany.screenerConfirmedAt and company.authorisedConfirmed: true (both required)
Person's name, birth date, nationalityshareholders[].data.firstName, lastName, dateOfBirth, nationality
Percentage ownedshareholders[].data.percentOwnershipInCompany
Directorshareholders[].data.isControllingOfficer and shareholderRole (for example Director)
Email and phoneshareholders[].data.email, countryCallingCode, phoneNumber
Home addressshareholders[].data.address with type: HOME_ADDRESS
UAE authorised signatoryshareholders[].isAuthorisedSignatory
Nigerian BVN and NINshareholders[].idNumbers.bvn and idNumbers.nin_v2
Company that owns part of the clientownerType: CORPORATE with businessName, businessEntityType, businessRegistrationNumber, percentOwnershipInCompany, ownershipTopology
Risk answersriskAssessment[] with questionId and answer. See Risk Assessment Question IDs

South Africa only: incomeClassification (Active NFE, Passive NFE or Financial Institution) is required. giin is needed for a Financial Institution unless you give giinExplanation. ownershipControlAssessment is required before a South African application can be submitted.

UAE only: trnVerification records whether the business holds a Tax Registration Number (TRN) and, if so, the number.

Example request

{
  "selectedProducts": ["Convert", "Pay"],
  "company": {
    "name": "Acme Logistics Ltd",
    "description": "A 300 to 1,000 character description of what the business does, who it serves and how it will use Verto.",
    "category": "Business Services",
    "subCategory": "Advertising Services",
    "type": "Private Limited Company",
    "incorporationDate": "2022-05-14",
    "identificationNumber": "12345678",
    "website": "www.example.com",
    "prohibitedActivities": [],
    "screenerConfirmedAt": "2026-11-02T09:00:00Z",
    "authorisedConfirmed": true
  },
  "companyAddresses": [
    {
      "action": "ADD",
      "type": "COMPANY_ADDRESS",
      "data": {
        "addressLine1": "100 Currency Way",
        "addressLine2": "Suite 400",
        "city": "London",
        "state": "Greater London",
        "zipCode": "EC1A 1BB",
        "country": "United Kingdom"
      }
    }
  ],
  "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"
        }
      }
    }
  ],
  "companyDocuments": [
    {
      "action": "ADD",
      "data": {
        "link": "document-key-from-upload-link",
        "country": "United Kingdom"
      }
    }
  ],
  "riskAssessment": [
    {
      "questionId": "question-id-from-risk-assessment-page",
      "answer": "Single answer text"
    },
    {
      "questionId": "another-question-id",
      "answer": ["Option one", "Option two"]
    }
  ]
}

Need help?

If you have questions about your integration or need support, contact our enterprise API support team at [email protected] or reach out to your account manager directly.


Did this page help you?