Bulk Upload Employees

Upload a CSV file to create multiple employees in bulk

POST /companies/{company_id}/employees/bulk

cURL

curl -X POST https://api.companyflow.com/companies/123e4567-e89b-12d3-a456-426614174000/employees/bulk \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@employees.csv"

201 Success

{
  "success": true,
  "message": "Employees created successfully. Temporary passwords have been generated.",
  "data": {
    "success_count": 25,
    "failure_count": 0,
    "validation_errors": [],
    "created_employees": [
      "emp-uuid-1",
      "emp-uuid-2",
      "emp-uuid-3"
    ]
  }
}

Authentication

This endpoint requires Bearer token authentication with one of the following roles:

• super_admin
• hr_manager

Path Parameters

company_id · string · required

The unique identifier of the company (UUID format)

Request Body

This endpoint accepts multipart/form-data.

file · file · required

CSV file containing employee data. File must have a .csv extension or text/csv content type.

CSV Format

The CSV file must include the following headers (column order is flexible):

Required Columns

• email - Employee email address
• first_name - Employee first name
• last_name - Employee last name
• phone - Employee phone number
• employee_code - Internal employee code (e.g., EMP001)
• department_id - Department UUID
• designation_id - Designation UUID
• level_id - Level UUID
• role_id - Role UUID
• status - Employee status (active, inactive, on_leave, terminated, probation)
• employment_type - Employment type (full_time, part_time, contract, intern)
• hire_date - Hire date (YYYY-MM-DD format)

Optional Columns

• password - Employee password (if empty, temporary password will be generated)
• date_of_birth - Date of birth (YYYY-MM-DD format)
• manager_id - Manager UUID
• gender - Employee gender
• address - Employee address
• emergency_contact_name - Emergency contact name
• emergency_contact_phone - Emergency contact phone
• profile_image_url - Profile image URL

Example CSV

email,password,phone,first_name,last_name,date_of_birth,employee_code,department_id,designation_id,level_id,role_id,manager_id,status,employment_type,hire_date,gender,address,emergency_contact_name,emergency_contact_phone,profile_image_url
[e-mail],,[phone],John,Doe,1990-01-15,EMP001,dept-uuid,desig-uuid,level-uuid,role-uuid,manager-uuid,active,full_time,2024-01-01,Male,123 Main St,Jane Doe,[phone],
[e-mail],,[phone],Jane,Smith,1992-05-20,EMP002,dept-uuid,desig-uuid,level-uuid,role-uuid,,active,full_time,2024-01-15,Female,456 Oak Ave,John Smith,[phone],

Response

success · boolean

Indicates if the request was successful

message · string

Status message

data · object

success_count · integer

Number of employees successfully created

failure_count · integer

Number of employees that failed validation

validation_errors · array

Array of validation error objects (only present if failures occurred)

row_number · integer

Row number in CSV where error occurred

record · object

The employee record that failed validation

errors · array

Array of error messages for this record

created_employees · array

Array of created employee UUIDs (only present on success)

cURL

curl -X POST https://api.companyflow.com/companies/123e4567-e89b-12d3-a456-426614174000/employees/bulk \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@employees.csv"

201 Success

{
  "success": true,
  "message": "Employees created successfully. Temporary passwords have been generated.",
  "data": {
    "success_count": 25,
    "failure_count": 0,
    "validation_errors": [],
    "created_employees": [
      "emp-uuid-1",
      "emp-uuid-2",
      "emp-uuid-3"
    ]
  }
}