Add Employee

Add a new employee record with contact details, address, and employment information.

POST

/api/v1/employee/add

Description

Creates a new employee record in your company. Once added, the employee is available across your Unduit account for asset assignment, orders, and shipping.

Request

Headers

Header	Value	Required
Authorization	Bearer <access_token>	Yes
Content-Type	application/json	Yes

Basic Information

Fields

Parameter	Type	Required	Description
firstname	string	Yes	Employee's first name. Letters and spaces only.
lastname	string	Yes	Employee's last name. Letters and spaces only.
work_email	string	Yes	Employee's work email address.
work_phone	string	Yes	Work phone number, digits only. Spaces and dashes are stripped automatically.
work_phone_country	string	Yes	Work phone country as an ISO 3166-1 alpha-2 code (e.g. US, GB).
personal_email	string	No	Employee's personal email address.
personal_phone	string	No	Employee's personal phone number, digits only.
personal_contact_country	string	No	Personal phone country as an ISO 3166-1 alpha-2 code. Also accepted as personal_phone_country.

Address Information

Fields

Parameter	Type	Required	Description
address_1	string	Yes	Street address line 1.
address_2	string	No	Street address line 2.
city	string	Yes	City.
state	string	No	State or province. Required for all countries except GB.
zip	string	Yes	Postal or zip code.
country	string	Yes	Country as an ISO 3166-1 alpha-2 code (e.g. US, DE).
location_type	string	Yes	How the employee is based. Must be one of: Warehouse, Corporate Office, Retail Store, Remote Employee.
location_name	string	No	Display name for the employee's location. Defaults to "{firstname} {lastname}" when not provided.

Employment Information

These fields are optional and sent at the top level of the request body. They are returned nested under employment_information in the response.

Fields

Parameter	Type	Required	Description
employee_id	string	No	Employee's ID on their location record.
department	string	No	Department name. Must match an existing department in your company. Returns 422 if not found.
employment_status	string	No	Employment status (e.g. Active, Terminated).
employment_type	string	No	Employment type (e.g. Full Time, Part Time, Contractor).
manager	string	No	Direct manager's name or identifier.
employment_start_date	string	No	Start date in YYYY-MM-DD format (e.g. 2024-01-15).
termination_date	string	No	Termination date in YYYY-MM-DD format. Include when employment_status is Terminated.

Example Request Body

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

Response

Top-level Fields

Field	Type	Description
success	boolean	Whether the request was successful.
message	string	Human-readable confirmation (e.g. "Employee added successfully").
address	object	The newly created employee address record. See fields below.

Address Fields

Field	Type	Description
address.id	string	Use the full value in detail and update routes.
address.firstname	string	Employee's first name.
address.lastname	string	Employee's last name.
address.location_name	string	Display name for the employee's location.
address.work_email	string	Employee's work email address.
address.work_phone	string	Work phone number, digits only.
address.work_phone_country	string	Work phone country as an ISO 3166-1 alpha-2 code.
address.address_1	string	Address line 1.
address.address_2	string	Address line 2. Null if not provided.
address.city	string	City.
address.state	string	State or province.
address.zip	string	Postal or zip code.
address.country	string	Country as an ISO 3166-1 alpha-2 code.
address.location_type	string	How the employee is based (e.g. Remote Employee, Corporate Office).
address.department	string	Department name. Null if not provided.
address.configure_cost_center_id	number	ID of the assigned cost center. Null if not configured.
address.employee_id	string	Employee ID on the location record. Null if not provided.
address.employment_information	object	Employment and personal contact fields submitted with the request. Null if no employment fields were provided. Only fields with values are included. See fields below.

employment_information Fields

Field	Type	Description
address.employment_information.employment_status	string	Employment status (e.g. Active, Terminated).
address.employment_information.employment_type	string	Employment type (e.g. Full Time, Part Time, Contractor).
address.employment_information.employment_start_date	string	Start date in YYYY-MM-DD format.
address.employment_information.termination_date	string	Termination date in YYYY-MM-DD format. Only present when employment_status is Terminated.
address.employment_information.manager	string	Direct manager's name or identifier.
address.employment_information.personal_email	string	Employee's personal email address.
address.employment_information.personal_phone	string	Employee's personal phone number, digits only.
address.employment_information.personal_contact_country	string	Personal phone country as an ISO 3166-1 alpha-2 code.

Notes

Returns HTTP 201 on success.
address.id is returned as an opaque string (`{7-digit-prefix}-{numericId}`). Pass the full value to GET /api/v1/employees/{id} and update routes.
email and work_email are interchangeable — both refer to the work email address. Use work_email in new integrations.
personal_contact_country and personal_phone_country are interchangeable. Use personal_contact_country in new integrations.
state is required for all countries except GB.
location_name defaults to "{firstname} {lastname}" when not provided.
location_type must be one of: Warehouse, Corporate Office, Retail Store, Remote Employee.
department must match an existing department name for your company. Returns 422 if not found.
Employment fields are sent at the top level of the request body but returned nested under employment_information in the response.
employment_information only includes fields that were provided — empty or null fields are omitted.
contact_info and contact_country in the response are legacy aliases for work_phone and work_phone_country retained for backwards compatibility.

Related Endpoints

Update Employee

Update an existing employee

Employee Detail

Retrieve employee by ID

Bulk Import Employees

Import up to 500 employees

Did this page help you?

Request

curl -X POST https://uat.unduit.com/api-exposed/api/v1/employee/add \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'

Success Response

{
  "success": true,
  "message": "Employee added successfully",
  "address": {
    "id": "6065387-8027",
    "firstname": "Jane",
    "lastname": "Doe",
    "location_name": "Remote - San Francisco",
    "work_email": "jane.doe@company.com",
    "work_phone": "4155551234",
    "work_phone_country": "US",
    "contact_info": "4155551234",
    "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",
    "department": "IT",
    "configure_cost_center_id": null,
    "employee_id": "EMP-501",
    "employment_information": {
      "employment_status": "Active",
      "employment_type": "Full Time",
      "employment_start_date": "2024-01-15",
      "manager": "John Shah",
      "personal_email": "jane.doe@gmail.com",
      "personal_phone": "4155559999",
      "personal_contact_country": "US"
    }
  }
}

Error Responses

422 Validation Error

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    { "type": "field", "msg": "Work phone country is required", "path": "work_phone_country", "location": "body" },
    { "type": "field", "msg": "Address line 1 is required", "path": "address_1", "location": "body" },
    { "type": "field", "msg": "City is required", "path": "city", "location": "body" }
  ]
}

422 Department Not Found

{
  "success": false,
  "message": "Department 'Finance' not found",
  "errors": {
    "department": "Department 'Finance' does not exist for your company."
  }
}

401 Unauthorized

{
  "success": false,
  "message": "Access denied: No token provided."
}