Users Management
Get Users
For retriving user objects. This is divided into two:
Get all users
GET api/users
Description:
Returns a list of users for the authenticated company.
Request Headers:
Authorization
Bearer Token
The token used for authenticating the request.
Request Body:
This is optional and only needed for a B2B2B Scenario.
company_id
Integer (Optional)
The ID of the target company if fetching users of another company in a B2B2B scenario.
Response:
{
"Resources": [
{
"id": 42,
"manager_id": 100,
"employee_id": "543356463",
"first_name": "Gin",
"last_name": "Agbo",
"email": "[email protected]",
"email_verified_at": null,
"created_at": "2023-11-23T04:56:32.000000Z",
"updated_at": "2024-04-08T16:23:24.000000Z",
"personal_email": "[email protected]",
"unique_id": "eaa505",
"user_types": "Executive",
"address": "No 5, Shekpe RD",
"phone": "+23431478956789",
"document_paths": null,
"onboarding_token": null,
"token_expires_at": "2023-11-24 04:56:32",
"onboarding_completed": 1,
"domain_id": 11,
"level": "L5",
"title": "Senior Manager",
"base_salary": "500.00",
"department": "IT",
"allowances": "500",
"office_location": "US",
"payment_frequency": "Bi-Weekly",
"start_date": "2023-09-07",
"manager": "Johny Walker",
"is_active": true,
"company_id": 1,
"deleted_at": null
},
{
"id": 100,
"manager_id": 42,
"employee_id": "33982927",
"first_name": "Johny",
"last_name": "Walker",
"email": "[email protected]",
"email_verified_at": null,
"created_at": "2024-04-07T21:33:54.000000Z",
"updated_at": "2024-07-05T22:08:49.000000Z",
"personal_email": "[email protected]",
"unique_id": "rjw948",
"user_types": "Regular",
"address": "1200 units Lokoja",
"phone": "0808654304",
"document_paths": null,
"onboarding_token": null,
"token_expires_at": "2024-04-08 21:33:54",
"onboarding_completed": 1,
"domain_id": 9,
"level": "L3",
"title": "Lead",
"base_salary": "2000.00",
"department": "Operations",
"allowances": "100",
"office_location": "NG",
"payment_frequency": "Bi-Weekly",
"start_date": "2023-08-01",
"manager": "Ogogoro Sipper",
"is_active": true,
"company_id": 1,
"deleted_at": null
}
],
"totalResults": 6
}{
"error": "Unauthorized"
}Get a specific user:
GET api/users/{id}
Description:
Returns a list of users for the authenticated company.
Request Headers:
Authorization
Bearer Token
The token used for authenticating the request.
Request Parameters:
id
Integer
The ID of the user to deactivate.
Request Body:
This is optional and only needed for a B2B2B Scenario.
company_id
Integer (Optional)
The ID of the target company if user is for another company in a B2B2B scenario.
Response:
{
"id": 42,
"manager_id": 100,
"employee_id": "543356463",
"first_name": "Gin",
"last_name": "Agbo",
"email": "[email protected]",
"email_verified_at": null,
"created_at": "2023-11-23T04:56:32.000000Z",
"updated_at": "2024-04-08T16:23:24.000000Z",
"personal_email": "[email protected]",
"unique_id": "eaa505",
"user_types": "Executive",
"address": "No 5, Shekpe RD",
"phone": "+23431478956789",
"document_paths": null,
"onboarding_token": null,
"token_expires_at": "2023-11-24 04:56:32",
"onboarding_completed": 1,
"domain_id": 11,
"level": "L5",
"title": "Senior Manager",
"base_salary": "500.00",
"department": "IT",
"allowances": "500",
"office_location": "US",
"payment_frequency": "Bi-Weekly",
"start_date": "2023-09-07",
"manager": "Johny Walker",
"is_active": true,
"company_id": 1,
"deleted_at": null
},Unauthorized: If the user is not authenticated:
{
"error": "Unauthorized or invalid company ID."
}Forbidden: If the user does not have permission to update the target company.
{
"error": "Unauthorized or invalid company ID."
}Not Found: If the user ID provided does not exist.
{
"error": "User not found."
}Create a New User
POST api/users
Description:
This endpoint allows for the creation of a new user in a specific company. It supports B2B2B scenarios where a third-party company (e.g., Flair HR) can create users for their customers' companies.
Request Headers
Authorization
Bearer token for API access
string
Yes
Content-Type
Must be set to application/json
string
Yes
Request Parameters
Body Parameters
company_id
ID of the company for which the user is being created. Optional if the user is for the initiating company.
integer
No
-
123
first_name
First name of the user
string
Yes
-
Samson
last_name
Last name of the user
string
Yes
-
Olu
domain_name
Domain name associated with the user's email
string
Yes
-
vincentco.com
user_types
User type within the company
string
Yes
-
Employee
title
Job title of the user
string
No
-
Software Engineer
base_salary
Base salary of the user
numeric
No
-
85000
department
Department where the user works
string
No
-
IT
allowances
Allowances for the user
numeric
No
-
5000
office_location
Office location of the user
string
No
-
Lagos
start_date
Start date of the user in YYYY-MM-DD format
date
Yes
-
2024-09-01
manager_email
Email of the user's manager. If provided, the manager must exist in the specified company.
string
No
-
Name of the user's bank. Required if account_number is provided.
string
No
-
Guaranty Trust Bank
account_number
User's bank account number. Required if bank_name is provided.
string
No
-
0167865207
roles
Roles assigned to the user. Defaults to user if not provided.
array
No
["user"]
["admin", "user"]
is_active
Whether the user should be immediately activated (true) or not (false).
boolean
No
false
true
notify
Flag to send notification
Boolean
Optional
false
true
Response
{
"message": "User created successfully",
"user": {
"id": 45,
"first_name": "Samson",
"last_name": "Olu",
"email": "[email protected]",
"personal_email": "[email protected]",
"company_id": 123,
"title": "Software Engineer",
"department": "IT",
"manager_id": 10,
"employee_id": "EMP456",
"unique_id": "UID789",
"is_active": true,
"onboarding_completed": true,
"created_at": "2024-09-01T12:00:00Z",
"updated_at": "2024-09-01T12:00:00Z"
}
}Unauthorized or Invalid:
{
"error": "Unauthorized or invalid company ID."
}Domain Name Does Not Exist:
{
"error": "Domain name does not exist for the specified company."
}User Type Does Not Exist:
{
"error": "The user type entered does not exist for the specified company."
}Manager Email Does Not Exist:
{
"error": "Manager with specified email does not exist."
}User Already Exists:
{
"error": "User already exists and is active."
}Failed to Create User:
{
"error": "Failed to create user."
}Use Cases
Example 1: Creating a New User
Request:
POST /api/usersBody:
{
"company_id": 123,
"first_name": "Samson",
"last_name": "Olu",
"personal_email": "[email protected]",
"domain_name": "vincentco.com",
"user_types": "Employee",
"title": "Software Engineer",
"base_salary": 85000,
"department": "IT",
"allowances": 5000,
"office_location": "Lagos",
"start_date": "2024-09-01",
"manager_email": "[email protected]",
"bank_name": "Guaranty Trust Bank",
"account_number": "0178965457",
"roles": ["user"],
"is_active": true
}Response:
{
"message": "User created successfully",
"user": {
"id": 45,
"first_name": "Samson",
"last_name": "Olu",
"email": "[email protected]",
"personal_email": "[email protected]",
"company_id": 123,
"title": "Software Engineer",
"department": "IT",
"manager_id": 10,
"employee_id": "EMP456",
"unique_id": "UID789",
"is_active": true,
"onboarding_completed": true,
"created_at": "2024-09-01T12:00:00Z",
"updated_at": "2024-09-01T12:00:00Z"
}
}Example 2: Creating a New User Without Activation
Request:
POST /api/usersBody:
{
"company_id": 123,
"first_name": "Samson",
"last_name": "Olu",
"personal_email": "[email protected]",
"domain_name": "vincentco.com",
"user_types": "Employee",
"title": "Software Engineer",
"base_salary": 85000,
"department": "IT",
"allowances": 5000,
"office_location": "Lagos",
"start_date": "2024-09-01",
"manager_email": "[email protected]",
"bank_name": "Guaranty Trust Bank",
"account_number": "01436783207",
"roles": ["user"]
}Response:
{
"message": "User created successfully",
"user": {
"id": 45,
"first_name": "Samson",
"last_name": "Olu",
"email": "[email protected]",
"personal_email": "[email protected]",
"company_id": 123,
"title": "Software Engineer",
"department": "IT",
"manager_id": 10,
"employee_id": "EMP456",
"unique_id": "UID789",
"is_active": false,
"onboarding_completed": false,
"created_at": "2024-09-01T12:00:00Z",
"updated_at": "2024-09-01T12:00:00Z"
}
}Example 3: Creating a New User for the Initiating Company (Non-B2B2B Scenario)
Request:
POST /api/usersBody:
{
"first_name": "Jane",
"last_name": "Doe",
"personal_email": "[email protected]",
"domain_name": "initiatingcompany.com",
"user_types": "Employee",
"title": "Marketing Manager",
"base_salary": 70000,
"department": "Marketing",
"allowances": 3000,
"office_location": "New York",
"start_date": "2024-10-01",
"manager_email": "[email protected]",
"bank_name": "First Bank",
"account_number": "1234567890",
"roles": ["user"],
"is_active": false
}Response:
{
"message": "User created successfully",
"user": {
"id": 46,
"first_name": "Jane",
"last_name": "Doe",
"email": "[email protected]",
"personal_email": "[email protected]",
"company_id": 101, // ID of the initiating company
"title": "Marketing Manager",
"department": "Marketing",
"manager_id": 15,
"employee_id": "EMP123",
"unique_id": "UID456",
"is_active": false,
"onboarding_completed": false,
"created_at": "2024-10-01T12:00:00Z",
"updated_at": "2024-10-01T12:00:00Z"
}
}Scenario Details
Non-B2B2B Scenario: In this example, the user is being created for the company that is initiating the API call, and no
company_idis provided in the request. This means the new user will be associated with the initiating company.No Immediate Activation: The user is not immediately activated (
is_activeis set tofalse). They will need to complete onboarding through the provided token.Onboarding: Since the user is not activated, an onboarding token is generated, and an invitation email will be sent to the user's personal email to complete the onboarding process.
Domain and User Type Checks: The domain name and user type are validated against the initiating company's existing records.
This example showcases a straightforward use case where a company uses the API to create a user within its own system, without interacting with another company's data (non-B2B2B scenario).
Update a User's Profile
PUT api/users/{id}
Description
This API endpoint is used to update an existing user's details within a company. The request can optionally specify a target company ID for B2B2B scenarios.
Request Headers
Authorization
Bearer Token
The token used for authenticating the request.
Request Parameters
id
Integer
The ID of the user to be updated.
Request Body
company_id
Integer (Optional)
The ID of the target company if updating for another company in a B2B2B scenario.
first_name
String (Optional)
The user's first name.
last_name
String (Optional)
The user's last name.
domain_name
String (Optional)
The domain name associated with the user's email address.
user_types
String (Optional)
The user type, e.g., 'Admin', 'Employee'.
title
String (Optional)
The user's job title.
base_salary
Numeric (Optional)
The user's base salary.
department
String (Optional)
The department where the user works.
allowances
Numeric (Optional)
The user's allowances.
personal_email
String (Optional)
The user's personal email address.
office_location
String (Optional)
The user's office location.
start_date
Date (Optional)
The user's start date.
manager_email
String (Optional)
The email address of the user's manager.
documents
Array of Files (Optional)
Array of documents to upload for the user.
password
String (Optional)
The user's password. Must be at least 12 characters long, with uppercase and special characters.
password_confirmation
tring (Optional)
Match the password
bank_name
String (Optional)
The user's bank name.
account_number
String (Optional)
The user's bank account number.
notify
Boolean: true (Optional)
Flag to send notification
Example Request Body
{
"company_id": 123,
"first_name": "John",
"last_name": "Doe",
"domain_name": "example.com",
"user_types": "Admin",
"title": "Project Manager",
"base_salary": 75000,
"department": "Engineering",
"allowances": 5000,
"personal_email": "[email protected]",
"office_location": "New York Office",
"start_date": "2024-01-15",
"manager_email": "[email protected]",
"documents": ["document1.pdf", "document2.pdf"],
"password": "securepassword123",
"bank_name": "Example Bank",
"account_number": "1234567890"
}Response
{
"message": "User updated successfully via API",
"emailUpdate": "Email updated",
"uniqueIdUpdate": "Unique ID updated",
"user": {
"id": 1,
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"unique_id": "JDoeAdmin",
// additional user details...
}
}Unauthorized: If the user is not authenticated:
{
"error": "Unauthorized or invalid company ID."
}Forbidden: If the user does not have permission to update the target company.
{
"error": "Unauthorized or invalid company ID."
}Not Found: If the user ID provided does not exist.
{
"error": "User not found."
}Un-processable Entity: If validation of the request body fails
{
"error": {
"first_name": ["The first name field is required."],
// other validation errors...
}
}Internal Server Error: If there is a server-side error during the update.
{
"error": "Failed to update user."
}Deactivate a User
PATCH api/users/{id}/deactivate
Description:
This API endpoint deactivates a user within a company by updating the is_active status.
Request Headers:
Authorization
Bearer Token
The token used for authenticating the request.
Request Parameters:
id
Integer
The ID of the user to deactivate.
Request Body:
This is optional and only needed for a B2B2B Scenario.
company_id
Integer (Optional)
The ID of the target company if deactivating user of another company in a B2B2B scenario.
Response:
{
"message": "User deactivated successfully."
}Not Found: If the user with the provided ID does not exist.
{
"error": "User not found."
}Forbidden: If there’s an error during the deactivation process.
{
"error": "Failed to deactivate user."
}Bad Request: If the user ID is not provided.
{
"error": "User ID is required."
}Activate a User
PATCH api/users/{id}/activate
Description:
This API endpoint activates a user within a company by updating the is_active status and setting the onboarding as completed.
Request Headers:
Authorization
Bearer Token
The token used for authenticating the request.
Request Parameters:
id
Integer
The ID of the user to activate.
Request Body:
This is optional and only needed for a B2B2B Scenario.
company_id
Integer (Optional)
The ID of the target company if activating user of another company in a B2B2B scenario.
notify
Boolean (Optional:true)
Flag to send notification
Response:
{
"message": "User activated successfully."
}Not Found: If the user with the provided ID does not exist.
{
"error": "User not found."
}Forbidden: If there’s an error during the activation process.
{
"error": "Failed to activate user."
}Bad Request: If the user ID is not provided.
{
"error": "User ID is required."
}Delete a User
DELETE api/users/{id}
Description:
This API endpoint deletes a user within a company. It deactivates the user, removes associated roles, and deletes related onboarding documents.
Request Headers:
Authorization
Bearer Token
The token used for authenticating the request.
Request Parameters:
This is optional and only needed for a B2B2B Scenario.
id
Integer
The ID of the user to delete.
Request Body:
company_id
Integer (Optional)
The ID of the target company if deleting user of another company in a B2B2B scenario.
Response:
{
"message": "User deleted successfully."
}Not Found: If the user with the provided ID does not exist.
{
"error": "User not found."
}Forbidden: If there’s an error during the deletion process.
{
"error": "Failed to delete user."
}Bad Request: If the user ID is not provided.
{
"error": "User ID is required."
}Bulk Create Users
POST api/users/bulk-create
Description
Allows bulk creation of users for a specific company by uploading a CSV file.
Request Headers
Authorization
Bearer {token}
Content-Type
multipart/form-data
Parameters
Query Parameters
company_id
int
No
ID of the target company. Defaults to the authenticated company.
Form Data
users_csv
file
Yes
CSV file containing user data.
Responses
{
"status": "success",
"message": "Bulk user creation completed.",
"summary": "3 accounts created, 1 accounts not created.",
"successes": [ ... ],
"failures": [ ... ]
}{
"errors": {
"users_csv": ["The users_csv file is required."]
}
}{
"error": "Target company not found."
}Bulk Update Users
POST api/users/bulk-update
Description
Allows bulk updates to existing users in a company by uploading a CSV file.
Headers
Authorization
Bearer {token}
Content-Type
multipart/form-data
Parameters
Query Parameters
company_id
int
No
ID of the target company. Defaults to the authenticated company.
Form Data
users_csv
file
Yes
CSV file containing user update data.
Responses
{
"status": "success",
"message": "Bulk user update completed.",
"summary": "2 accounts updated.",
"successes": [ ... ],
"failures": [ ... ]
}{
"errors": {
"users_csv": ["The users_csv file is required."]
}
}Suspend User
POST api/users/{id}/suspend
Description
Suspend a user for a specified duration or indefinitely.
Headers
Authorization
Bearer {token}
Parameters
Query Parameters
company_id
int
No
ID of the target company. Defaults to the authenticated company.
Request Body
suspension_duration_type
string
Yes
Type of suspension (minutes, hours, date, indefinite).
suspension_duration_value
integer
No
Value for minutes or hours duration type.
suspension_end_at
string
No
Date for date duration type (YYYY-MM-DD HH:mm:ss).
clear_roles
boolean
No
Whether to remove all roles for the user during suspension.
suspension_reason
string
No
Reason for the suspension.
Responses
{
"message": "User suspended successfully.",
"user": { ... }
}{
"error": "suspension_duration_value is required for minutes type."
}Unsuspend User
POST api/users/{id}/unsuspend
Description
Unsuspend a user either immediately or at a specified future time.
Headers
Authorization
Bearer {token}
Parameters
Query Parameters
company_id
int
No
ID of the target company. Defaults to the authenticated company.
Request Body
unsuspend_option
string
Yes
Option to unsuspend (immediately, future).
new_unsuspension_time
string
No
Future unsuspension time (YYYY-MM-DD HH:mm:ss).
Responses
{
"message": "User unsuspended successfully.",
"user": { ... }
}{
"error": "Invalid action."
}Download Templates
Download Import Template
GET api/users/import-template
Description
Download the CSV template for user import.
Responses:
"Please fill out the following template. Ensure the date format for the start_date is YYYY-MM-DD.","Account numbers should retain leading zeros, so the ""account_number"" column should be formatted as text in your spreadsheet software.","","","","","","","","","","","",""
"first_name","last_name","personal_email","domain","user_types","title","base_salary","department","allowances","office_location","start_date (YYYY-MM-DD)","manager","bank_name","account_number"Download Update Template
GET api/users/update-template
Description
Download the CSV template for user update.
Responses
"Please fill out the following template. Ensure the date format for the start_date is YYYY-MM-DD.","Account numbers should retain leading zeros, so the ""account_number"" column should be formatted as text in your spreadsheet software.","","","","","","","","","","","","",""
"email","first_name","last_name","personal_email","domain","user_types","title","base_salary","department","allowances","office_location","start_date (YYYY-MM-DD)","manager","bank_name","account_number"
Last updated