https://api.novacash.bi/v1Users API
The Users API provides comprehensive management of user accounts within the NovaCash system. This API allows you to create, retrieve, update, and delete user accounts, manage user roles and permissions, handle user authentication, and perform various user-related operations.
User Object
The User object represents an individual user account in the NovaCash system. Each user has a unique identifier and contains personal information, authentication details, account status, and role-based permissions.
Key Attributes
| Attribute | Type | Description |
|---|---|---|
| id | string | Unique identifier for the user |
| phone | string | Phone number in E.164 format, used as primary identifier |
| first_name | string | User's first name |
| last_name | string | User's last name |
| string | User's email address (optional) | |
| role | string | User role: user, agent, super_agent, partner_inember, partner, admin |
| status | string | Account status: active, pending, blocked, suspended |
| balance | number | Current account balance in BIF |
| created_at | string | Timestamp when the user was created |
| updated_at | string | Timestamp when the user was last updated |
| last_login | string | Timestamp of the user's last login |
| verified_at | string | Timestamp when the user was verified |
GET /users
Description
Retrieve a list of users
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| page | number | Optional | Page number for pagination |
| limit | number | Optional | Number of items per page |
| status | string | Optional | Filter by user status (active, pending, blocked, suspended) |
| role | string | Optional | Filter by user role (user, agent, super_agent, partner_inember, partner, admin) |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | The request is understood, but it has been refused due to permissions |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Query Parameters
Page number for pagination
Number of items per page
Filter by user status (active, pending, blocked, suspended)
Filter by user role (user, agent, super_agent, partner_inember, partner, admin)
POST /users
Description
Create a new user
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 400 | Bad Request | Invalid input data |
| 409 | Conflict | Phone number already in use |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
GET /users/{id}
Description
Retrieve a specific user by ID
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | User ID |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | Insufficient permissions to access this user |
| 404 | Not Found | User not found |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Path Parameters
User ID
PUT /users/{id}
Description
Update a user
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | User ID |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 400 | Bad Request | Invalid input data |
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | Insufficient permissions to update this user |
| 404 | Not Found | User not found |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Path Parameters
User ID
DELETE /users/{id}
Description
Delete a user
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | User ID |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | Insufficient permissions to delete this user |
| 404 | Not Found | User not found |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Path Parameters
User ID
POST /users/{id}/activate
Description
Activate a user account
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | User ID |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | Insufficient permissions to activate this user |
| 404 | Not Found | User not found |
| 409 | Conflict | User is already active |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Path Parameters
User ID
POST /users/{id}/block
Description
Block a user account
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | User ID |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | Insufficient permissions to block this user |
| 404 | Not Found | User not found |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Path Parameters
User ID
POST /users/{id}/suspend
Description
Suspend a user account temporarily
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | User ID |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | Insufficient permissions to suspend this user |
| 404 | Not Found | User not found |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Path Parameters
User ID
GET /users/{id}/transactions
Description
Get user transaction history
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | User ID |
| page | number | Optional | Page number for pagination |
| limit | number | Optional | Number of items per page |
| type | string | Optional | Filter by transaction type |
| start_date | string | Optional | Start date for filtering (ISO format) |
| end_date | string | Optional | End date for filtering (ISO format) |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | Insufficient permissions to access this user's transactions |
| 404 | Not Found | User not found |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Path Parameters
User ID
Query Parameters
Page number for pagination
Number of items per page
Filter by transaction type
Start date for filtering (ISO format)
End date for filtering (ISO format)
GET /users/{id}/balance
Description
Get user current balance
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | User ID |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | Insufficient permissions to access this user's balance |
| 404 | Not Found | User not found |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Path Parameters
User ID
POST /users/{id}/reset-password
Description
Reset user password
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | User ID |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 400 | Bad Request | Invalid reset token or weak password |
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | Insufficient permissions to reset this user's password |
| 404 | Not Found | User not found |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Path Parameters
User ID
GET /users/search
Description
Search users by various criteria
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| query | string | Required | Search query (phone, name, email) |
| page | number | Optional | Page number for pagination |
| limit | number | Optional | Number of items per page |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 400 | Bad Request | Invalid search query |
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Query Parameters
Search query (phone, name, email)
Page number for pagination
Number of items per page