Upload Onboarding Data API

The Update Onboarding Data API is the primary endpoint for submitting and modifying all information related to a sub-account application. This includes company details, shareholder information, linking uploaded documents, and providing answers to risk assessment questions.

This endpoint is used to build the application piece by piece. You can call it multiple times to add or change information as it becomes available.

Endpoint: POST /companies/[companyId]/onboarding-data

• Authentication: Requires the appropriate auth token (e.g., parentCompanyId token) in the authorisation header.
• [companyId]: This must be the unique ID of the sub-account you are updating.

Payload Structure and Actions

The request body is a flexible JSON object that allows you to update different sections of the application in a single call. You only need to include the sections you wish to add or modify.

The main properties of the payload include:

• company: An object containing the sub-account's business information.
• companyAddresses: An array for the sub-account's registered and operating addresses.
• shareholders: An array for adding, updating, or deleting shareholder information.
• companyDocuments: An array used to link uploaded company documents to the application.
• shareholderDocuments: An array used to link documents for specific shareholders.
• riskAssessment: An array for submitting the answers to the mandatory risk assessment questions.

Using the 'action' Property For arrays like shareholders and companyAddresses, each object must include an action property to specify the operation:

• "action": "ADD": Adds the object as a new entry.
• "action": "UPDATE": Modifies an existing entry. You must include the id of the shareholder or address to be updated.
• "action": "DELETE": Removes an existing entry. You only need to provide the id.

Linking Uploaded Documents After successfully uploading a file using the Document Upload API flow, you must link it to the application using this endpoint. In the companyDocuments or shareholderDocuments array, provide an object containing:

1. The static typeId of the document.
2. The key returned from the /documents/generate-upload-link response, which you map to the link property here.

Example for linking a company document:

"companyDocuments": [
  {
    "action": "ADD",
    "data": {
      "typeId": "66d2938475a40aae623126e1",
      "link": "a484j93-d7f5-5b12-f863-db44c454c25e-Sample.pdf"
    }
  }
]

Submitting Risk Assessment Answers Use the riskAssessment array to submit answers. Each object in the array must contain the static questionId and the corresponding answer.

• For single-select and text questions, the answer is a string.
• For multi-select questions, the answer is an array of strings.

Example for submitting risk questions:

"riskAssessment": [
  {
    "questionId": "66d2974278a40aae623126e1",
    "answer": "No"
  },
  {
    "questionId": "66557b35aa849e0ccd44b906",
    "answer": [
      "My own bank account",
      "Other businesses"
    ]
  }
]

Sub-Account Terms & Conditions

Before a Sub-Account can be fully operated, the director of the business must review and accept Verto’s Terms & Conditions.

Note: This only applies to reffered clients

The T&C API allows Atlas partners to:

Record the director’s decision (accepted or rejected) for a Sub-Account.

Store the director’s name and the time of decision.

Retrieve the updated linked status for that Sub-Account.

This is typically the final activation step after onboarding has been completed.

Prerequisites

Before using the T&C API, make sure you have:

A Parent Account (your platform / Atlas account).

A created Sub-Account for your end-client (via the Sub-Accounts APIs).

The Sub-Account’s companyId (also called subCompanyId in the path parameter).

Onboarding completed for that Sub-Account (so that it is ready for T&C).

You can obtain the subCompanyId from:

The response of the Create Sub-Account API, or

The Get Sub-Accounts APIs.

T&C Flow via API

At a high level, the flow looks like this:

Create & onboard the Sub-Account (using the Sub-Accounts + Onboarding APIs).

Confirm T&C consent from the director i

Submit the result (acceptance or rejection) using the T&C API.

Check the linked status to confirm the Sub-Account is ready to use.

Submitting T&C Acceptance / Rejection

Use the “Submit T&C for Sub-Account” endpoint :

POST /sub-accounts/{subCompanyId}/tnc

Path Parameter

subCompanyId – The companyId of the Sub-Account you are updating.

Request Body

The request body contains:

linkedStatus – The T&C decision for this Sub-Account.

director – An object containing:

firstName – Director’s first name.

lastName – Director’s last name.

Example request body :

{
  "linkedStatus": "ACCEPTED",
  "director": {
    "firstName": "string",
    "lastName": "string"
  }
}

Reading the Response

On success, the endpoint returns a 200 response with:

linkedStatus – The stored T&C status for the Sub-Account.

linkedAt – The timestamp when the T&C decision was recorded.

director – The director details saved against this decision.

companyReference – The internal company reference for the Sub-Account.

Example response:

{
  "linkedStatus": "string",
  "linkedAt": "2025-11-17T08:42:28.377Z",
  "director": {
    "firstName": "string",
    "lastName": "string"
  },
  "companyReference": "string"
}

After this, the Sub-Account’s status will update accordingly , and it can be used for collections, payouts and FX according to your configuration.

Check Sub-Account Onboarding / Activation Status

Use this to determine whether a Sub-Account is still onboarding (KYC pending), is awaiting T&C acceptance, or is fully active.

You can use this endpoint to check whether a sub-account is still onboarding or fully active.

When you call the endpoint, each sub-account in the items array includes two important status fields:

companyStatus – lifecycle of the company record

linkedStatus – whether the sub-account is ready to be operated

Request Example

curl --request POST \
     --url https://api-company-sandbox.vertofx.com/sub-accounts/list \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

Response Example

{
  "totalCount": 2,
  "items": [
    {
      "id": "sub_7baf65d21",
      "externalId": "string",
      "parentCompanyId": "string",
      "name": "ACME Trading Limited",
      "country": "GB",
      "category": "string",
      "subCategory": "string",
      "identificationNumber": "47585940",
      "taxIdOrEin": "string",
      "accountType": "PARTNER_REFERRED",
      "companyReference": "VU-13112025-B3822",
      "companyStatus": "CREATED",
      "linkedStatus": "PENDING",
      "linkedAt": "2025-11-17T08:51:51.362Z",
      "createdAt": "2025-11-17T08:51:51.362Z",
      "updatedAt": "2025-11-17T08:51:51.362Z"
    },
    {
      "id": "sub_9ffd8c723",
      "externalId": "string",
      "parentCompanyId": "string",
      "name": "Beta Holdings",
      "country": "GB",
      "category": "string",
      "subCategory": "string",
      "identificationNumber": "9475992",
      "taxIdOrEin": "string",
      "accountType": "PARTNER_REFERRED",
      "companyReference": "VU-13112025-B3815",
      "companyStatus": "CREATED",
      "linkedStatus": "ACCEPTED",
      "linkedAt": "2025-11-17T10:14:22.011Z",
      "createdAt": "2025-11-17T08:49:12.001Z",
      "updatedAt": "2025-11-17T10:14:22.011Z"
    }
  ]
}