Add Onboarding Data (New)

Overview

Submit comprehensive onboarding data for a company or sub-account, track review and RFI states, and submit compliance data before enabling operational activity.

This endpoint accepts the company's selected banking products, corporate profile, registered and operating addresses, beneficial owners/shareholders, uploaded document references, and regulatory risk assessment answers.

Resource Access

• HTTP Method: POST
• Endpoint: /banking/ibans/v2/companies/{companyId}/onboarding-data
• Authentication: Bearer token required

Request Headers

Header	Value	Required	Description
Authorization	Bearer {access_token}	Yes	JWT Bearer access token
Content-Type	application/json	Yes	Request payload format
Accept	application/json	Yes	Response payload format
x-api-key	string	No	Optional API key

Path Parameters

Parameter	Type	Required	Description
companyId	string	Yes	The unique identifier for the company (e.g. 2).

Request Body

Request Fields (ClientOnboardingRq)

Field	Type	Required	Description
selectedProducts	array of strings	Yes	Banking products selected (Collect, Convert, Pay, Hold, API).
company	object	Yes	Corporate profile details (legal form, company type).
company.type	string	Yes	Legal entity type (e.g. Private Limited Company, Sole Proprietorship).
companyAddresses	array	Yes	Registered and operational addresses for the business.
companyAddresses[].type	string	Yes	Address type (REGISTERED or OPERATING).
companyAddresses[].line1	string	Yes	Street address line 1.
companyAddresses[].city	string	Yes	City or locality.
companyAddresses[].postalCode	string	Yes	Postal or ZIP code.
companyAddresses[].country	string	Yes	ISO country code (e.g. GB, US).
shareholders	array	Yes	Array of corporate or individual shareholders and UBOs.
shareholders[].type	string	Yes	Shareholder type (INDIVIDUAL or CORPORATE).
shareholders[].firstName	string	Yes	First name (for individuals).
shareholders[].lastName	string	Yes	Last name (for individuals).
shareholders[].percentage	number	Yes	Percentage of shares or voting rights held.
companyDocuments	array	No	Uploaded company document references (documentKey, documentTypeId).
shareholderDocuments	array	No	Uploaded identification documents for shareholders.
riskAssessment	array	No	Array of compliance and risk assessment questionnaire responses.

Request Example

{
  "selectedProducts": ["Collect", "Convert", "Pay"],
  "company": {
    "type": "Private Limited Company"
  },
  "companyAddresses": [
    {
      "type": "REGISTERED",
      "line1": "100 Bishopsgate",
      "city": "London",
      "postalCode": "EC2N 4AG",
      "country": "GB"
    }
  ],
  "shareholders": [
    {
      "type": "INDIVIDUAL",
      "firstName": "Alexander",
      "lastName": "Wright",
      "email": "alex.wright@example.com",
      "percentage": 60.0,
      "isUltimateBeneficialOwner": true,
      "isDirector": true
    }
  ],
  "companyDocuments": [
    {
      "documentTypeId": "doc_type_incorp_01",
      "documentKey": "docs/company/2/incorporation-cert.pdf"
    }
  ]
}

Response

Success Response (200 OK)

{
  "companyId": "2",
  "parentCompanyId": "1",
  "status": "UNDER_REVIEW",
  "kycLevel": "0",
  "selectedProducts": ["Collect", "Convert", "Pay"],
  "company": {
    "type": "Private Limited Company"
  },
  "progress": [
    {
      "step": "COMPANY_DETAILS",
      "status": "COMPLETED"
    },
    {
      "step": "DOCUMENTS",
      "status": "IN_REVIEW"
    }
  ],
  "createdAt": "2026-09-15T03:00:00.000Z",
  "updatedAt": "2026-09-15T03:00:00.000Z"
}

Response Fields (ClientOnboardingRs)

Field	Type	Description
companyId	string	Unique identifier for the company.
parentCompanyId	string	ID of the parent company if this is a sub-account.
status	string	Overall onboarding status (CREATED, PENDING, UNDER_REVIEW, APPROVED, REJECTED, RFI).
kycLevel	string	Approved KYC tier (0 = basic, 3 = verified tier).
selectedProducts	array	List of products activated for this account.
progress	array	Granular review step progression across compliance checks.
createdAt	string	Timestamp when onboarding dossier was created.
updatedAt	string	Timestamp of last modification.

Error Responses

• 400 Bad Request: Invalid payload, missing mandatory fields, or malformed schema.
• 401 Unauthorized: Missing or expired Bearer token.
• 403 Forbidden: Caller does not have permissions to modify this company.
• 404 Not Found: companyId not found.
• 500 Internal Server Error: An internal server error occurred.

Code Examples

Base URL

Production: https://api.ahrvo.network
Staging:    https://gateway.ahrvo.network

cURL

curl -X POST \
  'https://gateway.ahrvo.network/banking/ibans/v2/companies/2/onboarding-data' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "selectedProducts": ["Collect", "Convert", "Pay"],
    "company": {
      "type": "Private Limited Company"
    },
    "companyAddresses": [
      {
        "type": "REGISTERED",
        "line1": "100 Bishopsgate",
        "city": "London",
        "postalCode": "EC2N 4AG",
        "country": "GB"
      }
    ],
    "shareholders": [
      {
        "type": "INDIVIDUAL",
        "firstName": "Alexander",
        "lastName": "Wright",
        "email": "alex.wright@example.com",
        "percentage": 60.0
      }
    ]
  }'

Python

import requests

url = "https://gateway.ahrvo.network/banking/ibans/v2/companies/2/onboarding-data"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "selectedProducts": ["Collect", "Convert", "Pay"],
    "company": {
        "type": "Private Limited Company"
    },
    "companyAddresses": [
        {
            "type": "REGISTERED",
            "line1": "100 Bishopsgate",
            "city": "London",
            "postalCode": "EC2N 4AG",
            "country": "GB"
        }
    ],
    "shareholders": [
        {
            "type": "INDIVIDUAL",
            "firstName": "Alexander",
            "lastName": "Wright",
            "email": "alex.wright@example.com",
            "percentage": 60.0
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.status_code, response.json())

JavaScript (Node.js)

const axios = require('axios');

const companyId = '2';
const url = `https://gateway.ahrvo.network/banking/ibans/v2/companies/${companyId}/onboarding-data`;
const headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
  'Content-Type': 'application/json'
};

const payload = {
  selectedProducts: ['Collect', 'Convert', 'Pay'],
  company: {
    type: 'Private Limited Company'
  },
  companyAddresses: [
    {
      type: 'REGISTERED',
      line1: '100 Bishopsgate',
      city: 'London',
      postalCode: 'EC2N 4AG',
      country: 'GB'
    }
  ],
  shareholders: [
    {
      type: 'INDIVIDUAL',
      firstName: 'Alexander',
      lastName: 'Wright',
      email: 'alex.wright@example.com',
      percentage: 60.0
    }
  ]
};

axios.post(url, payload, { headers })
  .then(res => console.log(res.data))
  .catch(err => console.error(err.response ? err.response.data : err.message));

Interactive API Explorer