All employee endpoints are under /organizations/{orgId}/employees and require an access token.

status is one of invited (created, not yet activated), active, or terminated.

GET /organizations/{orgId}/employees

Optional filters: status, email, group (group name), updatedSince (ISO timestamp). Without a status filter the list returns every employee, terminated ones included; pass status=active or status=invited (or both calls) to exclude them.

GET /organizations/{orgId}/employees/{employeeRef}

employeeRef is the AirMason id or ext:<employeeId>.

POST /organizations/{orgId}/employees

employeeId, email, firstName and lastName are required. employeeId and email must be unique among the organization's non-terminated employees (409 conflict otherwise). Groups named in groups are created if they don't exist.

Posting the employeeId of a terminated employee does not return 409: it rehires that employee. The existing row keeps its AirMason id, its fields are overwritten with the request, and its status goes back to invited.

Set sendWelcomeEmail: false if you deliver the activation link yourself via the employee.created webhook. The link is single-use and valid for 7 days; treat activationLinkExpiresAt in the event payload as the authoritative expiry.

PATCH /organizations/{orgId}/employees/{employeeRef}

Any field from the create request except employeeId. Passing null or an empty string clears an optional field.

Passing groups replaces the employee's full group membership; omit it to leave groups unchanged.

A PATCH against a terminated employee returns 409 conflict (Employee is terminated); reactivate first.

POST /organizations/{orgId}/employees/{employeeRef}/terminate

terminatedDate defaults to today. Terminated employees lose portal access immediately, stop receiving reminders, are excluded from employeeCount and signature-completion percentages, and are preserved (with their signature history) for audit purposes. Terminating is idempotent: a second call does not move terminatedDate. To bring someone back, POST …/{employeeRef}/reactivate.

PUT /organizations/{orgId}/employees/import — multipart/form-data with a file field (CSV, up to 100 MB)

Creates or updates employees in bulk, matching on employeeId. The import runs asynchronously: the response is 202 with a job you can poll at GET /organizations/{orgId}/employees/import/{jobId}. status goes from pending to completed.

deactivatedCount is always 0: an import never terminates employees. Only one import can run per organization at a time (409 conflict otherwise).

Send complete rows. The update half of the import replaces the whole employee row, so any column absent from the CSV is cleared on existing employees (for example an employee loses teamName, location, country and managerEmployeeId after a six-column import).

Accepted CSV headers: email, employee_id, first_name, last_name, dob, team_name, job_title (also jobTitle / JobTitle), location, state, country, department, division, manager_name, manager_email, manager_id, cost_center, hire_date, employee_type, pay_type, company, leave_status, username, code, source_id, source.

The import does not validate email format. Imported employees receive no welcome email, so their employee.created event carries no activationLink (null).

Groups are how you assign handbooks to sets of employees. All under /organizations/{orgId}/groups, access token. Requests that take group names (employee groups, handbook assignments) accept at most 50 names.

Partner API documentation: