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. Root Business Entity
  4. Create Entity
  5. Get Entity Info
  6. List Entities
  7. Update Entity Address

Root Business Entity

As part of onboarding, we will create a business entity on Production for your organization. Internally, this is referred to as your “root business entity.”

You can have multiple business entities in SAVA, and this one will be your own business entity created for you during setup. As a consequence, there is no need for you to create a business entity that is linked to your business.

When we create this root business entity, an account will also be created automatically after compliance approves. That account is your partner pool account. You can still create additional accounts under this business entity as needed.

To view this entity in your environment, use the List Entities endpoint that is already available in your generated client and documented here.

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 via the Create Account endpoint
  • •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 using the Create Account endpoint, which creates a new banking account for an entity.
  • Each account has a unique account number
  • All accounts are linked to the parent entity
  • No limit on the number of accounts per 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