API References

Entity Service

API reference for managing business and personal entities.

Root Business Entity

As part of onboarding, we will create a business entity on Production for you. 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 business
  • 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 business or personal entity.

Subject: svc.entity.<partner_id>.create

Request for Business Entity

Request
{
  "name": "Example Trading (Pty) Ltd",              // Required: company name, at least 2 characters
  "trading_name": "Example Trading",                // Required for a business entity
  "registration_number": "2020/015825/07",          // Required: 12 characters once any "/" are removed
  "tax_number": "9012345678",                       // Optional: at least 2 characters
  "email": "finance@example.co.za",                 // Required: business email
  "country": "ZAF",                                  // Required: ZAF or KEN
  "entity_type": "business",                         // Required: must be "business"
  "source_of_funds": "Revenue from retail sales",   // Required: up to 300 characters
  "industry": "Retail",                              // Required: up to 64 characters
  "business_size": "10-30"                           // Required: a count ("25"), a range ("10-30") or open-ended ("50+")
}
FieldTypeRequiredDescription
namestringrequiredCompany name, at least 2 characters
trading_namestringrequiredTrading name
registration_numberstringrequiredCompany registration number: 12 characters once any "/" are removed, e.g. "2020/015825/07". For ZAF, it must match a company on record
tax_numberstringoptionalTax number, at least 2 characters
emailstringrequiredBusiness email address
countrystringrequiredISO 3-letter country code: "ZAF" or "KEN"
entity_typestringrequiredMust be "business"
source_of_fundsstringrequiredWhere the business's funds come from. Free text, up to 300 characters
industrystringrequiredThe business's industry. Free text, up to 64 characters
business_sizestringrequiredNumber of employees, as a string: a count ("25"), a range ("10-30", upper bound not below the lower) or open-ended ("50+"). Whole numbers from 1, no leading zeros

Request for Personal Entity

Request
{
  "name": "Jane Doe",                                 // Required: at least 2 characters
  "entity_type": "personal",                          // Required: must be "personal"
  "email": "jane.doe@example.com",                    // Required: personal email
  "country": "ZAF",                                    // Required: ZAF or KEN
  "first_name": "Jane",                               // Required: at least 2 characters
  "last_name": "Doe",                                 // Required: at least 2 characters
  "phone_number": "+27821234567",                     // Required
  "gender": "female",                                 // Required: male, female or other
  "date_of_birth": "1990-05-14T00:00:00Z",            // Required: not in the future
  "id_number": "9005140123087",                       // Required: 13 digits for a National ID
  "id_type": "National",                              // Required: "National" or "Passport", exact case
  "id_issue_date": "2010-03-01T00:00:00Z",            // Required: not in the future
  "id_issue_expiry_date": "2030-03-01T00:00:00Z",     // Required for Passport, optional for National
  "city": "Johannesburg",                             // Optional: at least 2 characters
  "residency": "string",                              // Optional
  "title": "Ms",                                      // Optional
  "permit_number": "string",                          // Optional: for non-citizens
  "address": {                                        // Optional: residential address
    "address_line_1": "12 Main Road",
    "address_line_2": "Unit 4",
    "city": "Johannesburg",
    "state": "Gauteng",
    "postcode": "2196"
  }
}
FieldTypeRequiredDescription
namestringrequiredEntity name, at least 2 characters. Usually the person's full name
entity_typestringrequiredMust be "personal"
emailstringrequiredPersonal email address
countrystringrequiredISO 3-letter country code: "ZAF" or "KEN"
first_namestringrequiredFirst name, at least 2 characters
last_namestringrequiredLast name, at least 2 characters
phone_numberstringrequiredPhone number
genderstringrequiredOne of: male, female, other
date_of_birthstringrequiredDate of birth, e.g. "1990-05-14T00:00:00Z". Cannot be in the future
id_numberstringrequiredNational ID or passport number. A National ID must be exactly 13 digits
id_typestringrequired"National" or "Passport", exactly as written (case-sensitive: "national" is rejected)
id_issue_datestringrequiredDate the ID was issued. Cannot be in the future or after the expiry date
id_issue_expiry_datestringoptionalID expiry date. Required when id_type is "Passport"
citystringoptionalCity of residence, at least 2 characters
residencystringoptionalResidency status
titlestringoptionalTitle, e.g. Mr, Ms, Dr, Mx
permit_numberstringoptionalWork permit number, for non-citizens
addressobjectoptionalResidential address. If sent, address_line_1, city, state and postcode are required (at least 2 characters each); address_line_2 is optional. The entity's country is used as the address country

The user is created automatically

A personal entity gets one user, created automatically from the same details, so you don't call Create User. Duplicate National ID numbers are rejected within your partner account.

Response

Response
{
  "id": "6b1f0f7e-2c4a-4d3e-9b8a-1f2e3d4c5b6a",
  "user_id": "40ec785e-d915-49de-9053-4630042d8182",
  "user_ready": true
}
FieldTypeDescription
idstringUUID of the new entity
user_idstringPersonal entities only: the UUID of the user created automatically. Left out if the user is not ready yet
user_readybooleanPersonal entities only: true if the user already exists. Always false for business entities

SAVA waits up to 3 seconds for a personal entity's user. If user_ready is false, the user is still being created: find it with List Users using the entity's id.

Iframe equivalent: Create Business Entity and Create Personal Entity Sessions

Either entity type can also be created through a hosted session, where the end user gives consent and submits inside a SAVA-owned page that you embed in an iframe (or WebView). The request body is the same as above, and the response is a hosted_url and iframe_url instead of the entity id.

Possible Errors

  • 400 Bad Request: Invalid input or a failed validation, for example a registration number that isn't 12 characters, an unknown company, an invalid business_size, or a National ID that isn't 13 digits
  • 409 Conflict: The entity already exists in your partner account (same registration number, or same National ID number)
  • 500 Internal Server Error: Error creating the entity

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
}
FieldTypeRequiredDescription
entity_iduuidrequiredThe 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
    }
  ]
}

Each object in the entities array has the following fields:

FieldTypeDescription
idstring
namestring
trading_namestringEmpty for personal entities
registration_numberstringEmpty for personal entities
emailstring
created_attimestamp
entity_typestring"Business" or "Personal" (capitalized)
first_namestringEmpty for business entities
last_namestringEmpty for business entities
phone_numberstringEmpty for business entities
genderstringEmpty for business entities
date_of_birthtimestamp0001-01-01T00:00:00Z for business entities
id_numberstringEmpty for business entities
id_typestring"National" or "Passport" for personal entities. Empty for business entities
id_issue_datetimestamp0001-01-01T00:00:00Z for business entities
id_issue_expiry_datetimestamp0001-01-01T00:00:00Z for business entities
citystringEmpty for business entities
residencystringEmpty for business entities
titlestringEmpty for business entities
permit_numberstringEmpty 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
}
FieldTypeRequiredDescription
entity_idstringrequired
address_line_1stringrequired
address_line_2stringoptional
statestringoptional
postcodestringoptional
countrystringoptionalISO 3-letter country code
citystringoptional

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