Documentation/API/Entity API

Entity Service

API reference for managing organizations, businesses, and personal entities

VERTEX ENGINE

00

Table of Contents

  1. Entity Types Overview
  2. Entity-Account Relationship
  3. Create Entity
  4. Get Entity Info
  5. List Entities
  6. Update Entity Address

Entity Types Overview

The Entity service supports two types of entities: Business entities and Personal entities. Each type has different requirements and automated processes.

Business Entity

  • •Represents a company or organization
  • •Requires KYB (Know Your Business) verification
  • •First account created automatically after KYB approval
  • •Can create multiple accounts
  • •Requires registration number and trading name
  • •Users must be created manually via the User Service

Personal Entity

  • •Represents an individual person
  • •Requires KYC (Know Your Customer) verification
  • •First account created automatically after KYC approval
  • •User created automatically upon entity creation
  • •Requires personal details (name, ID, date of birth, etc.)
  • •Suitable for individual banking needs

ℹ️ Automatic User Creation for Personal Entities

When a personal entity is created, a corresponding user is automatically created with the same details. This streamlines the onboarding process for individual customers.

Entity-Account Relationship

The relationship between entities and accounts differs based on the entity type.

Business Entities

Business Account Creation Process

  • First account is automatically created after successful KYB verification
  • Additional accounts can be created by calling the entity endpoint again
  • Each account has a unique account number
  • All accounts are linked to the parent entity
  • No limit on the number of accounts per entity

Benefits of Multiple Accounts

  • •Segregate funds by department, project, or purpose
  • •Simplify financial organization
  • •Improve financial reporting and reconciliation
  • •Enable better cash flow management
  • •Support compliance requirements for fund segregation

Personal Entities

Personal Entity Process

  • •User account is automatically created when personal entity is created
  • •User inherits all personal details from the entity
  • •Account creation follows after KYC verification
  • •Single user per personal entity

1. Create Entity

Creates a new entity in the system.

Subject: svc.entity.<partner_id>.create

Request for Business Entity

{
  "name": "string",               // Required - Company name
  "trading_name": "string",       // Required - Trading name
  "tax_number": "string",         // Optional - Tax number
  "registration_number": "string", // Required - Company registration number (12 digits)
  "email": "string",              // Required - Business email
  "country": "string",            // Required - ISO 3-letter country code (e.g., "ZAF")
  "entity_type": "business"       // Required - Must be "business"
}

Required Fields for Business Entity

  • name - Company name
  • trading_name - Trading name
  • registration_number - Company registration number (12 digits)
  • email - Business email
  • country - ISO 3-letter country code
  • entity_type - Must be "business"

Request for Personal Entity

{
  "name": "string",               // Optional - Will be auto-generated from first_name + last_name
  "entity_type": "personal",      // Required - Must be "personal"
  "email": "string",              // Required - Personal email
  "country": "string",            // Required - ISO 3-letter country code (e.g., "ZAF")
  "first_name": "string",         // Required - First name
  "last_name": "string",          // Required - Last name
  "phone_number": "string",       // Required - Phone number
  "gender": "string",             // Required - One of: male, female, other
  "date_of_birth": "string",      // Required - Format: "YYYY-MM-DDTHH:MM:SSZ"
  "id_number": "string",          // Required - National ID or passport number
  "id_type": "string",            // Required - One of: National, Passport
  "id_issue_date": "string",      // Required - Format: "YYYY-MM-DDTHH:MM:SSZ"
  "id_issue_expiry_date": "string", // Optional - Format: "YYYY-MM-DDTHH:MM:SSZ"
  "city": "string",               // Optional - City of residence
  "residency": "string",          // Optional - Residency status
  "title": "string",              // Optional - Title (e.g., Mr, Ms, Dr, Mx)
  "permit_number": "string"       // Optional - Work permit number (for non-citizens)
}

