User Service
API reference for managing users within an entity.
The User Service allows you to create, update, and list users within your entity. Users must be created within an entity and can have their profiles updated with personal information.
Personal Entities
User creation is automatic when creating a personal entity. The system automatically creates a single user associated with that entity. All user fields (name, email, phone, etc.) should be provided during the personal entity creation request, and the user is provisioned automatically.
Business Entities
User creation is manual and requires explicit API calls. After creating a business entity, you must use the User Service endpoints to individually create each user that belongs to that business entity. Unlike personal entities where the user is auto-created during entity creation, business entities require you to:
- First create the business entity
- Then separately create each user with Create User, or through a hosted session using the
create_userflow - Associate each user with the business entity via the
entity_idfield
This manual approach allows business entities to have multiple users (employees, administrators, account managers, etc.), whereas personal entities have a single user that represents an individual person.
1. Create User
Creates a user under a business entity. For personal entities, the user is created automatically with the entity.
Subject: svc.user.<partner_id>.create
Request
| Field | Type | Required | Description |
|---|---|---|---|
entity_id | string | required | UUID of the business entity this user belongs to |
first_name | string | required | First name, at least 2 characters |
last_name | string | required | Last name, at least 2 characters |
email | string | required | Email address, must be a valid email |
phone_number | string | required | Phone number. Must be a valid number; it is stored in international format |
gender | string | required | One of: male, female, other (any case) |
date_of_birth | string | required | Date of birth, e.g. "1990-05-14T00:00:00Z". Cannot be in the future |
country | string | required | 2 or 3-letter country code, e.g. "ZAF" |
city | string | required | City, at least 2 characters |
residency | string | required | Residency, at least 2 characters |
id_number | string | required | ID or passport number, at least 2 characters |
id_type | string | required | "National" or "Passport". Any case is accepted; the user is stored and returned with "national" or "passport" in lowercase |
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" |
title | string | required | Title, e.g. Mr, Ms, Dr, at least 2 characters |
permit_number | string | optional | Work permit number, at least 2 characters |
address | object | optional | Residential address. If sent, address_line_1, city, state and postcode (at least 2 characters each) and country (ISO 3-letter code) are required; address_line_2 is optional. Needed before a physical card can be issued |
Response
| Field | Type | Description |
|---|---|---|
userId | string | UUID of the new user |
Iframe equivalent: Create User Session
The same user can 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, except that address is required, and the response is a hosted_url and iframe_url instead of userId. See Create User Session.
Possible Errors
400 Bad Request: Invalid request data, for example a missing field, an invalid phone number, or a passport withoutid_issue_expiry_date401 Unauthorized: Missing or invalid authentication403 Forbidden: Insufficient permissions404 Not Found: Entity not found
2. Update User Profile
Updates an existing user's profile information.
Subject: svc.user.<partner_id>.update
Request
| Field | Type | Required | Description |
|---|---|---|---|
user_id | string | required | UUID of the user to update |
first_name | string | optional | The user's first name, minimum 2 characters |
last_name | string | optional | The user's last name, minimum 2 characters |
email | string | optional | The user's email address, must be a valid email |
phone_number | string | optional | The user's phone number, minimum 2 characters |
gender | string | optional | The user's gender |
date_of_birth | string | optional | The user's date of birth, in ISO 8601 format |
birth_country | string | optional | 3-letter country code, specified separately from the user's current country |
birth_city | string | optional | The user's birth city, minimum 2 characters |
residency | string | optional | The user's residency, minimum 2 characters |
id_number | string | optional | The user's identification number, minimum 2 characters |
id_type | string | optional | "National" or "Passport". Stored in lowercase |
id_issue_date | string | optional | Date the ID was issued, in ISO 8601 format |
id_issue_expiry_date | string | optional | Date the ID expires, in ISO 8601 format |
title | string | optional | The user's title, minimum 2 characters |
permit_number | string | optional | The user's permit number, minimum 2 characters |
address | object | optional | The user's residential address. Send only the lines you want to change; every field inside it is optional |
address.address_line_1 | string | optional | First line of the address, minimum 2 characters |
address.address_line_2 | string | optional | Second line of the address |
address.city | string | optional | City, minimum 2 characters |
address.state | string | optional | State or province, minimum 2 characters |
address.country | string | optional | Country, ISO 3166 alpha-3 code, for example ZAF |
address.postcode | string | optional | Postcode, minimum 2 characters |
Response
| Field | Type | Description |
|---|---|---|
userId | string | UUID of the updated user |
Possible Errors
400 Bad Request: Invalid request data401 Unauthorized: Missing or invalid authentication403 Forbidden: Insufficient permissions404 Not Found: User not found
3. Get User
Retrieves a single user by user ID, including KYC status and verification details.
Subject: svc.user.<partner_id>.get
Permissions Required: read
Request
| Field | Type | Required | Description |
|---|---|---|---|
user_id | string | required | UUID of the user to retrieve |
Response
id_type is returned in lowercase: national or passport.
KYC Fields
verified: Boolean indicating whether the user is currently KYC verified. This is true when kyc_status is approved, and false when kyc_status is not_started, pending, or rejected. Use kyc_status for the detailed KYC lifecycle state, and verified as the simple approved/not-approved flag.kyc_status: Current KYC status. One of: not_started, pending, approved, rejected.kyc_submitted_at: Timestamp when KYC was submitted. Omitted if KYC has not been submitted.kyc_reviewed_at: Timestamp when KYC was approved or rejected. Omitted while KYC is pending or not started.kyc_rejection_reason: Reason for rejection. Only populated when kyc_status is rejected.
Possible Errors
400 Bad Request: Invalid request data401 Unauthorized: Missing or invalid authentication403 Forbidden: Insufficient permissions404 Not Found: User not found
4. List Users
Retrieves a list of users, including KYC status and verification details. Can be filtered by entity ID.
Subject: svc.user.<partner_id>.list
Permissions Required: read
Request
| Field | Type | Required | Description |
|---|---|---|---|
entity_id | string | optional | Filter results by entity |
Response
KYC Fields
verified: Boolean indicating whether the user is currently KYC verified. This is true when kyc_status is approved, and false when kyc_status is not_started, pending, or rejected. Use kyc_status for the detailed KYC lifecycle state, and verified as the simple approved/not-approved flag.kyc_status: Current KYC status. One of: not_started, pending, approved, rejected.kyc_submitted_at: Timestamp when KYC was submitted. Omitted if KYC has not been submitted.kyc_reviewed_at: Timestamp when KYC was approved or rejected. Omitted while KYC is pending or not started.kyc_rejection_reason: Reason for rejection. Only populated when kyc_status is rejected.
Possible Errors
400 Bad Request: Invalid request data401 Unauthorized: Missing or invalid authentication403 Forbidden: Insufficient permissions