User Service
API reference for managing users within an organization
VERTEX ENGINE
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 using
svc.user.<partner_id>.create - 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.
Table of Contents
1. Create User
Creates a new user within a business entity. For personal entities, users are created automatically during entity creation.
Subject: svc.user.<partner_id>.create
Request
{
"entity_id": "550e8400-e29b-41d4-a716-446655440000", // Required - UUID
"first_name": "string", // Required - minimum 2 characters
"last_name": "string", // Required - minimum 2 characters
"email": "string", // Required - must be valid email
"phone_number": "string", // Required - minimum 2 characters
"gender": "string", // Required
"date_of_birth": "2023-01-01T00:00:00Z", // Required - ISO 8601 format
"country": "ZAF", // Required - 3-letter country code
"city": "string", // Required - minimum 2 characters
"residency": "string", // Required - minimum 2 characters
"id_number": "string", // Required - minimum 2 characters
"id_type": "string", // Required - Use "National" for national ID (no expiry needed) or "passport" for passport (requires id_issue_expiry_date)
"id_issue_date": "2023-01-01T00:00:00Z", // Required - ISO 8601 format
"id_issue_expiry_date": "2025-01-01T00:00:00Z", // Required for passport; not required for National ID
"title": "string", // Required - minimum 2 characters
"verified": false, // Required - boolean
"permit_number": "string" // Required - minimum 2 characters
}ID Type Requirements
- National – For a national identification number; no expiry date is required.
- passport – For a passport number. When you send
passport, you must also includeid_issue_expiry_date, or the request will fail.
Required Fields
All fields are required for user creation.
Field Validations
- String fields require minimum 2 characters
- Email must be a valid email format
- Country must be a 3-letter ISO country code
- Dates must be in ISO 8601 format
Response
{
"userId": "40ec785e-d915-49de-9053-4630042d8182" // UUID of the created user
}Possible Errors
400 Bad Request: Invalid request data401 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
{
"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": "string", // Optional - minimum 2 characters
"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
}Required Fields
user_id- UUID of the user to update
Notes
- Only provided fields will be updated
- Birth country is specified separately from the user's current country
Response
{
"userId": "40ec785e-d915-49de-9053-4630042d8182" // 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. List Users
Retrieves a list of users. Can be filtered by entity ID.
Subject: svc.user.<partner_id>.list
Request
{
"entity_id": "550e8400-e29b-41d4-a716-446655440000" // Optional - Filter by entity UUID
}Optional Fields
entity_id- Filter 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,
"gender": "Male",
"date_of_birth": "1990-01-01T00:00:00Z",
"country": "ZAF",
"city": "Johannesburg",
"residency": "South Africa",
"id_number": "9001015800084",
"id_type": "National ID",
"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": ""
}
]
}Possible Errors
400 Bad Request: Invalid request data401 Unauthorized: Missing or invalid authentication403 Forbidden: Insufficient permissions