Skip to main content

​
User API Documentation

​
Overview

The User API provides endpoints for managing users in the wallet service, including creation, updates, and user management operations.

​
Base URL

/api/v1/users

​
Authentication

All endpoints require authentication using an API key in the request headers:
  • X-API-KEY: Your API key
  • X-Tenant-ID: Tenant identifier (required for most endpoints)
  • countryCode: Country code (required for user creation)

​
Endpoints

​
Create User

Create a new user in the system. Endpoint: POST /register Headers:
  • X-API-KEY (optional): API key for authentication
  • X-Tenant-ID: Tenant identifier
  • countryCode: Country code
Request Body: 
{
  "fullName": "string",
  "phoneNumber": "string",
  "password": "string",
  "email": "string",
  "country": {
    "code": "string",
    "name": "string"
  },
  "type": "TENANT_ADMIN|TENANT_USER",
  "keyDuration": "number",
  "duration": "HOURS|DAYS|WEEKS|MONTHS|YEARS"
}
Response: 
{
  "statusCode": 201,
  "message": "string",
  "data": {
    "id": "number",
    "userId": "string",
    "tenant": {
      "tenantId": "string",
      "name": "string"
    },
    "fullName": "string",
    "phoneNumber": "string",
    "email": "string",
    "country": "string",
    "type": "string",
    "active": "boolean",
    "deleted": "boolean",
    "createdAt": "string",
    "updatedAt": "string"
  }
}

​
Update User

Update an existing user’s information. Endpoint: PATCH /update Headers:
  • X-API-KEY (optional): API key for authentication
  • X-Tenant-ID: Tenant identifier
Request Body: 
{
  "fullName": "string",
  "phoneNumber": "string",
  "email": "string",
  "country": "string"
}
Response: 
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "id": "number",
    "userId": "string",
    "tenant": {
      "tenantId": "string",
      "name": "string"
    },
    "fullName": "string",
    "phoneNumber": "string",
    "email": "string",
    "country": "string",
    "type": "string",
    "active": "boolean",
    "deleted": "boolean",
    "createdAt": "string",
    "updatedAt": "string"
  }
}

​
Get Users

Retrieve users with filtering and pagination. Endpoint: GET / Headers:
  • X-API-KEY (optional): API key for authentication
  • X-Tenant-ID (optional): Tenant identifier
Query Parameters:
  • userId: Filter by user ID (comma-separated for multiple IDs)
  • tenantId: Filter by tenant ID
  • fullName: Filter by full name
  • phoneNumber: Filter by phone number (comma-separated for multiple numbers)
  • email: Filter by email
  • country: Filter by country code (comma-separated for multiple countries)
  • type: Filter by user type (comma-separated for multiple types)
  • page: Page number (default: 0)
  • size: Page size (default: 20)
  • sort: Sort field and direction (e.g., “createdAt,desc”)
Response: 
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "content": [
      {
        "userId": "string",
        "fullName": "string",
        "phoneNumber": "string",
        "email": "string",
        "country": "string",
        "createdAt": "string",
        "updatedAt": "string",
        "type": "string",
        "tenantId": "string"
      }
    ],
    "totalElements": "number",
    "totalPages": "number",
    "size": "number",
    "number": "number"
  }
}

​
Activate/Deactivate User

Activate or deactivate a user account. Endpoint: GET /{userId}/{action} Headers:
  • X-API-KEY (optional): API key for authentication
  • X-Tenant-ID (optional): Tenant identifier
Path Parameters:
  • userId: User ID
  • action: Action to perform (ACTIVATE or DEACTIVATE)
Response: 
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "id": "number",
    "userId": "string",
    "tenant": {
      "tenantId": "string",
      "name": "string"
    },
    "fullName": "string",
    "phoneNumber": "string",
    "email": "string",
    "country": "string",
    "type": "string",
    "active": "boolean",
    "deleted": "boolean",
    "createdAt": "string",
    "updatedAt": "string"
  }
}

​
Error Responses

All endpoints may return the following error responses: 401 Unauthorized 
{
  "statusCode": 401,
  "message": "Unauthorized",
  "data": null
}
404 Not Found 
{
  "statusCode": 404,
  "message": "User not found",
  "data": null
}
409 Conflict 
{
  "statusCode": 409,
  "message": "Duplicate email",
  "data": null
}

​
Notes

  • All timestamps are in ISO-8601 format
  • User types:
    • TENANT_ADMIN: Can manage users within their tenant
    • TENANT_USER: Regular user within a tenant
  • Platform admins can create users for any tenant
  • Tenant admins can only create users for their own tenant
  • Regular users can only update their own profile
  • User activation/deactivation:
    • Platform admins can activate/deactivate any user
    • Tenant admins can only activate/deactivate users in their tenant
    • Regular users cannot activate/deactivate accounts
  • Email addresses must be unique across the system
  • Phone numbers must be valid for the specified country
  • User passwords are encrypted before storage
  • API keys are automatically generated for new users
  • User history is maintained for audit purposes
  • Deleted users are soft-deleted and can be restored