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": "[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": "[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": "[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
}

401

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": "[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": "[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

403

404

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	-	[email protected]
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	-	[email protected]
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": "[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"
    }
}

403

400

500

Use Cases

Example 1: Creating a New User

Request:

POST /api/users

Body:

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

Body:

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

Body:

{
    "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_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": "[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

200

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

401

403

404

422

500

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

403

400

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

403

400

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

403

400

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

404 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

---

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

---

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

---

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"