Create a Sub-Account (New)

Overview

Create a sub-account for a downstream company, validate required fields like subCategory against supported industry classifications, and prepare the customer for onboarding and later scoped operations.

The created sub-account is automatically linked to the parent company initiating the request and receives a unique id and companyReference.

Resource Access

• HTTP Method: POST
• Endpoint: /banking/ibans/v2/sub-accounts
• Authentication: Bearer token required (Authorization: Bearer {access_token})

Request Headers

Header	Value	Required	Description
Accept	application/json	Yes	Content type for response
Authorization	Bearer {access_token}	Yes	Bearer token for authentication
Content-Type	application/json	Yes	Request body content type
x-api-key	string	No	Optional API key

Request Body

{
  "name": "Acme Innovations Ltd",
  "country": "United Kingdom",
  "subCategory": "Software Development and IT Services",
  "identificationNumber": "12345678",
  "taxIdOrEin": "GB987654321",
  "externalId": "ext_acme_001",
  "accountType": "SUB_CLIENT"
}

Request Fields

Field	Type	Required	Description
name	string	Yes	The registered legal name of the company with the respective government authority.
country	string	Yes	The country where the sub-account is incorporated (e.g. United Kingdom, United States).
subCategory	string	Yes	The company's industry classification or economic activity sector.
identificationNumber	string	Yes	Official company registration number or national registry ID.
taxIdOrEin	string	No	Tax registration number, VAT number, or EIN with the respective tax authority.
externalId	string	No	The company identification number in the client's internal system for mapping.
accountType	string	Yes	Type of account: SUB_CLIENT (recommended), PARTNER_REFERRED, or RELATED_ENTITY.

Response

Success Response (201 Created)

{
  "id": "comp_982341",
  "externalId": "ext_acme_001",
  "parentCompanyId": "comp_100201",
  "name": "Acme Innovations Ltd",
  "country": "United Kingdom",
  "category": "Technology",
  "subCategory": "Software Development and IT Services",
  "identificationNumber": "12345678",
  "taxIdOrEin": "GB987654321",
  "accountType": "SUB_CLIENT",
  "companyReference": "CA-15092026-001",
  "companyStatus": "CREATED",
  "linkedStatus": "ACCEPTED",
  "linkedAt": "2026-09-15T10:00:00Z",
  "createdAt": "2026-09-15T10:00:00Z",
  "updatedAt": "2026-09-15T10:00:00Z"
}

Response Fields

Field	Type	Description
id	string	Unique system identifier assigned to the newly created sub-account. Use this as {companyId} in downstream onboarding and wallet routes.
externalId	string	The client system external identifier supplied in the request.
parentCompanyId	string	The company ID of the parent account that owns this sub-account.
name	string	Registered legal business name.
country	string	Country of incorporation.
category	string	Primary industry sector determined from classification.
subCategory	string	Specific industry classification.
identificationNumber	string	Official government business registry ID.
taxIdOrEin	string	Tax identification number.
accountType	string	Assigned account type (SUB_CLIENT).
companyReference	string	Unique reference string formatted for public display and audit logs.
companyStatus	string	Current lifecycle status (CREATED, APPROVED, REJECTED).
linkedStatus	string	Status of parent-child binding (ACCEPTED, PENDING, REJECTED).
createdAt	string (ISO Date)	Timestamp of sub-account creation.
updatedAt	string (ISO Date)	Timestamp of last modification.

Error Responses

• 400 Bad Request: Missing mandatory fields (name, country, subCategory, identificationNumber, accountType) or invalid country name.
• 401 Unauthorized: Missing or expired Bearer token.
• 403 Forbidden: Insufficient privileges to create downstream sub-accounts.
• 500 Internal Server Error: Internal platform error during entity provisioning.

Code Examples

cURL

curl -X POST "https://api.ahrvo.network/banking/ibans/v2/sub-accounts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Acme Innovations Ltd",
    "country": "United Kingdom",
    "subCategory": "Software Development and IT Services",
    "identificationNumber": "12345678",
    "taxIdOrEin": "GB987654321",
    "externalId": "ext_acme_001",
    "accountType": "SUB_CLIENT"
  }'

Python

import requests

url = "https://api.ahrvo.network/banking/ibans/v2/sub-accounts"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
payload = {
    "name": "Acme Innovations Ltd",
    "country": "United Kingdom",
    "subCategory": "Software Development and IT Services",
    "identificationNumber": "12345678",
    "taxIdOrEin": "GB987654321",
    "externalId": "ext_acme_001",
    "accountType": "SUB_CLIENT"
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()
print("Created Sub-Account ID:", data.get("id"))
print("Company Reference:", data.get("companyReference"))

JavaScript / Node.js

const response = await fetch("https://api.ahrvo.network/banking/ibans/v2/sub-accounts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
    name: "Acme Innovations Ltd",
    country: "United Kingdom",
    subCategory: "Software Development and IT Services",
    identificationNumber": "12345678",
    taxIdOrEin": "GB987654321",
    externalId": "ext_acme_001",
    accountType: "SUB_CLIENT"
  })
});

const subAccount = await response.json();
console.log("Sub-Account ID:", subAccount.id);
console.log("Status:", subAccount.companyStatus);

Interactive API Explorer