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:

Header Name	Value Type	Description
Authorization	Bearer Token	The token used for authenticating the request.

Request Body:

This is optional and only needed for a B2B2B Scenario.

Parameter	Value Type	Description
company_id	Integer (Optional)	The ID of the target company if fetching users of another company in a B2B2B scenario.

Response:

200

{
    "Resources": [
        {
            "id": 42,
            "manager_id": 100,
            "employee_id": "543356463",
            "first_name": "Gin",
            "last_name": "Agbo",
            "email": "[e-mail]",
            "email_verified_at": null,
            "created_at": "2023-11-23T04:56:32.000000Z",
            "updated_at": "2024-04-08T16:23:24.000000Z",
            "personal_email": "[e-mail]",
            "unique_id": "eaa505",
            "user_types": "Executive",
            "address": "No 5, Shekpe RD",
            "phone": "[phone]",
            "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": "[e-mail]",
            "email_verified_at": null,
            "created_at": "2024-04-07T21:33:54.000000Z",
            "updated_at": "2024-07-05T22:08:49.000000Z",
            "personal_email": "[e-mail]",
            "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
}

401

{
    "error": "Unauthorized"
}

Get a specific user:

GET api/users/{id}

Description:

Returns a list of users for the authenticated company.

Request Headers:

Header Name	Value Type	Description
Authorization	Bearer Token	The token used for authenticating the request.

Request Parameters:

Parameter	Value Type	Description
id	Integer	The ID of the user to deactivate.

Request Body:

This is optional and only needed for a B2B2B Scenario.

Parameter	Value Type	Description
company_id	Integer (Optional)	The ID of the target company if user is for another company in a B2B2B scenario.

Response:

200

 {
            "id": 42,
            "manager_id": 100,
            "employee_id": "543356463",
            "first_name": "Gin",
            "last_name": "Agbo",
            "email": "[e-mail]",
            "email_verified_at": null,
            "created_at": "2023-11-23T04:56:32.000000Z",
            "updated_at": "2024-04-08T16:23:24.000000Z",
            "personal_email": "[e-mail]",
            "unique_id": "eaa505",
            "user_types": "Executive",
            "address": "No 5, Shekpe RD",
            "phone": "[phone]",
            "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
        },

401

Unauthorized: If the user is not authenticated:

{
    "error": "Unauthorized or invalid company ID."
}

403

Forbidden: If the user does not have permission to update the target company.

{
    "error": "Unauthorized or invalid company ID."
}

404

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

Header Name	Description	Type	Required
Authorization	Bearer token for API access	string	Yes
Content-Type	Must be set to application/json	string	Yes

Request Parameters

Body Parameters

Parameter	Description	Type	Required	Default	Example
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
personal_email	Personal email of the user	string	Yes	-	[e-mail]
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	-	[e-mail]
bank_name	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

200

{
    "message": "User created successfully",
    "user": {
        "id": 45,
        "first_name": "Samson",
        "last_name": "Olu",
        "email": "[e-mail]",
        "personal_email": "[e-mail]",
        "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"
    }
}

403

Unauthorized or Invalid:

{
    "error": "Unauthorized or invalid company ID."
}

400

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."
}

500

Failed to Create User:

{
    "error": "Failed to create user."
}

Use Cases

Example 1: Creating a New User

Request:

POST /api/users

Body:

{
    "company_id": 123,
    "first_name": "Samson",
    "last_name": "Olu",
    "personal_email": "[e-mail]",
    "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": "[e-mail]",
    "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": "[e-mail]",
        "personal_email": "[e-mail]",
        "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/users

Body:

{
    "company_id": 123,
    "first_name": "Samson",
    "last_name": "Olu",
    "personal_email": "[e-mail]",
    "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": "[e-mail]",
    "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": "[e-mail]",
        "personal_email": "[e-mail]",
        "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/users

Body:

{
    "first_name": "Jane",
    "last_name": "Doe",
    "personal_email": "[e-mail]",
    "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": "[e-mail]",
    "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": "[e-mail]",
        "personal_email": "[e-mail]",
        "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_id is 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_active is set to false). 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

Header Name	Value Type	Description
Authorization	Bearer Token	The token used for authenticating the request.

Request Parameters

Parameter	Value Type	Description
id	Integer	The ID of the user to be updated.

Request Body

Attribute	Value Type	Description
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": "[e-mail]",
    "office_location": "New York Office",
    "start_date": "2024-01-15",
    "manager_email": "[e-mail]",
    "documents": ["document1.pdf", "document2.pdf"],
    "password": "securepassword123",
    "bank_name": "Example Bank",
    "account_number": "1234567890"
}

Response

200

{
    "message": "User updated successfully via API",
    "emailUpdate": "Email updated",
    "uniqueIdUpdate": "Unique ID updated",
    "user": {
        "id": 1,
        "first_name": "John",
        "last_name": "Doe",
        "email": "[e-mail]",
        "unique_id": "JDoeAdmin",
        // additional user details...
    }
}

401

Unauthorized: If the user is not authenticated:

{
    "error": "Unauthorized or invalid company ID."
}

403

Forbidden: If the user does not have permission to update the target company.

{
    "error": "Unauthorized or invalid company ID."
}

404

Not Found: If the user ID provided does not exist.

{
    "error": "User not found."
}

422

Un-processable Entity: If validation of the request body fails

{
    "error": {
        "first_name": ["The first name field is required."],
        // other validation errors...
    }
}

500

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:

Header Name	Value Type	Description
Authorization	Bearer Token	The token used for authenticating the request.

Request Parameters:

Parameter	Value Type	Description
id	Integer	The ID of the user to deactivate.

Request Body:

This is optional and only needed for a B2B2B Scenario.

Parameter	Value Type	Description
company_id	Integer (Optional)	The ID of the target company if deactivating user of another company in a B2B2B scenario.

Response:

200

{
    "message": "User deactivated successfully."
}

404

Not Found: If the user with the provided ID does not exist.

{
    "error": "User not found."
}

403

Forbidden: If there’s an error during the deactivation process.

{
    "error": "Failed to deactivate user."
}

400

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:

Header Name	Value Type	Description
Authorization	Bearer Token	The token used for authenticating the request.

Request Parameters:

Parameter	Value Type	Description
id	Integer	The ID of the user to activate.

Request Body:

This is optional and only needed for a B2B2B Scenario.

Parameter	Value Type	Description
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:

200

{
    "message": "User activated successfully."
}

404

Not Found: If the user with the provided ID does not exist.

{
    "error": "User not found."
}

403

Forbidden: If there’s an error during the activation process.

{
    "error": "Failed to activate user."
}

400

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:

Header Name	Value Type	Description
Authorization	Bearer Token	The token used for authenticating the request.

Request Parameters:

This is optional and only needed for a B2B2B Scenario.

Parameter	Value Type	Description
id	Integer	The ID of the user to delete.

Request Body:

Parameter	Value Type	Description
company_id	Integer (Optional)	The ID of the target company if deleting user of another company in a B2B2B scenario.

Response:

200

{
    "message": "User deleted successfully."
}

404

Not Found: If the user with the provided ID does not exist.

{
    "error": "User not found."
}

403

Forbidden: If there’s an error during the deletion process.

{
    "error": "Failed to delete user."
}

400

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

Key	Value
Authorization	Bearer {token}
Content-Type	multipart/form-data

Parameters

Query Parameters

Name	Type	Required	Description
company_id	int	No	ID of the target company. Defaults to the authenticated company.

Form Data

Name	Type	Required	Description
users_csv	file	Yes	CSV file containing user data.

Responses

200 Success

{
  "status": "success",
  "message": "Bulk user creation completed.",
  "summary": "3 accounts created, 1 accounts not created.",
  "successes": [ ... ],
  "failures": [ ... ]
}

422 Unprocessable Entity

{
  "errors": {
    "users_csv": ["The users_csv file is required."]
  }
}

404 Not Found

{
  "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

Key	Value
Authorization	Bearer {token}
Content-Type	multipart/form-data

Parameters

Query Parameters

Name	Type	Required	Description
company_id	int	No	ID of the target company. Defaults to the authenticated company.

Form Data

Name	Type	Required	Description
users_csv	file	Yes	CSV file containing user update data.

Responses

200 Success

{
  "status": "success",
  "message": "Bulk user update completed.",
  "summary": "2 accounts updated.",
  "successes": [ ... ],
  "failures": [ ... ]
}

422 Unprocessable Entity

{
  "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

Key	Value
Authorization	Bearer {token}

Parameters

Query Parameters

Name	Type	Required	Description
company_id	int	No	ID of the target company. Defaults to the authenticated company.

Request Body

Name	Type	Required	Description
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

200 OK

{
  "message": "User suspended successfully.",
  "user": { ... }
}

422 Unprocessable Entity

{
  "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

Key	Value
Authorization	Bearer {token}

Parameters

Query Parameters

Name	Type	Required	Description
company_id	int	No	ID of the target company. Defaults to the authenticated company.

Request Body

Name	Type	Required	Description
unsuspend_option	string	Yes	Option to unsuspend (immediately, future).
new_unsuspension_time	string	No	Future unsuspension time (YYYY-MM-DD HH:mm:ss).

Responses

200 OK

{
  "message": "User unsuspended successfully.",
  "user": { ... }
}

400 Bad Request

{
  "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"