Employees

Employees are human staff members linked to agents for call routing. The AI agent uses employee information to decide who to transfer calls to or notify after a call.

Status system

Each employee has a status indicating their availability:

Status	Translation	Description
`anwesend`	Present	Available for calls
`urlaub`	Vacation	Away on vacation
`krank`	Sick	On sick leave
`weiterbildung`	Training	In training
`notdienst`	Emergency duty	On-call for emergencies
`im_termin`	In a meeting	Temporarily unavailable
`ausser_haus`	Out of office	Away from the office

Data model

Field	Type	Description
`id`	uuid	Employee identifier
`name`	string	Employee name (required, max 255 chars)
`phone_number`	string	Phone number (max 30 chars)
`email`	string	Email address
`status`	string	One of the 7 statuses above
`active`	boolean	Whether the employee is active (default: `true`)
`get_mail`	boolean	Receives email notifications (default: `false`)
`agent_id`	uuid	Parent agent
`organization_id`	uuid	Organization (read-only, derived from the agent)
`back_at_work_at`	date	Expected return date while absent (`YYYY-MM-DD`)
`notdienst_bereiche`	string[]	Emergency-duty areas of the current shift, taken from the organization’s `notdienst_bereiche` — one employee can cover several at once. Only kept while `status` is `notdienst`; any other status clears them. Trimmed and de-duplicated; an empty list becomes `null`. If the organization has more than one area, status `notdienst` requires at least one
`created_at`	datetime	Creation timestamp
`updated_at`	datetime	Last update timestamp

Endpoints

List employees

GET /v1/agents/{agentId}/employees

Permission: employees:read | Pagination: yes Filters:

Parameter	Type	Description
`status`	string	Filter by status (e.g., `?status=anwesend`); unknown values are ignored, not rejected
`active`	boolean	Filter by active state (e.g., `?active=true`)

# List only present, active employees
curl -H "X-API-Key: $TP_KEY" \
  "$TP_BASE/agents/{agentId}/employees?status=anwesend&active=true"

Get employee

GET /v1/agents/{agentId}/employees/{employeeId}

Permission: employees:read

Create employee

POST /v1/agents/{agentId}/employees

Permission: employees:write Required fields: name The employee is linked to the agent in the same request (the link is what the agent detail page in the dashboard and the runtime lookup by agent use). If the link cannot be written, the employee is not created and the request returns 500.

curl -X POST -H "X-API-Key: $TP_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Max Mustermann",
    "phone_number": "+491701234567",
    "email": "max@example.com",
    "status": "anwesend",
    "active": true,
    "get_mail": true
  }' \
  "$TP_BASE/agents/{agentId}/employees"

Update employee

PATCH /v1/agents/{agentId}/employees/{employeeId}

Permission: employees:write Common use case: changing the status (e.g., marking an employee as on vacation). Updatable: name, phone_number, email, status, active, get_mail, back_at_work_at, notdienst_bereiche; unknown fields are ignored.

# Mark as on vacation
curl -X PATCH -H "X-API-Key: $TP_KEY" -H "Content-Type: application/json" \
  -d '{"status": "urlaub", "back_at_work_at": "2026-09-22"}' \
  "$TP_BASE/agents/{agentId}/employees/{employeeId}"

# Emergency duty for the electrical and security areas
curl -X PATCH -H "X-API-Key: $TP_KEY" -H "Content-Type: application/json" \
  -d '{"status": "notdienst", "notdienst_bereiche": ["Elektro", "Sicherheit"]}' \
  "$TP_BASE/agents/{agentId}/employees/{employeeId}"

Delete employee

DELETE /v1/agents/{agentId}/employees/{employeeId}

Permission: employees:write | Returns 204 No Content

Common patterns

Sync employee status from HR system

const hrEmployees = await fetchFromHR();
const { data: tpEmployees } = await talkpilot(`/agents/${agentId}/employees`);

for (const hr of hrEmployees) {
  const match = tpEmployees.find(e => e.name === hr.name);
  if (match && match.status !== hr.status) {
    await talkpilot(`/agents/${agentId}/employees/${match.id}`, {
      method: "PATCH",
      body: JSON.stringify({ status: hr.status }),
    });
  }
}

Agents — Parent resource
Forwarding Slots — Call routing using employees
Employee Management — Dashboard UI guide

API Resources

Endpoint Reference

Guides

Code Examples

Status system

Data model

Endpoints

List employees

Get employee

Create employee

Update employee

Delete employee

Common patterns

Sync employee status from HR system

​Status system

​Data model

​Endpoints

​List employees

​Get employee

​Create employee

​Update employee

​Delete employee

​Common patterns

​Sync employee status from HR system

​Related resources

Status system

Data model

Endpoints

List employees

Get employee

Create employee

Update employee

Delete employee

Common patterns

Sync employee status from HR system

Related resources