Skip to main content
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:
StatusTranslationDescription
anwesendPresentAvailable for calls
urlaubVacationAway on vacation
krankSickOn sick leave
weiterbildungTrainingIn training
notdienstEmergency dutyOn-call for emergencies

​
Data model

FieldTypeDescription
iduuidEmployee identifier
namestringEmployee name (required, max 255 chars)
phone_numberstringPhone number (max 30 chars)
emailstringEmail address
statusstringOne of the 5 statuses above
activebooleanWhether the employee is active (default: true)
get_mailbooleanReceives email notifications (default: false)
agent_iduuidParent agent
created_atdatetimeCreation timestamp
updated_atdatetimeLast update timestamp

​
Endpoints

​
List employees

GET /v1/agents/{agentId}/employees
Permission: employees:read | Pagination: yes Filters:
ParameterTypeDescription
statusstringFilter by status (e.g., ?status=anwesend)
activebooleanFilter 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 
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). 
# Mark as on vacation
curl -X PATCH -H "X-API-Key: $TP_KEY" -H "Content-Type: application/json" \
  -d '{"status": "urlaub"}' \
  "$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 }),
    });
  }
}