Update Employee

Update an existing employee record including contact details, address, and employment information.

PUT

/api/v1/employee/update/{id}

Description

Updates an existing employee record. Changes are reflected immediately across your Unduit account including the Users list, Locations, and shipping address selectors. This is a full replace — all required fields must be sent even if unchanged.

This endpoint performs a full replace, not a partial update. All required fields must be included in every request, even if the values have not changed. Omitting a required field will result in a validation error.

Request

Headers

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

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Pass the full value from the API response in path parameters.

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. When provided on update, these values overwrite any previously stored employment data.

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",
  "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 updated successfully").
address	object	The updated employee address record. See fields below.

Address Fields

Field	Type	Description
address.id	string	Opaque employee record ID (`{7-digit-prefix}-{numericId}`).
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.email	string	Legacy alias for work_email.
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.contact_info	string	Legacy alias for work_phone.
address.contact_country	string	Legacy alias for work_phone_country.
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 after the update. 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

This endpoint performs a full replace. All required fields must be sent on every request even if unchanged. Use the Employee Detail endpoint to fetch the current record before updating.
Pass the id from the Employees List or Employee Detail response as the {id} path parameter.
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. When provided, they overwrite any previously stored employment data.
contact_info and contact_country in the response are legacy aliases for work_phone and work_phone_country retained for backwards compatibility.

Related Endpoints

Add Employee

Add a new employee

Employee Detail

Retrieve employee by ID

Did this page help you?

Request

curl -X PUT https://uat.unduit.com/api-exposed/api/v1/employee/update/1204098-10466 \
  -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",
    "employment_status": "Active",
    "employment_type": "Full Time",
    "manager": "John Shah",
    "employment_start_date": "2024-01-15"
  }'

Success Response

{
  "success": true,
  "message": "Employee updated 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

404 Not Found

{
  "success": false,
  "message": "Employee not found"
}

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