Unduit

Bulk Import Employees

Import up to 500 employee records in a single request.

POST
/api/v1/employees/bulk-import

Description

Creates employee records from an array. Validates all rows before inserting; if any row fails validation, no records are processed. Skips emails that already exist for the company.

Request

Headers

HeaderValueRequired
AuthorizationBearer <access_token>Yes
Content-Typeapplication/jsonYes

Body Parameters

ParameterTypeRequiredDescription
employeesarrayYesArray of employee objects (max 500). Supports camelCase or PascalCase field aliases.

Each object in employees[]

Same fields as Add Employee. Aliases accepted: FirstName, LastName, LocationName, Email, etc.

Fields

ParameterTypeRequiredDescription
firstnamestringYesEmployee's first name. Letters and spaces only.
lastnamestringYesEmployee's last name. Letters and spaces only.
work_emailstringYesEmployee's work email address.
work_phonestringYesWork phone number, digits only. Spaces and dashes are stripped automatically.
work_phone_countrystringYesWork phone country as an ISO 3166-1 alpha-2 code (e.g. US, GB).
personal_emailstringNoEmployee's personal email address.
personal_phonestringNoEmployee's personal phone number, digits only.
personal_contact_countrystringNoPersonal phone country as an ISO 3166-1 alpha-2 code. Also accepted as personal_phone_country.
address_1stringYesStreet address line 1.
address_2stringNoStreet address line 2.
citystringYesCity.
statestringNoState or province. Required for all countries except GB.
zipstringYesPostal or zip code.
countrystringYesCountry as an ISO 3166-1 alpha-2 code (e.g. US, DE).
location_typestringYesHow the employee is based. Must be one of: Warehouse, Corporate Office, Retail Store, Remote Employee.
location_namestringNoDisplay name for the employee's location. Defaults to "{firstname} {lastname}" when not provided.
employee_idstringNoEmployee ID on the location record.
employee_number_idstringNoHRIS employee number. Returned in employment_information.
departmentstringNoDepartment name. Must match an existing department for your company; returns 422 if not found.
employment_statusstringNoEmployment status (e.g. Active, Terminated).
employment_typestringNoEmployment type (e.g. Full Time, Contractor).
managerstringNoManager name or identifier.
employment_start_datestringNoStart date (ISO 8601, e.g. 2024-01-15).
termination_datestringNoTermination date (ISO 8601).
work_phonestringNoHRIS work phone (digits only). Also returned in employment_information; may differ from top-level work_phone.

Example Request Body

{
  "employees": [
    {
      "firstname": "Jane",
      "lastname": "Doe",
      "work_email": "jane.doe@company.com",
      "work_phone": "4155551234",
      "work_phone_country": "US",
      "personal_email": "jane.doe@gmail.com",
      "personal_phone": "4155559999",
      "personal_contact_country": "US",
      "address_1": "123 Market Street",
      "address_2": "Suite 400",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94103",
      "country": "US",
      "location_type": "Remote Employee",
      "location_name": "Remote - San Francisco",
      "department": "IT",
      "employee_id": "EMP-501",
      "employment_status": "Active",
      "employment_type": "Full Time",
      "manager": "John Shah",
      "employment_start_date": "2024-01-15"
    },
    {
      "firstname": "Jane",
      "lastname": "Smith",
      "work_email": "jane.smith@example.com",
      "work_phone": "4155551234",
      "work_phone_country": "US",
      "personal_email": "jane.doe@gmail.com",
      "personal_phone": "4155559999",
      "personal_contact_country": "US",
      "address_1": "123 Market Street",
      "address_2": "Suite 400",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94103",
      "country": "US",
      "location_type": "Remote Employee",
      "location_name": "Remote - San Francisco",
      "department": "IT",
      "employee_id": "EMP-501",
      "employment_status": "Active",
      "employment_type": "Full Time",
      "manager": "John Shah",
      "employment_start_date": "2024-01-15"
    }
  ]
}

Response

FieldTypeDescription
successbooleanRequest success flag.
messagestringSummary of import result.
creatednumberNumber of employees created.
skippednumberNumber skipped (duplicate email or error).
employeesarrayCreated employee records with employment_information.
employees[].idstringUse the full value in detail and update routes.
employees[].firstnamestringEmployee's first name.
employees[].lastnamestringEmployee's last name.
employees[].location_namestringDisplay name for the employee's location.
employees[].work_emailstringEmployee's work email address.
employees[].work_phonestringWork phone number, digits only.
employees[].work_phone_countrystringWork phone country as an ISO 3166-1 alpha-2 code.
employees[].address_1stringAddress line 1.
employees[].address_2stringAddress line 2. Null if not provided.
employees[].citystringCity.
employees[].statestringState or province.
employees[].zipstringPostal or zip code.
employees[].countrystringCountry as an ISO 3166-1 alpha-2 code.
employees[].location_typestringHow the employee is based (e.g. Remote Employee, Corporate Office).
employees[].departmentstringDepartment name. Null if not provided.
employees[].configure_cost_center_idnumberID of the assigned cost center. Null if not configured.
employees[].employee_idstringEmployee ID on the location record. Null if not provided.
employees[].employment_informationobjectEmployment and personal contact fields submitted with the request. Null if no employment fields were provided. Only fields with values are included. See fields below.
employees[].emailstringLegacy alias for work_email.
employees[].contact_infostringLegacy alias for work_phone.
employees[].contact_countrystringLegacy alias for work_phone_country.
employees[].employment_information.employment_statusstringEmployment status (e.g. Active, Terminated).
employees[].employment_information.employment_typestringEmployment type (e.g. Full Time, Part Time, Contractor).
employees[].employment_information.employment_start_datestringStart date in YYYY-MM-DD format.
employees[].employment_information.termination_datestringTermination date in YYYY-MM-DD format. Only present when employment_status is Terminated.
employees[].employment_information.managerstringDirect manager's name or identifier.
employees[].employment_information.personal_emailstringEmployee's personal email address.
employees[].employment_information.personal_phonestringEmployee's personal phone number, digits only.
employees[].employment_information.personal_contact_countrystringPersonal phone country as an ISO 3166-1 alpha-2 code.

Related Endpoints

Add Employee

Create a single employee

Employees List

List all employees

Did this page help you?