API References

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:

  1. First create the business entity
  2. Then separately create each user with Create User, or through a hosted session using the create_user flow
  3. Associate each user with the business entity via the entity_id field

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

Request
{
  "entity_id": "550e8400-e29b-41d4-a716-446655440000", // Required: UUID of the business entity
  "first_name": "Jane",                               // Required: at least 2 characters
  "last_name": "Doe",                                 // Required: at least 2 characters
  "email": "jane.doe@example.com",                    // Required: valid email
  "phone_number": "+27821234567",                     // Required: valid phone number
  "gender": "female",                                 // Required: male, female or other
  "date_of_birth": "1990-05-14T00:00:00Z",            // Required: not in the future
  "country": "ZAF",                                    // Required: 2 or 3-letter country code
  "city": "Johannesburg",                             // Required: at least 2 characters
  "residency": "South Africa",                        // Required: at least 2 characters
  "id_number": "9005140123087",                       // Required: at least 2 characters
  "id_type": "National",                              // Required: "National" or "Passport"
  "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
  "title": "Ms",                                      // Required: at least 2 characters
  "permit_number": "string",                          // Optional: at least 2 characters
  "address": {                                        // Optional here; needed for physical cards
    "address_line_1": "12 Main Road",
    "address_line_2": "Unit 4",
    "city": "Johannesburg",
    "state": "Gauteng",
    "country": "ZAF",
    "postcode": "2196"
  }
}
FieldTypeRequiredDescription
entity_idstringrequiredUUID of the business entity this user belongs to
first_namestringrequiredFirst name, at least 2 characters
last_namestringrequiredLast name, at least 2 characters
emailstringrequiredEmail address, must be a valid email
phone_numberstringrequiredPhone number. Must be a valid number; it is stored in international format
genderstringrequiredOne of: male, female, other (any case)
date_of_birthstringrequiredDate of birth, e.g. "1990-05-14T00:00:00Z". Cannot be in the future
countrystringrequired2 or 3-letter country code, e.g. "ZAF"
citystringrequiredCity, at least 2 characters
residencystringrequiredResidency, at least 2 characters
id_numberstringrequiredID or passport number, at least 2 characters
id_typestringrequired"National" or "Passport". Any case is accepted; the user is stored and returned with "national" or "passport" in lowercase
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"
titlestringrequiredTitle, e.g. Mr, Ms, Dr, at least 2 characters
permit_numberstringoptionalWork permit number, at least 2 characters
addressobjectoptionalResidential 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

Response
{
  "userId": "40ec785e-d915-49de-9053-4630042d8182"
}
FieldTypeDescription
userIdstringUUID 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 without id_issue_expiry_date
  • 401 Unauthorized: Missing or invalid authentication
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Entity not found

2. Update User Profile

Updates an existing user's profile information.

Subject: svc.user.<partner_id>.update

Request

Request
{
  "user_id": "40ec785e-d915-49de-9053-4630042d8182", // Required: UUID
  "first_name": "string",         // Optional: minimum 2 characters
  "last_name": "string",          // Optional: minimum 2 characters
  "email": "string",              // Optional: must be valid email
  "phone_number": "string",       // Optional: minimum 2 characters
  "gender": "string",             // Optional
  "date_of_birth": "2023-01-01T00:00:00Z", // Optional: ISO 8601 format
  "birth_country": "ZAF",         // Optional: 3-letter country code
  "birth_city": "string",         // Optional: minimum 2 characters
  "residency": "string",          // Optional: minimum 2 characters
  "id_number": "string",          // Optional: minimum 2 characters
  "id_type": "National",          // Optional: "National" or "Passport"
  "id_issue_date": "2023-01-01T00:00:00Z",       // Optional: ISO 8601 format
  "id_issue_expiry_date": "2025-01-01T00:00:00Z", // Optional: ISO 8601 format
  "title": "string",              // Optional: minimum 2 characters
  "permit_number": "string",      // Optional: minimum 2 characters
  "address": {                    // Optional: send only the lines you want to change
    "address_line_1": "12 Main Road",   // Optional: minimum 2 characters
    "address_line_2": "Unit 4",         // Optional
    "city": "Johannesburg",             // Optional: minimum 2 characters
    "state": "Gauteng",                 // Optional: minimum 2 characters
    "country": "ZAF",                   // Optional: ISO 3166 alpha-3
    "postcode": "2196"                  // Optional: minimum 2 characters
  }
}
FieldTypeRequiredDescription
user_idstringrequiredUUID of the user to update
first_namestringoptionalThe user's first name, minimum 2 characters
last_namestringoptionalThe user's last name, minimum 2 characters
emailstringoptionalThe user's email address, must be a valid email
phone_numberstringoptionalThe user's phone number, minimum 2 characters
genderstringoptionalThe user's gender
date_of_birthstringoptionalThe user's date of birth, in ISO 8601 format
birth_countrystringoptional3-letter country code, specified separately from the user's current country
birth_citystringoptionalThe user's birth city, minimum 2 characters
residencystringoptionalThe user's residency, minimum 2 characters
id_numberstringoptionalThe user's identification number, minimum 2 characters
id_typestringoptional"National" or "Passport". Stored in lowercase
id_issue_datestringoptionalDate the ID was issued, in ISO 8601 format
id_issue_expiry_datestringoptionalDate the ID expires, in ISO 8601 format
titlestringoptionalThe user's title, minimum 2 characters
permit_numberstringoptionalThe user's permit number, minimum 2 characters
addressobjectoptionalThe user's residential address. Send only the lines you want to change; every field inside it is optional
address.address_line_1stringoptionalFirst line of the address, minimum 2 characters
address.address_line_2stringoptionalSecond line of the address
address.citystringoptionalCity, minimum 2 characters
address.statestringoptionalState or province, minimum 2 characters
address.countrystringoptionalCountry, ISO 3166 alpha-3 code, for example ZAF
address.postcodestringoptionalPostcode, minimum 2 characters

