{"openapi":"3.0.3","info":{"title":"Onboarding","version":"1.0","description":"Service for onboarding clients to the Verto platform.","x-logo":{"url":""}},"paths":{"/companies/{companyId}/onboarding-data/checks":{"get":{"x-atlas-api":true,"operationId":"get_submission_checks","x-permission-config":["Client:Basic Access:read","Admin:Onboarding:read"],"tags":["Review & submit"],"summary":"Get submission checks","description":"Use this endpoint to find out whether a sub-account's application is ready to submit. It returns all issues that our internal assessment generates.\n\nThe assessment depends on your Atlas product:\n\n- **Atlas for Platform**: Verto conducts full KYB/KYC on each sub-account directly, so on top of checking that the data is complete, Verto analyses the uploaded documents with AI-powered document analysis covering document age, document type and readability, and data consistency. This analysis runs in the background after each save.\n- **Atlas for Fintech**: Verto places reliance on your compliance framework, so the background analysis runs when the application is submitted rather than during data entry.\n\n> 🚧 **Atlas for Platform: wait for background checks before you submit.**\n>\n> Because the assessment is asynchronous, wait until `status` is `COMPLETED`.\n\n## Where this fits\n\n1. Save the sub-account's information with [Add or update onboarding data](/reference/post_company_onboarding_data).\n2. Call this endpoint to see what is still open.\n3. Fix the issues with another save, then call this endpoint again.\n4. When there are no BLOCKING issues and you have reviewed any WARNING issues, call [Submit application](/reference/post_submit_application).\n\n## Issue severity\n\n| Severity | Effect |\n|---|---|\n| **BLOCKING** | Must be resolved before the application can be submitted. |\n| **WARNING** | Doesn't block submission, but needs review. |\n\nDecide by each issue's `severity`, never by its `code`: the same code can be BLOCKING or WARNING.\n\n> 🚧 **Have someone review WARNING issues before you submit.**\n>\n> WARNING issues don't block submission, but they often point to document problems that delay compliance review.\n\n## Reading the response\n\n| Field | What it tells you |\n|---|---|\n| `companyId`, `reference` | The sub-account these checks are for, and its Verto reference (VU number). |\n| `status` | Where the **background checks** are (not the application's overall status). See the table below. |\n| `targetTier` | The tier the application will be submitted for. `TIER_2` for sub-accounts. |\n| `tiers` | For each tier, whether any BLOCKING issue remains (`submittable` is `true` when none does). |\n| `issues` | Everything still open, BLOCKING and WARNING (only up to the requested tier if you pass `tier`). |\n| `evaluatedAt` | When this response was computed. |\n\n### Background check status\n\n| `status` | Meaning |\n|---|---|\n| `NOT_STARTED` | No background check has run yet; its findings will appear once it does. |\n| `QUEUED` / `IN_PROGRESS` | Background checks are waiting or running. Findings from checks that have completed in this run are included; checks still running don't appear yet, so more WARNING issues may still arrive. |\n| `COMPLETED` | All background checks in the latest run have finished and their findings are included. The list is final until the next save. |\n| `FAILED` | The latest background run could not complete. Findings from checks that did complete in this run are included. Contact [enterpriseapi.support@vertofx.com](mailto:enterpriseapi.support@vertofx.com) if this persists. |\n\n### Each issue\n\n| Field | What it tells you |\n|---|---|\n| `severity` | `BLOCKING` or `WARNING`. See **Issue severity** above. |\n| `code` | What kind of problem it is. See **Possible set of codes** below. |\n| `resource`, `resourceId` | Where the problem is. `company` is the sub-account itself, and `resourceId` is its `companyId`. `shareholder` is one of its directors or owners, and `resourceId` is that shareholder's id. |\n| `field` | Which field to fix. See **Fixing an issue** below. |\n| `tier` | The lowest tier the issue applies to. |\n| `message` | A readable explanation of what to fix. |\n\n## Possible set of codes\n\n`code` tells you what kind of problem an issue is. Use `message` for the specific detail, and expect new codes to be added over time.\n\n| Code | What it means |\n|---|---|\n| `FIELD_MISSING` | A required field is empty. |\n| `FIELD_INVALID` | A field's value isn't valid, for example an identification number in the wrong format. |\n| `DOCUMENT_MISSING` | A required document hasn't been provided. |\n| `DIRECTOR_REQUIRED` | The sub-account needs at least one director with an email address. |\n| `SIGNATORY_REQUIRED` | The sub-account needs an individual authorised signatory. |\n| `OWNER_REQUIRED` | The sub-account needs at least one active shareholder. |\n| `COUNTRY_NOT_SUPPORTED` | Verto can't onboard sub-accounts from this country. Fixable only if the country was entered incorrectly. |\n| `TIER_BELOW_PRODUCTS` | The tier is below what the selected products need. |\n| `VERIFICATION_PENDING` | An identity or address verification hasn't completed yet. |\n| `DOCUMENT_TYPE_MISMATCH` | An uploaded document doesn't appear to be the type required. |\n| `DOCUMENT_EXPIRED` | An uploaded document appears to be expired or too old. |\n| `DOCUMENT_UNREADABLE` | An uploaded document couldn't be read. |\n| `DATA_MISMATCH` | Details in a document don't match the data provided. |\n\n## Fixing an issue\n\n`field` is usually a field name of `POST /companies/{companyId}/onboarding-data`, relative to `resource`. Documents and verification use the slot names below.\n\n- **`company`:** e.g. `identificationNumber`, `incorporationDate`, `authorisedConfirmed`, `description`, `companyAddresses.COMPANY_ADDRESS`, `screenerConfirmedAt`, `riskAssessment.<questionId>`, `ownershipControlAssessment.<questionId>`\n- **`shareholder`:** e.g. `email`, `dateOfBirth`, `nationality`, `address.zipCode`, `idNumbers.bvn`\n- **Verification:** `VERIFICATION_PENDING` issues use `verification.<check>`. Upload the identity or address documents the check needs.\n- **People:** `DIRECTOR_REQUIRED`, `SIGNATORY_REQUIRED` and `OWNER_REQUIRED` use `shareholders`.\n- **Documents:** `documents.<documentType>`, a camelCase slot name, e.g. `documents.certificateOfIncorporation`, `documents.proofOfBusinessAddress`, `documents.shareholdingStructure`, `documents.sourceOfFunds`. The slot's `typeId` comes from `GET /companies/{companyId}/documentsToSubmit`.\n\nSend the missing or corrected data in another save, then call this endpoint again.\n\n## When to submit\n\nOnce there are no BLOCKING issues and you have reviewed any WARNING issues, call [Submit application](/reference/post_submit_application). For Atlas for Platform, wait until `status` is `COMPLETED` first.","parameters":[{"$ref":"#/components/parameters/companyId"},{"name":"tier","in":"query","required":false,"description":"Use `TIER_2`, or omit it; the result is the same. `TIER_1` is not supported at this time. `tiers` is never filtered.","schema":{"type":"string","enum":["TIER_1","TIER_2"],"example":"TIER_2"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"companyId":{"type":"string","description":"The sub-account these checks are for."},"reference":{"type":"string","description":"The sub-account's Verto reference (VU number)."},"status":{"type":"string","enum":["NOT_STARTED","QUEUED","IN_PROGRESS","COMPLETED","FAILED"],"description":"Where the background checks are. See the status table in the description."},"targetTier":{"type":"string","enum":["TIER_1","TIER_2"],"description":"The tier the application will be submitted for when `tier` is omitted. `TIER_2` for sub-accounts."},"tiers":{"type":"array","description":"For each tier, whether any BLOCKING issue remains.","items":{"type":"object","properties":{"tier":{"type":"string","enum":["TIER_1","TIER_2"]},"submittable":{"type":"boolean","description":"True when no BLOCKING issue applies to this tier. Submission can still be refused for other reasons, e.g. it was already submitted."}}}},"issues":{"type":"array","description":"Everything still open, BLOCKING and WARNING (only up to the requested tier if you pass `tier`).","items":{"$ref":"#/components/schemas/SubmissionIssue"}},"evaluatedAt":{"type":"string","format":"date-time","description":"When this response was computed."}}}}}},"400":{"description":"Invalid tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not a sub-account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"KYC level 0 sub-account; submission not required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/companies/{companyId}/onboarding-data/submit":{"post":{"x-atlas-api":true,"operationId":"post_submit_application","x-permission-config":["Client:Basic Access:read","Admin:Onboarding:write"],"tags":["Review & submit"],"summary":"Submit application","description":"Submits the sub-account application for KYB/KYC compliance review. If there are no BLOCKING issues, the application is marked submitted and enters Verto's compliance pipeline for assessment.\n\n> 🚧 **Review WARNING issues before you submit.**\n>\n> WARNING issues, including pending identity verification and background-check findings, don't block submission, but they can delay compliance review. Call [Get submission checks](/reference/get_submission_checks) first and have someone on your team review every WARNING. For Atlas for Platform, wait until its `status` is `COMPLETED`.\n\n> 📘 **Use `TIER_2`, or leave `tier` out.**\n>\n> `tier` defaults to `TIER_2`. `TIER_1` is not supported for sub-accounts at this time and is rejected with a `422`.\n\nBefore calling this endpoint, save all of the sub-account's information with [Add or update onboarding data](/reference/post_company_onboarding_data): its details, directors, shareholders and owners, risk assessment answers and required documents. Incomplete applications will fail submission checks.\n\nIf BLOCKING issues remain (for example, missing mandatory fields, incomplete director information, or required documents not yet uploaded), the submission is rejected with a `422` stating how many BLOCKING issues remain. Call [Get submission checks](/reference/get_submission_checks) for the full list. These must be resolved before the application can be submitted successfully.\n\n## After you submit\n\nReview timelines:\n\n- Standard applications: **2 working days**\n- High-risk industry applications: **up to 5 working days**\n\nIf Verto's compliance team needs more documents or information, they email you a request for information (RFI).\n\n> 📘 **After approval: send the T&C email.**\n>\n> The sub-account isn't fully active until its nominated director accepts Verto's Terms & Conditions. Trigger the email with [Send T&C email](/reference/trigger_email_to_subclient_director).","parameters":[{"$ref":"#/components/parameters/companyId"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique string. A repeat request with the same key returns the original response instead of submitting again.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"tier":{"type":"string","enum":["TIER_1","TIER_2"],"description":"Tier to submit for. Use `TIER_2`, which is also the default when omitted. `TIER_1` is rejected for sub-accounts with a `422`.","example":"TIER_2"}}}}}},"responses":{"200":{"description":"Submitted","content":{"application/json":{"schema":{"type":"object","properties":{"companyId":{"type":"string"},"reference":{"type":"string","description":"The sub-account's Verto reference (VU number)."},"status":{"type":"string","enum":["SUBMITTED"]},"tier":{"type":"string","enum":["TIER_1","TIER_2"]},"submittedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Invalid request body, or a tier above the target tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not a sub-account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"Already submitted, submission in progress, tier already reached, not submittable in this stage, or KYC level 0","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"description":"Blocking issues for the tier, or a tier below the one the selected products need","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/companies/{companyId}/onboarding-data":{"post":{"description":"Use this endpoint to add or change the information Verto needs to onboard one of your sub-accounts: its details, products, addresses, directors and shareholders, documents and risk assessment answers. Send only what you want to add or change (except `selectedProducts`, which replaces the whole list), as often as you need. The response returns the application as it now stands.\n\n> 📘 **Saving does not submit the application.**\n>\n> When everything is in place, check it with [Get submission checks](/reference/get_submission_checks), then call [Submit application](/reference/post_submit_application). For Atlas for Platform, each save also starts Verto's background checks; their findings appear in Get submission checks.\n\n## Where this fits\n\n1. Save the sub-account's information with this endpoint, in one call or several.\n2. Call [Get submission checks](/reference/get_submission_checks) to see what is still missing or needs fixing.\n3. Fix the issues with another save, then check again.\n4. When there are no BLOCKING issues and you have reviewed any WARNING issues, call [Submit application](/reference/post_submit_application).\n\n## What you can send\n\n| Part | What it holds | How it is saved |\n|---|---|---|\n| `selectedProducts` | The Verto products the sub-account wants to use | Replaces the whole list each time |\n| `company` | The sub-account's own details, such as its legal name, registration number and industry | Only the fields you send are changed |\n| `companyAddresses` | The registered address and, if different, the operating address (up to 2 per request) | Matched by address type |\n| `shareholders` | Directors, shareholders, owners and authorised signatories (up to 5 changes per request) | Existing ones are matched by `id` |\n| `companyDocuments` | Documents about the sub-account itself (up to 5 changes per request) | Existing ones are matched by document `id` |\n| `shareholderDocuments` | Documents for a specific director, shareholder, owner or authorised signatory (up to 5 changes per request) | Existing ones are matched by document `id` and `shareholderId` |\n| `riskAssessment` | Answers to Verto's risk assessment questions | Saved per question |\n\n> 🚧 **`selectedProducts` replaces the whole list.**\n>\n> Unlike the other parts, it isn't merged. If you send `selectedProducts`, send every product the sub-account wants; any you leave out are removed.\n\n## Actions\n\nAddresses, shareholders and documents each take an `action`:\n\n| Action | What it does |\n|---|---|\n| `ADD` | Adds a new entry. For addresses, adding a type that already exists replaces it. |\n| `UPDATE` | Changes an existing entry. |\n| `DELETE` | Removes an entry. Documents Verto has approved or is reviewing can't be deleted. |\n| `ARCHIVE` | Sets a director, shareholder or owner aside without removing them. Shareholders only. |\n| `UNARCHIVE` | Brings an archived director, shareholder or owner back. Shareholders only. |\n\n## What you get back\n\nThe application as it now stands: the sub-account's details and addresses, products, directors and shareholders, documents and risk assessment answers, plus:\n\n- `status`: the application's overall status (not the background-check `status` from Get submission checks): IN_PROGRESS while it is being filled in, then APPROVED or REJECTED after Verto's review.\n- `progress`: how complete each section is, as a percentage. To decide what to fix, use Get submission checks rather than `progress`.","x-atlas-api":true,"operationId":"post_company_onboarding_data","x-permission-config":["Client:Basic Access:read","Admin:Onboarding:read"],"tags":["Client"],"parameters":[{"$ref":"#/components/parameters/companyId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientOnboardingRq"}}}},"responses":{"200":{"description":"Successfully updated onboarding data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientOnboardingRs"}}}},"400":{"description":"Invalid request payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Add or update onboarding data"}}},"components":{"securitySchemes":{"JWTAuth":{"x-atlas-api":true,"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Example: \n> Authorization: Bearer <token>"}},"parameters":{"companyId":{"name":"companyId","in":"path","description":"company id","required":true,"schema":{"type":"string"}}},"schemas":{"SubmissionIssue":{"type":"object","properties":{"code":{"type":"string","description":"What kind of problem it is, e.g. FIELD_MISSING or DOCUMENT_EXPIRED. See \"Possible set of codes\" in the description. Use `severity`, not the code, to decide whether the issue blocks submission."},"severity":{"type":"string","enum":["BLOCKING","WARNING"],"description":"BLOCKING must be fixed before the application can be submitted. WARNING is advisory and never blocks submission."},"tier":{"type":"string","enum":["TIER_1","TIER_2"],"description":"The lowest tier the issue applies to."},"resource":{"type":"string","enum":["company","shareholder"],"description":"Where the problem is. `company` is the sub-account itself; `shareholder` is one of its directors or owners."},"resourceId":{"type":"string","description":"The sub-account's `companyId` when `resource` is `company`, or the shareholder's id when it is `shareholder`."},"field":{"type":"string","description":"Which field to fix, using the field names of POST /companies/{companyId}/onboarding-data relative to `resource` (dots for nested fields)."},"message":{"type":"string","description":"A readable explanation of what to fix."}}},"Error":{"required":["message","code"],"type":"object","properties":{"message":{"description":"Required. A plain-English explanation of what went wrong.","type":"string"},"code":{"description":"Required. The error code, which matches the HTTP status code (for example 400).","maximum":1000,"minimum":1,"type":"integer"}},"example":{"code":400,"message":"wrong input"}},"ProblemDetails":{"type":"object","description":"RFC 9457 problem details.","properties":{"type":{"type":"string","description":"URI that identifies the problem, e.g. https://docs.vertofx.com/errors/submission-blocked"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}},"ClientOnboardingRq":{"type":"object","properties":{"selectedProducts":{"$ref":"#/components/schemas/Products"},"company":{"$ref":"#/components/schemas/ClientCompanyRq"},"companyAddresses":{"description":"The sub-account's addresses: its registered address (COMPANY_ADDRESS) and, if different, its operating address (OPERATING_ADDRESS). Up to two entries, one per address type. Submission checks refer to them as companyAddresses.COMPANY_ADDRESS and companyAddresses.OPERATING_ADDRESS.","type":"array","maxItems":2,"items":{"type":"object","required":["action","data"],"properties":{"action":{"$ref":"#/components/schemas/PostAction"},"data":{"$ref":"#/components/schemas/ClientCompanyAddress"}}}},"shareholders":{"description":"The sub-account's directors, shareholders, owners and authorised signatories, both individuals and corporate entities. Up to five changes per request.","type":"array","maxItems":5,"items":{"type":"object","required":["action","data"],"properties":{"action":{"$ref":"#/components/schemas/PostAction"},"data":{"$ref":"#/components/schemas/ClientShareholder"}}}},"companyDocuments":{"description":"Documents about the sub-account itself, such as its certificate of incorporation or proof of address. Up to five changes per request.","type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/ApiClientCompanyDocumentPostRq"}},"shareholderDocuments":{"description":"Documents for a specific director, shareholder, owner or authorised signatory, such as an ID or proof of address. Up to five changes per request.","type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/ApiClientShareholderDocumentPostRq"}},"riskAssessment":{"$ref":"#/components/schemas/RiskAssessment"}}},"ClientOnboardingRs":{"type":"object","allOf":[{"$ref":"#/components/schemas/AuditableBaseObj"},{"type":"object","properties":{"companyId":{"type":"string","description":"The sub-account's ID. This is the same companyId you used in the request path.","example":"2"},"parentCompanyId":{"type":"string","description":"Your own account ID as the partner that owns this sub-account. Omitted if the account is not a sub-account.","example":"1"},"selectedProducts":{"$ref":"#/components/schemas/Products"},"company":{"$ref":"#/components/schemas/ClientCompanyRs"},"shareholders":{"description":"All directors, shareholders, owners and authorised signatories on the application, people and entities alike. Archived ones are included with status ARCHIVED.","type":"array","items":{"$ref":"#/components/schemas/ClientShareholder"}},"progress":{"$ref":"#/components/schemas/OnboardingProgressArray"},"status":{"$ref":"#/components/schemas/OnboardingStatus"},"companyDocuments":{"description":"The documents uploaded for the sub-account itself, with each document's review status.","type":"array","items":{"$ref":"#/components/schemas/ApiClientCompanyDocumentPostRq"}},"riskAssessment":{"$ref":"#/components/schemas/RiskAssessment"},"kycLevel":{"description":"Response only. The verification level set for the sub-account: '0' means the sub-account does not go through a full Verto review, '3' means it does and the application must be submitted for review.","readOnly":true,"type":"string","enum":["0","3"]}}}]},"Products":{"description":"A list of one or more Verto product names the sub-account wants to use, for example Business Accounts or Expense Management.","type":"array","items":{"type":"string","enum":["Collect","Convert","Pay","Hold","API","Business Accounts","FX","Expense Management","Core API","Invoice Payment","Treasury Management"]},"minItems":1,"example":["Business Accounts","Expense Management","Core API"]},"ClientCompanyRq":{"description":"The sub-account's own details, such as its legal name, registration number, industry and contact details. In a request, only the fields you include are changed.","type":"object","properties":{"name":{"description":"Legal name of the sub-account, exactly as it appears on its registration documents. Required before the application can be submitted. If you leave tradingName empty, this name is also used as the trading name.","type":"string","example":"Verto"},"email":{"readOnly":true,"description":"Response only. The sub-account's registered email address. You cannot change it with this request.","type":"string","example":"client@vertofx.com"},"reference":{"readOnly":true,"description":"Response only. Verto's reference for the sub-account (for example VU-11022013-01). Quote it when you contact Verto about this application.","type":"string","example":"VU-11022013-01"},"description":{"description":"A plain description of what the sub-account does, who it serves and how it will use Verto. Required before the application can be submitted, and must be 300 to 1,000 characters.","type":"string","example":"Simplifying cross border payments"},"countryCallingCode":{"readOnly":true,"description":"Response only. International dialling code of the sub-account's phone number, for example +44.","type":"string","example":"+44"},"phoneNumber":{"readOnly":true,"description":"Response only. The sub-account's phone number, digits only, without the dialling code.","type":"string","pattern":"\\d+","example":"12345678"},"tradingName":{"description":"The name the sub-account trades under, if different from its legal name. This is the name the other party sees on payments. If left empty, the legal name is used.","type":"string"},"numberOfEmployees":{"description":"How many people the sub-account employs, as one of the listed ranges. Not included in the response.","type":"string","enum":["0-50","50-100","100-150","150-200","200-250","More than 250"]},"identificationNumber":{"description":"The sub-account's registration number from its country's official registry, for example a UK Companies House number (8 digits, or 2 letters and 6 digits). Required before the application can be submitted, and must match the format for the sub-account's country (5 to 20 letters and digits where no specific format applies).","type":"string","example":"UP12358132H"},"category":{"description":"The broad industry the sub-account operates in, for example Business Services. Required before the application can be submitted.","type":"string","example":"Business Services"},"subCategory":{"description":"The specific activity within the industry, for example Advertising Services. Required before the application can be submitted; it decides which documents the application asks for.","type":"string","example":"Advertising Services"},"taxIdOrEin":{"description":"The sub-account's tax identification number (for example an EIN in the US or a VAT number). For sub-accounts in the United Arab Emirates this is filled from the TRN in trnVerification and cleared if no TRN is held.","type":"string","example":"JH12313"},"licensedCountry":{"allOf":[{"$ref":"#/components/schemas/Country"},{"description":"If the sub-account needs a licence to operate, the country that issued it. Send it together with licensedType. A copy of the licence may be requested, depending on the sub-account's industry."}]},"licensedType":{"description":"If the sub-account needs a licence to operate, the type of licence, for example Financial Services License. Send it together with licensedCountry. Not included in the response.","type":"string","example":"Money Transfer License"},"website":{"description":"The sub-account's website address, for example www.example.com. Optional, but if given it must be a valid web address.","type":"string","example":"www.vertofx.com"},"countriesOfOffice":{"description":"Countries where the sub-account has an office, registration or other physical presence, given as country names (for example United Kingdom). Not included in the response.","type":"array","items":{"type":"string"},"example":["United Kingdom","Nigeria"]},"country":{"readOnly":true,"allOf":[{"$ref":"#/components/schemas/Country"},{"description":"Response only. The country where the sub-account is registered. You cannot change it with this request."},{"example":"United States"}]},"incorporationDate":{"description":"The date the sub-account was incorporated or registered, in ISO 8601 format (for example 2022-05-14T00:00:00Z). Cannot be in the future, and is required before the application can be submitted.","type":"string","format":"date-time","nullable":true,"example":"2022-05-14T00:00:00.000Z"},"type":{"allOf":[{"$ref":"#/components/schemas/EntityType"},{"description":"The sub-account's legal structure, for example Private Limited Company or Partnerships. Use one of the listed values. Required before the application can be submitted."}]},"socialMediaLinks":{"description":"Links to the sub-account's social media profiles. Optional.","type":"array","items":{"type":"object","properties":{"platform":{"type":"string","description":"Required for each link. The platform name in lower case, for example linkedin or youtube.","example":"linkedin"},"url":{"type":"string","description":"Required for each link. The full web address of the profile, for example https://www.linkedin.com/company/example.","example":"https://www.linkedin.com/company/example"}},"required":["platform","url"]},"example":[{"platform":"youtube","url":"https://www.youtube.com/@example"},{"platform":"linkedin","url":"https://www.linkedin.com/company/example"}]},"prohibitedActivities":{"type":"array","description":"Activities the sub-account carries out that Verto cannot support. Leave this empty if none apply: if any value is sent, the application cannot be submitted. Not included in the response.","items":{"type":"string"}},"screenerConfirmedAt":{"type":"string","format":"date-time","nullable":true,"description":"Date and time (ISO 8601) at which you confirm the sub-account does not carry out any prohibited activities. Required before the application can be submitted. Not included in the response."},"authorisedConfirmed":{"type":"boolean","description":"Set to true to confirm that the person submitting the application is authorised to act for the sub-account. Must be true before the application can be submitted. Not included in the response."},"incomeClassification":{"allOf":[{"$ref":"#/components/schemas/EIncomeClassification"},{"nullable":true,"description":"South Africa only. The sub-account's tax-reporting classification under FATCA/CRS: Active NFE, Passive NFE or Financial Institution. Required for South African sub-accounts. Not included in the response."}]},"giin":{"type":"string","nullable":true,"description":"South Africa only. The sub-account's Global Intermediary Identification Number, format XXXXXX.XXXXX.XX.XXX. Needed when incomeClassification is Financial Institution, unless you give giinExplanation instead. Not included in the response.","example":"ABC123.00000.LE.123"},"giinExplanation":{"type":"string","nullable":true,"description":"South Africa only. Why the sub-account has no GIIN, at least 10 characters. Use this instead of giin when incomeClassification is Financial Institution and no GIIN is held. Not included in the response.","example":"Company is registered as Active NFE"},"trnVerification":{"type":"object","nullable":true,"description":"United Arab Emirates only. Whether the sub-account holds a UAE Tax Registration Number (TRN) and, if so, the number. Not included in the response.","properties":{"status":{"type":"string","enum":["HAS_TRN","APPLIED_OR_WILL_APPLY","NOT_REQUIRED"],"description":"HAS_TRN if the sub-account holds a TRN, APPLIED_OR_WILL_APPLY if it has applied or will apply, NOT_REQUIRED if it does not need one.","example":"HAS_TRN"},"trnNumber":{"type":"string","nullable":true,"description":"The TRN (usually 15 digits). Required when status is HAS_TRN; also copied into taxIdOrEin. Ignored for any other status.","example":"100123456700003"},"reason":{"type":"string","nullable":true,"description":"Why the sub-account does not have a TRN yet, or does not need one, at least 10 characters. Ignored when status is HAS_TRN.","example":"We have applied and are awaiting issuance"}}},"ownershipControlAssessment":{"type":"object","nullable":true,"description":"South Africa only. The sub-account's answers to the ownership and control questions, which are required before a South African application can be submitted. Not included in the response.","properties":{"questionaire":{"type":"array","description":"One entry per ownership and control question. Every question must be answered, and a reason is needed for each Yes. (The field name is spelt questionaire.)","items":{"$ref":"#/components/schemas/OwnershipControlQuestionnaireItem"}},"consentDate":{"type":"string","format":"date-time","description":"Date and time (ISO 8601) at which the authorised signatories confirmed these answers. Stored for the record.","example":"2026-04-14T10:30:00.000Z"},"signatoryIds":{"type":"array","description":"The shareholder ids of the authorised signatories who confirmed these answers.","items":{"type":"string"},"example":["shareholder-123","shareholder-456"]}}}}},"PostAction":{"description":"What to do with this entry. ADD creates it; UPDATE and DELETE change or remove an existing one. ARCHIVE and UNARCHIVE apply to directors, shareholders and owners only. Existing directors, shareholders and owners are matched by id; addresses are matched by type.","type":"string","enum":["ADD","UPDATE","DELETE","ARCHIVE","UNARCHIVE"]},"ClientCompanyAddress":{"allOf":[{"$ref":"#/components/schemas/AddressBase"},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/CompanyAddressType"}}}]},"ClientShareholder":{"description":"A person or entity linked to the sub-account: a director, shareholder, owner or authorised signatory. Send a person with ownerType INDIVIDUAL, or a company or other legal entity with ownerType CORPORATE.","anyOf":[{"$ref":"#/components/schemas/ClientIndividualShareholder"},{"$ref":"#/components/schemas/ClientCorporateShareholder"}]},"ApiClientCompanyDocumentPostRq":{"description":"A document entry for the sub-account. In a request, the action decides what happens: ADD a new document, UPDATE an existing one, or DELETE one.","discriminator":{"propertyName":"action","mapping":{"ADD":"#/components/schemas/ApiClientCompanyDocumentAddRq","UPDATE":"#/components/schemas/ApiClientCompanyDocumentUpdateRq","DELETE":"#/components/schemas/ApiClientCompanyDocumentDeleteRq"}},"oneOf":[{"$ref":"#/components/schemas/ApiClientCompanyDocumentAddRq"},{"$ref":"#/components/schemas/ApiClientCompanyDocumentUpdateRq"},{"$ref":"#/components/schemas/ApiClientCompanyDocumentDeleteRq"}]},"ApiClientShareholderDocumentPostRq":{"description":"One change to the documents of a director, shareholder, owner or authorised signatory. The action decides the shape: ADD, UPDATE or DELETE.","discriminator":{"propertyName":"action","mapping":{"ADD":"#/components/schemas/ApiClientShareholderDocumentAddRq","UPDATE":"#/components/schemas/ApiClientShareholderDocumentUpdateRq","DELETE":"#/components/schemas/ApiClientShareholderDocumentDeleteRq"}},"oneOf":[{"$ref":"#/components/schemas/ApiClientShareholderDocumentAddRq"},{"$ref":"#/components/schemas/ApiClientShareholderDocumentUpdateRq"},{"$ref":"#/components/schemas/ApiClientShareholderDocumentDeleteRq"}]},"RiskAssessment":{"description":"A list of answers to Verto's risk assessment questions, one entry per question.","type":"array","items":{"$ref":"#/components/schemas/OnboardingAnswer"}},"AuditableBaseObj":{"type":"object","properties":{"id":{"readOnly":true,"$ref":"#/components/schemas/Uuid"},"createdAt":{"description":"When the sub-account's application was first created, in ISO 8601 format.","readOnly":true,"type":"string","format":"date-time","example":"2022-05-13T21:05:53.455Z"},"modifiedAt":{"description":"When the application was last changed, in ISO 8601 format.","readOnly":true,"type":"string","format":"date-time","example":"2022-05-13T21:05:53.455Z"}}},"ClientCompanyRs":{"allOf":[{"$ref":"#/components/schemas/ClientCompanyRq"},{"type":"object","properties":{"addresses":{"description":"Response only. The sub-account's saved addresses: its registered address (COMPANY_ADDRESS) and, if given, its operating address (OPERATING_ADDRESS). To change them, use companyAddresses in the request.","type":"array","items":{"$ref":"#/components/schemas/ClientCompanyAddress"}}}}]},"OnboardingProgressArray":{"description":"One entry per section of the application, each with its completion percentage.","type":"array","items":{"$ref":"#/components/schemas/OnboardingProgress"}},"OnboardingStatus":{"description":"The overall application status: IN_PROGRESS while it is being filled in, then APPROVED or REJECTED after Verto's review.","type":"string","enum":["IN_PROGRESS","USER_COMPLETED","APPROVED","REJECTED"],"example":"IN_PROGRESS"},"TierUpgradeInfo":{"type":"object","description":"The company's current tier upgrade, if any (for example TIER_1 → TIER_2). `status` moves from INITIATED to SUBMITTED to COMPLETED, or to REJECTED. INFO_REQUESTED means Verto needs more information before the upgrade can continue.","properties":{"status":{"$ref":"#/components/schemas/ETierUpgradeStatus"},"fromTierCode":{"type":"string","description":"The tier the company is upgrading from","example":"TIER_1"},"toTierCode":{"type":"string","description":"The tier the company is upgrading to","example":"TIER_2"},"initiatedAt":{"type":"string","format":"date-time"},"lastUpdatedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true},"forceTierUpgrade":{"type":"boolean","nullable":true,"description":"True when the company must complete full onboarding before access is restored."},"adminTierOverride":{"type":"boolean","nullable":true,"description":"True when Verto has set the target tier manually."}}},"Country":{"nullable":true,"description":"A country name in English, for example United Kingdom.","type":"string","enum":[null,"Afghanistan","Albania","Barbados","Belarus","Burkina Faso","Burundi","Cambodia","Cayman Islands","Congo (Brazzaville)","Democratic Republic of the Congo","Republic of the Congo","Equatorial Guinea","Guinea-Bissau","Haiti","Iran","Iraq","Jamaica","Jordan","Lebanon","Libya","Mali","Morocco","Myanmar","Nicaragua","North Korea","Pakistan","Panama","Philippines","Russia","Senegal","Somalia","South Sudan","Sudan","Syria","Turkey","Turkmenistan","Uganda","Venezuela","Western Sahara","Yemen","Gibraltar","Central African Republic","Guinea","Cuba","Malta","Angola","Azerbaijan","Bahamas","Bolivia","Botswana","Cabo Verde","Comoros","Egypt","Eritrea","Ghana","Kenya","Lao People's Democratic Republic","Liberia","Madagascar","Mauritania","Mauritius","Mongolia","Mozambique","Nigeria","Trinidad and Tobago","Uzbekistan","Zimbabwe","Bangladesh","Belize","Bosnia and Herzegovina","Brazil","British Virgin Islands","Cameroon","Chad","China","Curacao","Cyprus","Djibouti","Dominican Republic","Ecuador","El Salvador","Ethiopia","Guatemala","Honduras","Iceland","Isle of Man","Laos","Kazakhstan","Kosovo","Kyrgyzstan","Malawi","Maldives","Mexico","Nauru","Papua New Guinea","Paraguay","Samoa","Serbia","Seychelles","Sierra Leone","Sri Lanka","Tajikistan","Tanzania","Tunisia","Ukraine","Vanuatu","Vietnam","Algeria","Andorra","Antigua and Barbuda","Argentina","Armenia","Bahrain","Benin","Brunei Darussalam","Bulgaria","Cape Verde","Chile","Chinese Taipei","Colombia","Cook Islands","Costa Rica","Cote D'Ivoire","Cote'D Ivoire","Côte d'Ivoire","Côted'Ivoire","Ivory Coast","Croatia","Czech Republic","Dominica","Fiji","Gabon","Gambia","Gaza Strip","Georgia","Greece","Grenada","Guam","Guyana","Hong Kong","Hungary","India","Indonesia","Israel","Italy","Kiribati","Kuwait","Latvia","Lesotho","Lithuania","Macao","Macau","Macedonia","Malaysia","Marshall Islands","Moldova","Monaco","Montenegro","Namibia","Nepal","Niger","Oman","Palau","Peru","Portugal","Puerto Rico","Qatar","Romania","Rwanda","Saint Lucia","Saint Vincent and the Grenadines","Sao Tome and Principe","Saudi Arabia","Slovakia","Solomon Islands","South Africa","South Korea","Sint Maarten","Suriname","Swaziland","Taiwan","Thailand","Timor-Leste","Togo","Turks and Caicos Islands","Tuvalu","United Arab Emirates","Uruguay","West Bank","Zambia","Aruba","Australia","Austria","Belgium","Bermuda","Bhutan","Bonaire, Saint Eustatius and Saba","British Indian Ocean Territory","Canada","Falkland Islands","France","Ireland","Japan","Jersey","Liechtenstein","Luxembourg","Micronesia","Niue","Pitcairn","Poland","Saint Helena","Singapore","Slovenia","Spain","Switzerland","United States","U.S. Virgin Islands","Aland Islands","Anguilla","Christmas Island","Cocos Islands","Crimea","Denmark","Estonia","Faroe Islands","Finland","French Guiana","French Polynesia","Germany","Greenland","Guadeloupe","Guernsey","Martinique","Mayotte","Montserrat","Netherlands","New Caledonia","New Zealand","Norfolk Island","Northern Mariana Islands","Norway","Reunion","Saint Barthelemy","Saint Martin","Saint Pierre and Miquelon","San Marino","Svalbard and Jan Mayen","Sweden","Tokelau","Tonga","United Kingdom","Vatican","Wallis and Futuna","Saint Kitts and Nevis","Palestinian Territory"]},"EntityType":{"description":"The sub-account's legal structure. Use one of the listed values.","type":"string","nullable":true,"enum":["Public Limited Company","Private Limited Company","Limited Liability Company","Sole Trader / Sole Proprietorship / Freelancers","Club / Association","Non Profit / Charity","Estate / Trust","Partnerships","Unlimited Company","Closed Corporation","PTY Limited",null],"example":"Private Limited Company"},"EIncomeClassification":{"description":"FATCA/CRS tax-reporting classification, used for South African sub-accounts only.","type":"string","nullable":true,"enum":["Active NFE","Passive NFE","Financial Institution",null],"example":"Active NFE"},"OwnershipControlQuestionnaireItem":{"type":"object","required":["questionId","answer"],"properties":{"questionId":{"type":"string","description":"Required. ID of the ownership and control question being answered.","example":"64a1f2e3b5c9d0001234abcd"},"answer":{"type":"string","description":"Required. The answer, Yes or No.","example":"Yes"},"reason":{"type":"string","nullable":true,"description":"Explanation for the answer. Required when the answer is Yes.","example":"There is a shareholder agreement in place"}}},"AddressBase":{"type":"object","required":["type"],"properties":{"addressLine1":{"description":"First line of the address, usually the building number and street.","type":"string","example":"1600"},"addressLine2":{"description":"Second line of the address, such as a unit, floor or district. Optional.","type":"string","example":"Amphitheatre Parkway"},"city":{"description":"Town or city.","type":"string","example":"Mountain View"},"state":{"description":"Two-letter US state code, for example CA (not California). Required for US addresses; it is removed from addresses in any other country.","type":"string","example":"California"},"zipCode":{"description":"Postcode or ZIP code.","type":"string","example":"94043"},"country":{"description":"Country of the address, by full name, for example United States.","allOf":[{"$ref":"#/components/schemas/Country"},{"example":"United States"}]}}},"CompanyAddressType":{"description":"Type of the sub-account's address: COMPANY_ADDRESS is the registered address, OPERATING_ADDRESS is where it actually operates.","type":"string","enum":["COMPANY_ADDRESS","OPERATING_ADDRESS"],"example":"COMPANY_ADDRESS"},"ClientIndividualShareholder":{"title":"Person","type":"object","properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Uuid"},{"description":"The id of this person on the application. You can leave it out when adding a person and one is created for you. Send it to UPDATE, DELETE, ARCHIVE or UNARCHIVE that person."}]},"email":{"description":"The person's email address, for example jane.doe@example.com. Each person on the application needs a different email address, and at least one director must have one before the application can be submitted.","type":"string","example":"jane.doe@example.com"},"percentOwnershipInCompany":{"description":"Percentage of the sub-account this person owns, from 0 to 100, for example 25. Owners at or above the ownership threshold (usually 25%, lower in some cases) must complete identity verification.","type":"number","minimum":0,"maximum":100,"example":25},"ownerType":{"description":"Whether this record is a person (INDIVIDUAL) or a company or other legal entity (CORPORATE). Use INDIVIDUAL for directors, owners and authorised signatories who are people.","allOf":[{"$ref":"#/components/schemas/OwnerType"}]},"firstName":{"description":"The person's first name as shown on their ID document, for example Jane. Required for every person before the application can be submitted.","type":"string","example":"Jane"},"middleName":{"description":"The person's middle name or names, if they have any. Leave it out or send null if they have none.","type":"string","example":null,"nullable":true},"lastName":{"description":"The person's last name as shown on their ID document, for example Doe. Required for every person before the application can be submitted.","type":"string","example":"Doe"},"nationality":{"allOf":[{"$ref":"#/components/schemas/Country"},{"description":"The country of the person's nationality, given as a full country name, for example United States. Required for every director and owner. Nigerian nationals must also provide their BVN and NIN in idNumbers."},{"example":"United States"}]},"isControllingOfficer":{"description":"Set to true if this person is a director of the sub-account. Each application needs at least one director with an email address, and directors must also provide a date of birth and nationality.","type":"boolean"},"isAuthorisedSignatory":{"description":"Set to true if this person is an authorised signatory, meaning they can act and sign on behalf of the sub-account. Each application needs at least one authorised signatory who is a person.","type":"boolean"},"ownershipTopology":{"$ref":"#/components/schemas/OwnershipTopology"},"shareholderRole":{"description":"The person's job title or role in the sub-account, for example Chief Executive Officer. Up to 100 characters. Required for every person before the application can be submitted.","type":"string","maxLength":100},"dateOfBirth":{"description":"The person's date of birth in YYYY-MM-DD format, for example 1985-04-23. Required for directors and owners.","type":"string","format":"date"},"countryCallingCode":{"description":"The international dialling code for the person's phone number, including the plus sign, for example +44. Send it together with phoneNumber.","type":"string","example":"+44"},"phoneNumber":{"description":"The person's phone number, digits only and without the country calling code, for example 7700900123.","type":"string","pattern":"\\d+","example":"12345678"},"idNumbers":{"$ref":"#/components/schemas/IdNumbers"},"kycStatus":{"readOnly":true,"$ref":"#/components/schemas/EKYCStatus"},"kycApprovedOn":{"readOnly":true,"type":"string","format":"date-time","example":"2022-05-13T21:05:53.455Z","description":"Response only. The date and time this person's identity verification was approved. It is empty until then."},"verificationLink":{"description":"Response only. A personal link the person opens to complete identity verification. It stays valid for about 30 days from verificationLinkGeneratedAt, and is replaced if a new link is generated.","readOnly":true,"type":"string"},"verificationLinkGeneratedAt":{"description":"Response only. The date and time the current verification link was created. Use it to tell when the link will expire.","readOnly":true,"type":"string","format":"date-time"},"fetchedFromVendor":{"description":"Response only. True if Verto filled in this person from the official company register, and false if they were added by you. It changes to false if any details that came from the register are changed.","type":"boolean","example":false,"readOnly":true},"status":{"$ref":"#/components/schemas/ShareholderStatus"},"address":{"allOf":[{"$ref":"#/components/schemas/ClientAddress"},{"description":"The person's home address. Address line 1, city, postcode and country are needed before the application is complete."},{"type":"object","properties":{"type":{"description":"The address type. For a person, always send HOME_ADDRESS.","type":"string","enum":["HOME_ADDRESS"]}}}]},"documents":{"description":"Response only. The identity documents saved for this person, with each document's type, link and review status. To upload a document, use shareholderDocuments in the request. Documents sent here are ignored.","type":"array","items":{"$ref":"#/components/schemas/ApiClientShareholderDocument"}},"parentId":{"description":"Request only. If this person owns the sub-account through a corporate shareholder, send that shareholder's id here. Leave it out for direct ownership. It is not returned in the response.","type":"string","nullable":true,"example":"036c4bdd-803d-52f2-ac8c-45721749bcbf"},"tinVerification":{"$ref":"#/components/schemas/TinVerification"}}},"ClientCorporateShareholder":{"title":"Company or other entity","type":"object","properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Uuid"},{"description":"Verto's ID for this corporate shareholder. Leave it out when you ADD a shareholder (one is created for you) and send it on UPDATE, DELETE, ARCHIVE or UNARCHIVE."}]},"email":{"description":"Optional contact email for the corporate shareholder. Each email can be used by only one shareholder in the sub-account's application.","type":"string","example":"jane.doe@example.com"},"percentOwnershipInCompany":{"description":"The percentage of the sub-account this corporate shareholder owns, from 0 to 100 (for example 25). Needed unless the shareholder is marked as a related entity.","type":"number","minimum":0,"maximum":100,"example":25},"ownerType":{"description":"Set to CORPORATE for a shareholder that is a legal entity rather than a person. Required when you add a shareholder.","allOf":[{"$ref":"#/components/schemas/OwnerType"},{"example":"CORPORATE"}]},"businessEntityType":{"allOf":[{"$ref":"#/components/schemas/EntityType"},{"description":"The legal form of the corporate shareholder, for example Private Limited Company. Needed to complete the shareholder unless it is marked as a related entity."}]},"businessName":{"description":"The registered legal name of the corporate shareholder, for example Alphabet Inc. Always needed to complete the shareholder.","type":"string","example":"Alphabet"},"businessRegistrationNumber":{"description":"The corporate shareholder's registration number from its official company register, for example JG23517. Needed unless the shareholder is marked as a related entity.","type":"string","example":"JG23517"},"ownershipTopology":{"$ref":"#/components/schemas/OwnershipTopology"},"incorporationCountry":{"allOf":[{"$ref":"#/components/schemas/Country"},{"description":"The country where the corporate shareholder is incorporated, written as a full country name (for example United States)."},{"example":"United States"}]},"fetchedFromVendor":{"description":"Response only. True when Verto added this shareholder automatically from the official company register rather than you adding it; it becomes false once you change any of the register-sourced details.","type":"boolean","example":false,"readOnly":true},"status":{"$ref":"#/components/schemas/ShareholderStatus"},"isRelatedEntity":{"description":"Set to true if this entity is connected to the sub-account but does not hold shares in it. Only its name is then needed. Not returned in the response.","type":"boolean","example":false},"address":{"allOf":[{"$ref":"#/components/schemas/ClientCompanyAddress"},{"type":"object","properties":{"type":{"description":"The address type. For a corporate shareholder this is always COMPANY_ADDRESS.","type":"string","enum":["COMPANY_ADDRESS"]}}},{"description":"The corporate shareholder's registered address."}]},"documents":{"description":"Response only. The documents uploaded for this corporate shareholder and their review status. To upload documents, use shareholderDocuments in the request instead.","type":"array","items":{"$ref":"#/components/schemas/ApiClientShareholderDocument"}},"tinVerification":{"$ref":"#/components/schemas/TinVerification"},"incorporationDate":{"description":"The date the corporate shareholder was incorporated, in ISO 8601 format (for example 2015-03-01T00:00:00Z).","type":"string","format":"date-time","nullable":true}}},"ApiClientCompanyDocumentAddRq":{"title":"Add a document","type":"object","required":["action","data"],"properties":{"action":{"type":"string","enum":["ADD"],"description":"Set to ADD to upload a new document for the sub-account."},"data":{"allOf":[{"$ref":"#/components/schemas/ApiClientDocumentSchema"},{"type":"object","required":["typeId","link"],"description":"The new document. A document type and file link are required; Verto assigns the document id."}]}}},"ApiClientCompanyDocumentUpdateRq":{"title":"Update a document","type":"object","required":["action","data"],"properties":{"action":{"type":"string","enum":["UPDATE"],"description":"Set to UPDATE to replace the file, type or country of a document already on the application."},"data":{"allOf":[{"$ref":"#/components/schemas/ApiClientDocumentSchema"},{"type":"object","required":["id","typeId","link"],"description":"The document's id plus its type and file link. Fields you send overwrite the stored values."}]}}},"ApiClientCompanyDocumentDeleteRq":{"title":"Delete a document","type":"object","required":["action","data","reason"],"properties":{"action":{"type":"string","enum":["DELETE"],"description":"Set to DELETE to remove a document. Documents Verto has approved or is reviewing cannot be deleted."},"data":{"type":"object","required":["id"],"properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Uuid"},{"description":"The id of the document to remove, as returned when it was added."}]}},"description":"Identifies the document to remove; only its id is needed."},"reason":{"type":"string","description":"Why the document is being removed. Must not be empty; Verto records a standard reason for deletions you make.","minLength":1}}},"ApiClientShareholderDocumentAddRq":{"title":"Add a document","type":"object","required":["action","data"],"properties":{"action":{"type":"string","enum":["ADD"],"description":"Set to ADD to upload a new document for a director, shareholder, owner or authorised signatory."},"data":{"allOf":[{"$ref":"#/components/schemas/ApiClientShareholderDocument"},{"type":"object","required":["typeId","link","shareholderId"],"description":"The new document. The person or entity it belongs to, the document type and the file link are required; Verto assigns the document id."}]}}},"ApiClientShareholderDocumentUpdateRq":{"title":"Update a document","type":"object","required":["action","data"],"properties":{"action":{"type":"string","enum":["UPDATE"],"description":"Set to UPDATE to replace the file, type or country of an existing document."},"data":{"allOf":[{"$ref":"#/components/schemas/ApiClientShareholderDocument"},{"type":"object","required":["id","typeId","link","shareholderId"],"description":"The document's id, the person or entity it belongs to, and its type and file link. Fields you send overwrite the stored values."}]}}},"ApiClientShareholderDocumentDeleteRq":{"title":"Delete a document","type":"object","required":["action","data","reason"],"properties":{"action":{"type":"string","enum":["DELETE"],"description":"Set to DELETE to remove a document. Documents Verto has approved or is reviewing cannot be deleted."},"data":{"type":"object","required":["id"],"properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Uuid"},{"description":"The id of the document to remove, as returned when it was added."}]}},"description":"Identifies the document to remove: send the document's id and the shareholderId of the person or entity it belongs to."},"reason":{"type":"string","description":"Why the document is being removed. Must not be empty; Verto records a standard reason for deletions you make.","minLength":1}}},"OnboardingAnswer":{"type":"object","required":["questionId","answer"],"properties":{"questionId":{"allOf":[{"$ref":"#/components/schemas/Uuid"},{"description":"The id of the question being answered. The ids still to answer appear in the submission checks as riskAssessment.<questionId>. Sending a new answer for the same question replaces the earlier one."}]},"answer":{"description":"The answer. Send text for single-choice or free-text questions, and a list of options for multiple-choice questions; options must match the ones Verto offers for that question.","oneOf":[{"title":"Single answer","type":"string"},{"title":"Multiple answers","type":"array","items":{"type":"string"}}],"example":"$499K - $1M"}}},"Uuid":{"description":"A unique identifier, 1 to 50 characters, for example 5f29833d-1104-42a9-8c63-e6c8140130c1.","type":"string","minLength":1,"maxLength":50,"example":"5f29833d-1104-42a9-8c63-e6c8140130c1"},"OnboardingProgress":{"type":"object","required":["state","percentageCompleted"],"properties":{"state":{"$ref":"#/components/schemas/OnboardingState"},"percentageCompleted":{"description":"Required. How much of this section is filled in, from 0 to 100.","type":"integer","example":50},"lastUpdatedAt":{"description":"When this section's progress was last updated, in ISO 8601 format.","type":"string","format":"date-time","example":"2022-05-13T21:05:53.455Z"}}},"ETierUpgradeStatus":{"description":"Status of a tier upgrade. INFO_REQUESTED means Verto needs more information before the upgrade can continue.","type":"string","enum":["INITIATED","SUBMITTED","COMPLETED","REJECTED","INFO_REQUESTED"],"example":"INITIATED"},"OwnerType":{"description":"INDIVIDUAL for a person, CORPORATE for a company or other legal entity. Do not use BOTH.","type":"string","enum":["INDIVIDUAL","CORPORATE","BOTH"]},"OwnershipTopology":{"description":"DIRECT if the shares are held directly in the sub-account, INDIRECT if they are held through another entity. Send the uppercase values. The mixed-case values are accepted only for older data.","type":"string","enum":["DIRECT","INDIRECT","Direct","Indirect"]},"IdNumbers":{"type":"object","description":"object containing all the id numbers","properties":{"bvn":{"description":"Nigerian Bank Verification Number (BVN), 11 digits. Required for Nigerian nationals.","type":"string","example":"00000000000"},"nin_v2":{"description":"Nigerian National Identification Number (NIN): 11 digits, or the 11-character format of two letters, seven digits and a letter. Required for Nigerian nationals.","type":"string","example":"00000000000"},"tin":{"description":"The person's tax identification number: at least 8 digits, a hyphen, then at least 4 digits, for example 12345678-1234.","type":"string","example":"00000000-0000"},"national_id":{"description":"The person's national ID card number. For people in Kenya or South Africa.","type":"string","example":"0000000000"},"kra_pin":{"description":"Kenya Revenue Authority (KRA) PIN, for example A123456789Z. For people in Kenya.","type":"string","example":"A00000000"},"national_id_no_photo":{"description":"The person's national ID number, for people in Kenya or South Africa, as an alternative to national_id.","type":"string","example":"0000000000"},"passport":{"description":"The person's passport number. Used for an automatic identity check for people in Kenya.","type":"string","example":"A00000000"},"phone_number":{"description":"A phone number registered to the person, used to verify their identity in countries that support it. Digits only.","type":"string","example":"1234567890"}}},"EKYCStatus":{"type":"string","description":"Where a person is in identity verification. PENDING: not started. IN_PROGRESS: started. USER_COMPLETED: the person finished their steps and the result is awaited. MANUAL_REVIEW: Verto is reviewing it. APPROVED: verified. REJECTED: verification failed. RESUBMISSION_REQUESTED: the person needs to try again.","enum":["PENDING","IN_PROGRESS","USER_COMPLETED","MANUAL_REVIEW","APPROVED","REJECTED","RESUBMISSION_REQUESTED"]},"ShareholderStatus":{"description":"ACTIVE: the person or entity is part of the application. ARCHIVED: they have been set aside and are not considered, and they can be made ACTIVE again.","type":"string","enum":["ACTIVE","ARCHIVED"]},"ClientAddress":{"allOf":[{"$ref":"#/components/schemas/AddressBase"},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/AddressType"}}}]},"ApiClientShareholderDocument":{"allOf":[{"$ref":"#/components/schemas/ApiClientDocumentSchema"}],"type":"object","properties":{"shareholderId":{"allOf":[{"$ref":"#/components/schemas/Uuid"},{"description":"The id of the director, shareholder, owner or authorised signatory this document belongs to, as returned in the shareholders list. Needed when adding, updating or deleting their documents. Request only; not included in responses."}]}}},"TinVerification":{"type":"object","description":"Tax Identification Number verification details for UAE shareholders","properties":{"hasTrn":{"type":"boolean","description":"Whether there is a tax identification number. Send true together with tin, or false together with reason.","example":true},"tin":{"type":"string","description":"The tax identification number, for example 123456789.","example":"123456789"},"reason":{"type":"string","description":"Why there is no tax identification number, for example 'Newly incorporated, number pending'. Send it when hasTrn is false.","example":"Entity is newly incorporated and TRN is pending"}}},"ApiClientDocumentSchema":{"type":"object","required":["link","typeId"],"properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Uuid"},{"description":"The document's id, assigned by Verto when the document is added. Leave it out when adding; it is required when updating."}]},"typeId":{"allOf":[{"$ref":"#/components/schemas/Uuid"},{"description":"The document type this file fulfils, for example a certificate of incorporation. Use the typeId from the documents-to-submit list for the sub-account."}]},"link":{"description":"The reference to the uploaded file.","type":"string"},"country":{"description":"The country that issued the document, where relevant (for example, a passport or ID card). Optional.","type":"string","nullable":true}}},"OnboardingState":{"description":"An application section: SIGNUP_VERIFICATION (the products chosen; for sub-accounts this section can stay below 100 and can be ignored), BUSINESS_INFORMATION (the sub-account's details), SHAREHOLDER_INFORMATION (directors, shareholders and owners), COMPANY_DOCUMENTS (the sub-account's documents), SHAREHOLDER_VERIFICATION (identity checks on the people involved) or RISK_ASSESSMENT (risk assessment questions).","type":"string","enum":["SIGNUP_VERIFICATION","BUSINESS_INFORMATION","SHAREHOLDER_INFORMATION","COMPANY_DOCUMENTS","SHAREHOLDER_VERIFICATION","RISK_ASSESSMENT"],"example":"SIGNUP_VERIFICATION"},"AddressType":{"description":"Type of address. For a director's, shareholder's or owner's home address use HOME_ADDRESS.","type":"string","enum":["COMPANY_ADDRESS","OPERATING_ADDRESS","HOME_ADDRESS","OTHER_ADDRESS"],"example":"HOME_ADDRESS"},"SSNVerificationMatchDetails":{"type":"object","description":"Details of what matched during SSN verification","properties":{"ssnMatch":{"type":"boolean","description":"Whether the SSN matched"},"last4SSN":{"type":"string","description":"last 4 digits of ssn"},"nameMatch":{"type":"object","properties":{"firstNameMatch":{"type":"boolean"},"lastNameMatch":{"type":"boolean"},"returnedFirstName":{"type":"string","nullable":true},"returnedLastName":{"type":"string","nullable":true}}},"addressMatch":{"type":"object","properties":{"streetMatch":{"type":"boolean"},"cityMatch":{"type":"boolean"},"zipMatch":{"type":"boolean"},"returnedAddress":{"type":"object","nullable":true}}}}}}},"security":[{"JWTAuth":[]}],"servers":[{"url":"https://api-onboarding-beta.vertofx.com"},{"url":"https://api-onboarding-sandbox.vertofx.com"}]}