API Reference

Query employee directory data from your app. All endpoints below require a valid API key with the read scope unless otherwise noted.

Authentication#

Include your API key in the x-api-key request header on every call.

GET /api/v1/employees HTTP/1.1
Host: <your-eds-host>
x-api-key: YOUR_API_KEY

Endpoints#

List employees with pagination and search

Get a single employee by ID

Verify an employee by email

Export employees as CSV

Employee Object#

All fields are present in every response. Nullable fields are marked with | null.

Name	Type	Required	Description
`id`	UUID	Yes	Unique identifier for the employee.
`first_name`	string	Yes	Employee’s legal first name.
`last_name`	string	Yes	Employee’s legal last name.
`middle_name`	string \| null	Yes	Employee’s middle name.
`preferred_name`	string \| null	Yes	Name the employee prefers to go by.
`complete_name`	string	Yes	Full display name (computed from first, preferred, and last name).
`department_id`	UUID	Yes	ID of the department the employee belongs to.
`job_title`	string	Yes	Employee’s job title.
`birthday`	string \| null	Yes	ISO 8601 date string (YYYY-MM-DD).
`start_date`	string \| null	Yes	ISO 8601 date the employee started.
`name_pronunciation`	string \| null	Yes	Phonetic guide for pronouncing the employee’s name.
`phone_number`	string \| null	Yes	Employee’s phone number.
`email`	string \| null	Yes	Employee’s personal email address.
`company_email`	string	Yes	Employee’s company-issued email address.
`timezone`	string \| null	Yes	IANA timezone identifier (e.g. America/New_York).
`country`	string \| null	Yes	Country of residence.
`address_1`	string \| null	Yes	Primary street address line.
`address_2`	string \| null	Yes	Secondary address line (apt, suite, etc.).
`city`	string \| null	Yes	City of residence.
`state`	string \| null	Yes	State or province of residence.
`zip_postal_code`	string \| null	Yes	ZIP or postal code.
`profile_photo_url`	string \| null	Yes	URL to the employee's profile photo.
`is_active`	boolean	Yes	Whether the employee’s account is currently active.
`roles`	string[]	Yes	Array of roles the employee has within EDS (e.g. ["employee"], ["admin"], ["employee", "developer"]).
`time_employed`	string \| null	Yes	Human-readable time since start_date (e.g. “2 years, 3 months”). Only present in OAuth responses.