Response

{
  "userId": "40ec785e-d915-49de-9053-4630042d8182"  // UUID of the updated user
}
FieldTypeDescription
userIdstringUUID of the updated user

Possible Errors

  • 400 Bad Request: Invalid request data
  • 401 Unauthorized: Missing or invalid authentication
  • 403 Forbidden: Insufficient permissions
  • 404 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

Request
{
  "user_id": "40ec785e-d915-49de-9053-4630042d8182"  // Required: UUID of the user to retrieve
}
FieldTypeRequiredDescription
user_idstringrequiredUUID of the user to retrieve

Response

{
  "user": {
    "id": "40ec785e-d915-49de-9053-4630042d8182",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_number": "+27123456789",
    "entity_id": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2023-11-15T10:30:45Z",
    "updated_at": "2023-11-16T14:22:31Z",
    "verified": true,
    "verified_at": "2024-08-01T15:30:45Z",
    "gender": "Male",
    "date_of_birth": "1990-01-01T00:00:00Z",
    "country": "ZAF",
    "city": "Johannesburg",
    "residency": "South Africa",
    "id_number": "9001015800084",
    "id_type": "national",
    "id_issue_date": "2020-01-15T00:00:00Z",
    "id_issue_expiry": "2030-01-15T00:00:00Z",
    "title": "Mr",
    "permit_number": "",
    "kyc_status": "approved",
    "kyc_submitted_at": "2024-08-01T14:00:00Z",
    "kyc_reviewed_at": "2024-08-01T15:30:45Z",
    "kyc_rejection_reason": ""
  }
}

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 data
  • 401 Unauthorized: Missing or invalid authentication
  • 403 Forbidden: Insufficient permissions
  • 404 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

Request
{
  "entity_id": "550e8400-e29b-41d4-a716-446655440000"  // Optional: Filter by entity UUID
}
FieldTypeRequiredDescription
entity_idstringoptionalFilter results by entity

Response

{
  "users": [
    {
      "id": "40ec785e-d915-49de-9053-4630042d8182",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone_number": "+27123456789",
      "entity_id": "550e8400-e29b-41d4-a716-446655440000",
      "created_at": "2023-11-15T10:30:45Z",
      "updated_at": "2023-11-16T14:22:31Z",
      "verified": true,
      "verified_at": "2024-08-01T15:30:45Z",
      "gender": "Male",
      "date_of_birth": "1990-01-01T00:00:00Z",
      "country": "ZAF",
      "city": "Johannesburg",
      "residency": "South Africa",
      "id_number": "9001015800084",
      "id_type": "national",
      "id_issue_date": "2020-01-15T00:00:00Z",
      "id_issue_expiry": "2030-01-15T00:00:00Z",
      "title": "Mr",
      "date_registered": "2023-11-15T10:30:45Z",
      "permit_number": "",
      "kyc_status": "approved",
      "kyc_submitted_at": "2024-08-01T14:00:00Z",
      "kyc_reviewed_at": "2024-08-01T15:30:45Z",
      "kyc_rejection_reason": ""
    }
  ]
}

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 data
  • 401 Unauthorized: Missing or invalid authentication
  • 403 Forbidden: Insufficient permissions

On this page