Required Fields for Personal Entity

  • entity_type - Must be "personal"
  • email - Personal email
  • country - ISO 3-letter country code
  • first_name - First name
  • last_name - Last name
  • phone_number - Phone number
  • gender - One of: male, female, other
  • date_of_birth - Format: YYYY-MM-DDTHH:MM:SSZ
  • id_number - National ID or passport number
  • id_type - One of: National, Passport
  • id_issue_date - Format: YYYY-MM-DDTHH:MM:SSZ

ℹ️ ID Type Validation

  • For National ID type: ID number must be exactly 13 digits
  • For Passport type: Any alphanumeric format is accepted

Response

{
  "id": "uuid"  // The ID of the newly created entity
}

Possible Errors

  • 400 Bad Request: Invalid input data or validation failure
  • 409 Conflict: Entity already exists (duplicate ID number or registration number)
  • 500 Internal Server Error: Error creating organization

2. Get Entity Info

Retrieves information about a specific entity.

Subject: svc.entity.<partner_id>.info

Request

{
  "entity_id": "uuid"  // Required - The entity ID to retrieve
}

Response for Business Entity

{
  "id": "uuid",
  "date_created": "string",
  "name": "string",
  "trading_name": "string",
  "entity_type": "business",
  "email": "string",
  "approved": boolean
}

Response for Personal Entity

{
  "id": "uuid",
  "date_created": "string",
  "name": "string",
  "entity_type": "personal",
  "email": "string",
  "approved": boolean,
  "first_name": "string",
  "last_name": "string",
  "phone_number": "string",
  "gender": "string",
  "date_of_birth": "string",
  "id_number": "string",
  "id_type": "string",
  "id_issue_date": "string",
  "id_issue_expiry_date": "string",
  "city": "string",
  "residency": "string",
  "title": "string",
  "permit_number": "string"
}

Possible Errors

  • 400 Bad Request: Invalid request data
  • 403 Forbidden: Permission denied
  • 404 Not Found: Entity not found

3. List Entities

Retrieves a list of all entities for the authenticated partner.

Subject: svc.entity.<partner_id>.list-entities

Request

{}  // Empty object - partner_id is automatically injected from the authentication token

Response

{
  "entities": [
    {
      "id": "string",
      "name": "string",
      "trading_name": "string",              // Empty for personal entities
      "registration_number": "string",       // Empty for personal entities
      "email": "string",
      "created_at": "timestamp",
      "entity_type": "string",               // "Business" or "Personal" (capitalized)
      "first_name": "string",                // Empty for business entities
      "last_name": "string",                 // Empty for business entities
      "phone_number": "string",              // Empty for business entities
      "gender": "string",                    // Empty for business entities
      "date_of_birth": "timestamp",          // 0001-01-01T00: 00: 00Z for business entities
      "id_number": "string",                 // Empty for business entities
      "id_type": "string",                   // Empty for business entities
      "id_issue_date": "timestamp",          // 0001-01-01T00: 00: 00Z for business entities
      "id_issue_expiry_date": "timestamp",   // 0001-01-01T00: 00: 00Z for business entities
      "city": "string",                      // Empty for business entities
      "residency": "string",                 // Empty for business entities
      "title": "string",                     // Empty for business entities
      "permit_number": "string"              // Empty for business entities
    }
  ]
}

Possible Errors

  • 403 Forbidden: Permission denied (missing "read" permission)

4. Update Entity Address

Updates the address information for an entity.

Subject: svc.entity.<partner_id>.update_address

Request

{
  "entity_id": "string",      // Required
  "address_line_1": "string", // Required
  "address_line_2": "string", // Optional
  "state": "string",          // Optional
  "postcode": "string",       // Optional
  "country": "string",        // Optional - ISO 3-letter country code
  "city": "string"            // Optional
}

Required Fields

  • entity_id
  • address_line_1

Response

{
  // Empty response indicates success
}

Possible Errors

  • 400 Bad Request: Invalid input data
  • 404 Not Found: Entity not found
  • 500 Internal Server Error: Error updating address
Previous: AuthenticationNext: KYB