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.
Example request
Section titled “Example request”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.
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"}'Example response
Section titled “Example response”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 }}Request
Section titled “Request”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.
Headers
Section titled “Headers”| 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. |
JSON body
Section titled “JSON body”| 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 |
Response
Section titled “Response”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 |
Status codes
Section titled “Status codes”| 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.