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
| Field | Type | Required | Description |
|---|---|---|---|
name | string | required | Company name, at least 2 characters |
trading_name | string | required | Trading name |
registration_number | string | required | Company registration number: 12 characters once any "/" are removed, e.g. "2020/015825/07". For ZAF, it must match a company on record |
tax_number | string | optional | Tax number, at least 2 characters |
email | string | required | Business email address |
country | string | required | ISO 3-letter country code: "ZAF" or "KEN" |
entity_type | string | required | Must be "business" |
source_of_funds | string | required | Where the business's funds come from. Free text, up to 300 characters |
industry | string | required | The business's industry. Free text, up to 64 characters |
business_size | string | required | Number 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
| Field | Type | Required | Description |
|---|---|---|---|
name | string | required | Entity name, at least 2 characters. Usually the person's full name |
entity_type | string | required | Must be "personal" |
email | string | required | Personal email address |
country | string | required | ISO 3-letter country code: "ZAF" or "KEN" |
first_name | string | required | First name, at least 2 characters |
last_name | string | required | Last name, at least 2 characters |
phone_number | string | required | Phone number |
gender | string | required | One of: male, female, other |
date_of_birth | string | required | Date of birth, e.g. "1990-05-14T00:00:00Z". Cannot be in the future |
id_number | string | required | National ID or passport number. A National ID must be exactly 13 digits |
id_type | string | required | "National" or "Passport", exactly as written (case-sensitive: "national" is rejected) |
id_issue_date | string | required | Date the ID was issued. Cannot be in the future or after the expiry date |
id_issue_expiry_date | string | optional | ID expiry date. Required when id_type is "Passport" |
city | string | optional | City of residence, at least 2 characters |
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 |
address | object | optional | Residential 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
| Field | Type | Description |
|---|---|---|
id | string | UUID of the new entity |
user_id | string | Personal entities only: the UUID of the user created automatically. Left out if the user is not ready yet |
user_ready | boolean | Personal 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.
- Business entity: Create Business Entity Session
- Personal entity: Create Personal Entity Session
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 invalidbusiness_size, or a National ID that isn't 13 digits409 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
| Field | Type | Required | Description |
|---|---|---|---|
entity_id | uuid | required | The entity ID to retrieve |
Response for Business Entity
Response for Personal Entity
Possible Errors
400 Bad Request: Invalid request data403 Forbidden: Permission denied404 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
Response
Each object in the entities array has the following fields:
| Field | Type | Description |
|---|---|---|
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 | "National" or "Passport" for personal entities. 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
| Field | Type | Required | Description |
|---|---|---|---|
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 |
Response
Possible Errors
400 Bad Request: Invalid input data404 Not Found: Entity not found500 Internal Server Error: Error updating address