Skip to content
Book a Demo

Create an employee

POST /v1/employees

Creates one employee in your workspace. If the email belongs to an employee who was deleted from the workspace, the API restores that employee with access disabled. Do not set send_invitation to true for such an email: the API then returns 422 and restores nothing.

Requires a workspace API-client key with the employees:write scope.

Run this example in a test workspace. Replace alex@example.com with an email address that no FeedbackPulse workspace uses. The example creates an employee and sends no invitation. Use a distinct idempotency key for each new employee and keep it the same when retrying that request.

Terminal window
curl --request POST 'https://api.feedbackpulse.com/v1/employees' \
--header "Authorization: Bearer $FEEDBACKPULSE_API_KEY" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-hr:hire-123' \
--data '{
"name": "Alex Example",
"email": "alex@example.com",
"type": "full-time",
"job_title": "Product Designer"
}'

HTTP 201 Created

{
"data": {
"id": "emp_01J9EXAMPLE",
"name": "Alex Example",
"email": "alex@example.com",
"job_title": "Product Designer",
"department": null,
"employee_number": null,
"type": "full-time",
"employment_status": "active",
"account_status": "not-invited",
"access_status": "enabled",
"is_manager": false,
"hire_date": null,
"termination_date": null,
"created_at": "2026-11-02T09:00:00+00:00",
"updated_at": "2026-11-02T09:00:00+00:00",
"manager": null
}
}

Send a JSON object. To assign a manager, set manager_id to an employee id from List employees. Set send_invitation to true to email an account invitation. Without it, FeedbackPulse sends no invitation.

Header Required Description
Authorization Yes Bearer API-client key with employees:write.
Content-Type Yes application/json
Idempotency-Key No Replays the original response when the same API client sends the same key and same request fingerprint to the same POST route. Rate-limited (429) and server error (5xx) responses are not stored, so retry them with the same key. A key whose request never finished returns 409 idempotency_key_in_progress for 10 minutes; after that, the next request with the same key and payload runs again.
Field Type Required Description
name string Yes
email string Yes Format: email.
job_title string or null No
department string or null No
employee_number string or null No
type string Yes Values: full-time, part-time, contractor.
employment_status string No Rehire changes employment only. Access requires explicit admin reinstatement. Values: active, terminated.
hire_date string or null No Format: date.
termination_date string or null No Format: date.
is_manager boolean No
manager_id string or null No Canonical public employee identifier for the manager, for example emp_01H.... Internal numeric ids are rejected.
send_invitation boolean No

A 201 response contains the new employee in data. If the invitation email fails, the employee is still created and meta.warnings contains invitation_send_failed. A 422 response can also mean that the email is already in use, in this or another FeedbackPulse workspace, or that the workspace is at the employee limit of its plan.

Field Type Required Description
data object Yes
data.id string Yes Canonical public employee identifier, for example emp_01H....
data.name string Yes
data.email string Yes Format: email.
data.job_title string or null No
data.department string or null No
data.employee_number string or null No
data.type string or null No
data.employment_status string Yes Values: active, terminated.
data.account_status string or null Yes Null means activation history is unknown for a legacy terminated employee. Values: not-invited, invited, active, null.
data.access_status string Yes Values: enabled, disabled.
data.is_manager boolean Yes
data.hire_date string or null No Format: date.
data.termination_date string or null No Format: date.
data.created_at string Yes Format: date-time.
data.updated_at string Yes Format: date-time.
data.manager object or null No
data.manager.id string No Canonical public employee identifier, for example emp_01H....
data.manager.name string No
meta object No
meta.warnings array No
HTTP status Meaning
201 Employee created
401 Missing or invalid bearer token
403 Authenticated but lacking the required API client scope
409 Idempotency key reused with a different request payload or still in progress
422 Validation failed or the idempotency key is invalid
429 Rate limit exceeded

See API errors and rate limits or download the OpenAPI contract.