Documentation/API/Users

User Service

API reference for managing users within an organization

VERTEX ENGINE

00

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.

Important Note

Personal Entities: User creation is automatic when creating a personal entity. All user fields should be provided during entity creation.

Business Entities: These endpoints are used to manually create and manage users within business entities.

Table of Contents

  1. Create User
  2. Update User Profile
  3. List Users

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 - minimum 2 characters
  "id_issue_date": "2023-01-01T00:00:00Z",       // Required - ISO 8601 format
  "id_issue_expiry_date": "2025-01-01T00:00:00Z", // Required - ISO 8601 format
  "title": "string",              // Required - minimum 2 characters
  "verified": false,              // Required - boolean
  "permit_number": "string"       // Required - minimum 2 characters
}

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 data
  • 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

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