get
https://api-onboarding-beta.vertofx.com/companies//onboarding-data/checks
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.
The assessment depends on your Atlas product:
- 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.
- 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.
Atlas for Platform: wait for background checks before you submit.Because the assessment is asynchronous, wait until
statusisCOMPLETED.
Where this fits
- Save the sub-account's information with Add or update onboarding data.
- Call this endpoint to see what is still open.
- Fix the issues with another save, then call this endpoint again.
- When there are no BLOCKING issues and you have reviewed any WARNING issues, call Submit application.
Issue severity
| Severity | Effect |
|---|---|
| BLOCKING | Must be resolved before the application can be submitted. |
| WARNING | Doesn't block submission, but needs review. |
Decide by each issue's severity, never by its code: the same code can be BLOCKING or WARNING.
Have someone review WARNING issues before you submit.WARNING issues don't block submission, but they often point to document problems that delay compliance review.
Reading the response
| Field | What it tells you |
|---|---|
companyId, reference | The sub-account these checks are for, and its Verto reference (VU number). |
status | Where the background checks are (not the application's overall status). See the table below. |
targetTier | The tier the application will be submitted for. TIER_2 for sub-accounts. |
tiers | For each tier, whether any BLOCKING issue remains (submittable is true when none does). |
issues | Everything still open, BLOCKING and WARNING (only up to the requested tier if you pass tier). |
evaluatedAt | When this response was computed. |
Background check status
status | Meaning |
|---|---|
NOT_STARTED | No background check has run yet; its findings will appear once it does. |
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. |
COMPLETED | All background checks in the latest run have finished and their findings are included. The list is final until the next save. |
FAILED | The latest background run could not complete. Findings from checks that did complete in this run are included. Contact [email protected] if this persists. |
Each issue
| Field | What it tells you |
|---|---|
severity | BLOCKING or WARNING. See Issue severity above. |
code | What kind of problem it is. See Possible set of codes below. |
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. |
field | Which field to fix. See Fixing an issue below. |
tier | The lowest tier the issue applies to. |
message | A readable explanation of what to fix. |
Possible set of codes
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.
| Code | What it means |
|---|---|
FIELD_MISSING | A required field is empty. |
FIELD_INVALID | A field's value isn't valid, for example an identification number in the wrong format. |
DOCUMENT_MISSING | A required document hasn't been provided. |
DIRECTOR_REQUIRED | The sub-account needs at least one director with an email address. |
SIGNATORY_REQUIRED | The sub-account needs an individual authorised signatory. |
OWNER_REQUIRED | The sub-account needs at least one active shareholder. |
COUNTRY_NOT_SUPPORTED | Verto can't onboard sub-accounts from this country. Fixable only if the country was entered incorrectly. |
TIER_BELOW_PRODUCTS | The tier is below what the selected products need. |
VERIFICATION_PENDING | An identity or address verification hasn't completed yet. |
DOCUMENT_TYPE_MISMATCH | An uploaded document doesn't appear to be the type required. |
DOCUMENT_EXPIRED | An uploaded document appears to be expired or too old. |
DOCUMENT_UNREADABLE | An uploaded document couldn't be read. |
DATA_MISMATCH | Details in a document don't match the data provided. |
Fixing an issue
field is usually a field name of POST /companies/{companyId}/onboarding-data, relative to resource. Documents and verification use the slot names below.
company: e.g.identificationNumber,incorporationDate,authorisedConfirmed,description,companyAddresses.COMPANY_ADDRESS,screenerConfirmedAt,riskAssessment.<questionId>,ownershipControlAssessment.<questionId>shareholder: e.g.email,dateOfBirth,nationality,address.zipCode,idNumbers.bvn- Verification:
VERIFICATION_PENDINGissues useverification.<check>. Upload the identity or address documents the check needs. - People:
DIRECTOR_REQUIRED,SIGNATORY_REQUIREDandOWNER_REQUIREDuseshareholders. - Documents:
documents.<documentType>, a camelCase slot name, e.g.documents.certificateOfIncorporation,documents.proofOfBusinessAddress,documents.shareholdingStructure,documents.sourceOfFunds. The slot'stypeIdcomes fromGET /companies/{companyId}/documentsToSubmit.
Send the missing or corrected data in another save, then call this endpoint again.
When to submit
Once there are no BLOCKING issues and you have reviewed any WARNING issues, call Submit application. For Atlas for Platform, wait until status is COMPLETED first.