Company (New) - Overview

Introduction

The Company (New) API provides hierarchical, multi-entity management for platforms, payment facilitators, and regulated financial institutions. It allows parent organizations to create and manage downstream sub-accounts for client companies, subsidiaries, or business units.

Once a sub-account is created, it receives a distinct company identifier (id) and reference code, enabling isolated onboarding, document verification, multi-currency wallets, and transactional operations within a scoped context.

Key Features

• Hierarchical Account Structure: Structure customer organizations under a primary parent entity with automatic parent-child linking.
• Independent Scoped Onboarding: Execute KYC, UBO screening, and document collection specifically for each downstream company.
• Isolated Balance Pools: Allocate separate multi-currency wallets, IBANs, and virtual accounts per sub-account.
• Granular Filtering & Discovery: Search and list sub-accounts by company name, external identifier, system IDs, or reference codes with sorting and pagination.
• Standardized Account Classifications: Support for SUB_CLIENT entities across all major global jurisdictions and industry sectors.

Authentication

All Company API endpoints require Bearer authentication using a valid access token obtained via the /users/login endpoint.

Authorization: Bearer <your_access_token>

An optional x-api-key header may also be supplied for merchant environment verification.

Base URLs

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

Sub-Account Lifecycle & Workflow

sequenceDiagram
    autonumber
    participant App as Platform / Parent Application
    participant API as Company API (/sub-accounts)
    participant Onb as Onboarding & KYC Engine
    participant Wal as Multi-Currency Wallet Engine

    App->>API: POST /sub-accounts (name, country, subCategory, identificationNumber, accountType="SUB_CLIENT")
    API-->>App: 201 Created (id: comp_982341, companyReference: CA-15092026-001, linkedStatus="ACCEPTED")
    Note over App,Onb: Subsequent Scoped Operations
    App->>Onb: POST /companies/{companyId}/onboarding-data (Scoped to sub-account ID)
    Onb-->>App: 200 OK (KYC & UBO data accepted)
    App->>Wal: Create Wallets & IBANs for sub-account
    Wal-->>App: Wallets allocated with independent balances

Account Types

Account Type	Description
SUB_CLIENT	Standard downstream corporate client or customer of the parent financial institution. Supported for full lifecycle onboarding and operations.
PARTNER_REFERRED	Downstream partner referral entity (reserved for future partner tiers).
RELATED_ENTITY	Internal affiliate or subsidiary entity under common corporate ownership.

Sub-Account Statuses

• companyStatus:
  • CREATED: The sub-account record has been registered and is ready for onboarding data submission.
  • APPROVED: Compliance and AML screening have successfully verified the sub-account.
  • REJECTED: Onboarding or compliance evaluation was declined.
• linkedStatus:
  • PENDING: Linkage authorization in progress.
  • ACCEPTED: Successfully linked and bound under the parent company.
  • REJECTED: Linkage declined or dissolved.

Support

For sub-account hierarchy questions or enterprise onboarding assistance, contact support@ahrvo.com.