Create Employee Record

Programmatically create employee records, including contact information and shipping addresses.

Any record added via this API is automatically reflected in the Locations app, Manage app → Users view, and the Shipping Address selector in Unduit's order workflows. This enables seamless integration between your internal HR/location systems and Unduit's IT Asset Management platform.

POST

/api/v1/employee/add

Description

Use the POST Employee Record endpoint to programmatically create employee records with contact information and shipping addresses. Employee records created through this API power the dynamic address selectors across Unduit apps (e.g. Shop, Buyback, Device Hub, Repair).

Request

Headers

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

Request Body (JSON)

Field	Type	Required	Description	Validation Rules
firstname	String	Yes	First name of the user	Must not be empty, letters and spaces only
lastname	String	Yes	Last name of the user	Must not be empty, letters and spaces only
location_name	String	Yes	Name of the associated location	Must not be empty
location_type	String	Yes	Type of location	Must be: Warehouse, Corporate Office, Retail Store, or Remote Employee
contact_info	Number	Yes	Phone number for contact	Must contain only numbers
email	String	Yes	Email address of the contact	Must be valid email format and not empty
address_1	String	Yes	Address line 1	Must not be empty
address_2	String	No	Address line 2 (suite, apt, etc.)	Optional
city	String	Yes	City name	Must not be empty
state	String	Yes	State or province	Must not be empty
zip	String	Yes	Zip or postal code	Must not be empty
country	String	Yes	Country code (ISO 3166-1 alpha-2)	Valid ISO 3166-1 alpha-2 code (e.g., US, GB)
contact_country	String	Yes	Country code of contact's location	Must not be empty

Response

Response Fields

Field	Type	Description
message	string	Status message confirming successful creation
address	object	The created employee record with all fields
address.id	number	Unique identifier for the employee record
address.firstname	string	Employee's first name
address.lastname	string	Employee's last name
address.username	string	Full name (concatenation of first and last name)
address.email	string	Employee's email address
address.location_name	string	Name of the associated location
address.location_type	string	Type of location (Warehouse, Corporate Office, etc.)
address.contact_info	string	Phone number
address.company_id	number	Company identifier
address.created_at	string	Timestamp when record was created
address.updated_at	string	Timestamp of last update

Error Responses

Common error responses you may encounter when using this endpoint.

Notes

This endpoint requires valid authentication. Include your access token in the Authorization header.
All required fields must be provided in the request body. Missing or invalid fields will result in an error.
The location_type field must be one of the following: Warehouse, Corporate Office, Retail Store, or Remote Employee.
Country codes must follow the ISO 3166-1 alpha-2 standard (e.g., US for United States, GB for United Kingdom).
Employee records created via this API are immediately available across all Unduit apps.

Related Endpoints

Employee Directory

Retrieve a paginated list of all employees

Update Employee Record

Update an existing employee record

Did this page help you?

Request

curl -X POST https://dev-api.unduit.com/api/v1/employee/add \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "firstname": "John",
    "lastname": "Doe",
    "location_name": "San Francisco Remote Hub",
    "contact_info": "3242342",
    "email": "john.doe@example.com",
    "address_1": "123 Market Street",
    "address_2": "Suite 400",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94103",
    "country": "US",
    "contact_country": "US",
    "location_type": "Warehouse"
  }'

Success Response (201)

{
  "message": "Address added successfully",
  "address": {
    "firstname": "John",
    "lastname": "Doe",
    "username": "John Doe",
    "location_name": "San Francisco Remote Hub",
    "email": "john.doe@example.com",
    "contact_info": "3242342",
    "contact_country": "US",
    "address_1": "123 Market Street",
    "address_2": "Suite 400",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "zip": "94103",
    "location_type": "Warehouse",
    "id": 8027,
    "user_id": 0,
    "company_id": 317,
    "is_default": 0,
    "is_deleted": 0,
    "created_at": "2025-05-12 05:56:05",
    "updated_at": "2025-05-12 05:56:05",
    "updatedAt": "2025-05-12T05:56:05.202Z",
    "createdAt": "2025-05-12T05:56:05.202Z"
  }
}

Error Responses

400 Bad Request

{
  "message": "Missing required fields: firstname, lastname"
}

401 Unauthorized

{
  "message": "Missing or invalid authentication token"
}

409 Conflict

{
  "message": "Employee with email john.doe@example.com already exists"
}

422 Unprocessable Entity

{
  "message": "Invalid email format",
  "errors": {
    "email": "Must be a valid email address"
  }
}