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
- Create the sub-account. This sets up a record for your client.
- Add their information and documents. Everything in Part 1 below.
- Check the application. Verto tells you what's missing or wrong before you submit.
- 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 need | Details |
|---|---|
| Legal business name | Exactly as it appears on the certificate of incorporation |
| Country of registration | The country where the business is legally incorporated |
| Registration number | The number issued by the local registry, for example CAC (Nigeria), BRS (Kenya) or Companies House (UK) |
| Tax ID | A tax ID, VAT number or EIN. Required if the business is registered in the UAE, the US or South Africa. Optional everywhere else |
| Company type | The legal entity type, from Verto's supported list. For example Private Limited Company, LLC, Partnership or Sole Proprietorship |
| Industry | Must match Verto's supported industries list exactly, including spelling and capitalisation |
| Registered address | The full registered address: street, city, state, postal code and country |
| Operating or trading address | The trading address, if it's different. If it's the same, we need that confirmed |
| What the business does | A 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 incorporation | The date the company was registered. If it's less than 6 months ago, you need different documents (see "New businesses") |
| Website or online presence | See 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:
- 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?
- 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 need | Details |
|---|---|
| Full legal name | As shown on their official ID |
| Date of birth | |
| Nationality | |
| Percentage owned | |
| Is this person a director? | Yes or no |
| Email address | Required for at least one director. Verto sends the Terms & Conditions to a director |
| Home address | The 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 UAE | At least one person marked as an authorised signatory |
| A director or owner has Nigerian nationality | Their 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 person | Its 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 18 | Their 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.
| Question | How they answer | Options |
|---|---|---|
| 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 one | The same options as above |
| How will you receive money into your account? | Choose one or more | My own bank account, Other businesses, Both |
| Which countries will you receive money from? | Choose one or more | A list of countries |
| Which countries will you send money to? | Choose one or more | A list of countries |
| What are your transactions for? | Choose one or more | Paying 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
| Document | Examples |
|---|---|
| Certificate of incorporation or business registration | An official government-issued document confirming the business is legally registered |
| Memorandum and Articles of Association, or equivalent | Governing documents, bylaws or an operating agreement |
| Register of shareholders or ownership structure | A 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 months | A 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.
| Type | Examples |
|---|---|
| Primary | Equity 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 |
| Secondary | A 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
| Document | What's accepted |
|---|---|
| Proof of identity. One of | A 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 of | A 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
| Situation | What to add |
|---|---|
| Every client | Part 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 profile | The three questions in the description, plus a contract or invoice |
| Regulated industry | Operating licence(s) or permit(s) |
| Financial services | Licence(s), plus an AML policy |
| Incorporated under 6 months ago | One primary and one secondary item, instead of proof of trading |
| Registered in the UAE | An authorised signatory, and a tax ID |
| Registered in South Africa | Owners from 5%, and a tax ID. See the developer reference for the South Africa-only fields |
| Registered in the US | A tax ID |
| Nigerian director or owner | BVN and NIN for that person |
| Kenyan resident without a standard address proof | An approved alternative (see above) |
| A company owns part of the client | That company's details and ownership documents |
| An owner under 18 | Contact 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_PROGRESSwhile it's being filled in, thenAPPROVEDorREJECTED) and aprogresspercentage per section. Use Get submission checks, notprogress, 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.
| Environment | documentTypeId to use |
|---|---|
| Production | 6afdef2dadee2542525466c8 |
| Sandbox | 6afdef077f6d25ef6d8b3d6e |
- Get an upload link. Call Generate Upload Link with the
fileName(including its extension) and thedocumentTypeId. It returns a temporary upload link and a document key. - Upload the file.
PUTthe file to that link. - Attach it. Add the document key as the
link, plus thecountrythat issued it where relevant. Leave outtypeId: Verto then starts reading the document straight away, and Get submission checks shows it as still being read until it's done. UsecompanyDocumentsfor the business, orshareholderDocumentsfor a specific person.
Step 3: Check the application
Call Get submission checks with tier=TIER_2. It lists every issue still open.
| Severity | What it means | Examples |
|---|---|---|
| BLOCKING | Fix it before you can submit | FIELD_MISSING, FIELD_INVALID, DOCUMENT_MISSING, DIRECTOR_REQUIRED, SIGNATORY_REQUIRED, OWNER_REQUIRED, COUNTRY_NOT_SUPPORTED |
| WARNING | Advisory only. It won't block you but it can delay review | VERIFICATION_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.
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:
- Call Send T&C email with the email address and the
shareholderIdof 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. - The director accepts the Terms & Conditions. This gives your platform permission to operate the account.
- 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 it | Value | Meaning |
|---|---|---|
Application status | IN_PROGRESS | The application is being filled in |
APPROVED | Verto has approved the application | |
REJECTED | Verto has rejected the application | |
Sub-account companyStatus | CREATED | The sub-account exists and onboarding data hasn't been submitted |
APPROVED | The application is approved | |
REJECTED | The sub-account has been rejected | |
linkedStatus | PENDING | Approved, waiting for the director to accept Terms & Conditions |
ACCEPTED | The 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
| Step | Endpoint | Key inputs | Notes |
|---|---|---|---|
| Create | POST /sub-accounts | Name, country, registration number, tax ID, industry, accountType: PARTNER_REFERRED | Returns the companyId |
| Documents | GET /companies/{companyId}/documentsToSubmit (onboarding host) | The documents the sub-account needs, with the ID for each | |
| Upload | Generate Upload Link | fileName, documentTypeId | Returns an upload link and a document key |
| Save | POST /companies/{companyId}/onboarding-data (onboarding host) | Any of the parts below | 200, 400 for an invalid payload, 401 if unauthorised |
| Read | GET /companies/{companyId}/onboarding-data | Includes each shareholder's id | |
| Check | GET /companies/{companyId}/onboarding-data/checks | Query tier=TIER_2 | 400 invalid tier, 404 not a sub-account, 409 KYC level 0 sub-account (submission not required) |
| Submit | POST /companies/{companyId}/onboarding-data/submit | 422 if a BLOCKING issue remains | |
| T&C email | POST /sub-accounts/{subCompanyId}/tnc/send-email (company host) | email, shareholderId | The sub-account must be APPROVED. The shareholder must be an active, approved director |
| Login | POST /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
| Part | What it holds | Per request |
|---|---|---|
selectedProducts | The Verto products the sub-account wants | Replaces the whole list |
company | The business's own details | Only the fields you send change |
companyAddresses | Registered address and, if different, operating address | Up to 2, matched by address type |
shareholders | Directors, shareholders, owners and authorised signatories | Up to 5 changes, matched by id |
companyDocuments | Documents about the business | Up to 5 changes |
shareholderDocuments | Documents for a specific person | Up to 5 changes |
riskAssessment | Answers to the risk questions | One 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 collect | Field |
|---|---|
| Legal name, country, registration number, tax ID | name, country, identificationNumber, taxIdOrEin (at creation) |
| Industry | subCategory (at creation), and company.category and company.subCategory |
| Company type | company.type |
| Registered and operating address | companyAddresses[] with type of COMPANY_ADDRESS or OPERATING_ADDRESS |
| What the business does | company.description (300 to 1,000 characters) |
| Date of incorporation | company.incorporationDate (YYYY-MM-DD) |
| Website and other profiles | company.website, company.socialMediaLinks[] as { platform, url } (lower-case platform) |
| Licence | company.licensedCountry and company.licensedType, sent together |
| Trading name, employees, offices | company.tradingName, company.numberOfEmployees, company.countriesOfOffice (optional) |
| Prohibited activities | company.prohibitedActivities (leave empty if none; if anything is sent, the application can't be submitted) |
| Confirmations | company.screenerConfirmedAt and company.authorisedConfirmed: true (both required) |
| Person's name, birth date, nationality | shareholders[].data.firstName, lastName, dateOfBirth, nationality |
| Percentage owned | shareholders[].data.percentOwnershipInCompany |
| Director | shareholders[].data.isControllingOfficer and shareholderRole (for example Director) |
| Email and phone | shareholders[].data.email, countryCallingCode, phoneNumber |
| Home address | shareholders[].data.address with type: HOME_ADDRESS |
| UAE authorised signatory | shareholders[].isAuthorisedSignatory |
| Nigerian BVN and NIN | shareholders[].idNumbers.bvn and idNumbers.nin_v2 |
| Company that owns part of the client | ownerType: CORPORATE with businessName, businessEntityType, businessRegistrationNumber, percentOwnershipInCompany, ownershipTopology |
| Risk answers | riskAssessment[] 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.
Updated 1 day ago

