Before you start
Send Accept: application/json and Authorization: Bearer YOUR_TOKEN to https://{subdomain}.talentohq.com. See API for authentication.
Path and query identifiers are UUID strings.
Successful responses use 200. Validation failures use 422. Missing or invalid tokens, and records that cannot be found, use 401.
List all contracts of an employee
GET /api/v3/employees/{employee_id}/contracts
| Parameter | Type | Description |
|---|---|---|
employee_id |
string (UUID) | Employee id. |
Response 200
[
{
"id": "8d429d99-fbd4-4196-a9ac-94f1dc481344",
"employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
"employee_name": "Employee name",
"contract_category_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58",
"contract_category_name": "Part time",
"working_category_id": "8802f881-04c4-4ad0-b56b-28851b1e6825",
"working_category_name": "Full day",
"contract_end_reason_id": null,
"contract_end_reason_name": null,
"job_category_id": "9956bff3-c5c8-458a-a594-1946a50c85e8",
"job_category_name": "Junior developer",
"job_position_id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
"job_position_name": "Developer",
"start_on": "2021-05-27",
"end_on": "2023-09-28",
"annual_leave_days": "24.0",
"active": false,
"currency": "eur",
"gross_salary": 45000.0,
"gross_salary_effective_on": "2021-05-27",
"workload_percentage": "100.0",
"available_leave_days": "0.0",
"available_extra_hours": "0.0",
"create_offboarding": false
},
{
"id": "7b25791b-6e76-4bea-a821-46efde3869b3",
"employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
"employee_name": "Employee name",
"contract_category_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58",
"contract_category_name": "Part time",
"working_category_id": "8802f881-04c4-4ad0-b56b-28851b1e6825",
"working_category_name": "Full day",
"contract_end_reason_id": null,
"contract_end_reason_name": null,
"job_category_id": "9956bff3-c5c8-458a-a594-1946a50c85e8",
"job_category_name": "Junior developer",
"job_position_id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
"job_position_name": "Developer",
"start_on": "2021-05-27",
"end_on": null,
"annual_leave_days": "24.0",
"active": true,
"currency": "eur",
"gross_salary": 45000.0,
"gross_salary_effective_on": "2021-05-27",
"workload_percentage": "100.0",
"available_leave_days": "0.0",
"available_extra_hours": "0.0",
"create_offboarding": false
}
]
Create a contract
POST /api/v3/employees/{employee_id}/contracts
Request
{
"start_on": "2025-01-01",
"end_on": "2025-12-01",
"gross_salary": 70000,
"salary_effective_on": "2025-01-01",
"currency": "eur",
"annual_leave_days": 30,
"workload_percentage": 100,
"create_offboarding": true,
"job_position_id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
"working_category_id": "8802f881-04c4-4ad0-b56b-28851b1e6825",
"contract_category_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58",
"contract_end_reason_id": null
}
Response 200
{
"id": "8d429d99-fbd4-4196-a9ac-94f1dc481344",
"employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
"employee_name": "Employee name",
"contract_category_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58",
"contract_category_name": "Part time",
"working_category_id": "8802f881-04c4-4ad0-b56b-28851b1e6825",
"working_category_name": "Full day",
"contract_end_reason_id": null,
"contract_end_reason_name": null,
"job_category_id": "9956bff3-c5c8-458a-a594-1946a50c85e8",
"job_category_name": "Junior developer",
"job_position_id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
"job_position_name": "Developer",
"start_on": "2025-01-01",
"end_on": "2025-12-01",
"annual_leave_days": "24.0",
"active": false,
"currency": "eur",
"gross_salary": 70000.0,
"gross_salary_effective_on": "2021-05-27",
"workload_percentage": "100.0",
"available_leave_days": "0.0",
"available_extra_hours": "0.0",
"create_offboarding": true
}
Show a contract
GET /api/v3/employees/{employee_id}/contracts/{contract_id}
| Parameter | Type | Description |
|---|---|---|
employee_id |
string (UUID) | Employee id. |
contract_id |
string (UUID) | Contract id. |
Response 200
{
"id": "8d429d99-fbd4-4196-a9ac-94f1dc481344",
"employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
"employee_name": "Employee name",
"contract_category_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58",
"contract_category_name": "Part time",
"working_category_id": "8802f881-04c4-4ad0-b56b-28851b1e6825",
"working_category_name": "Full day",
"contract_end_reason_id": null,
"contract_end_reason_name": null,
"job_category_id": "9956bff3-c5c8-458a-a594-1946a50c85e8",
"job_category_name": "Junior developer",
"job_position_id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
"job_position_name": "Developer",
"start_on": "2021-05-27",
"end_on": "2023-09-28",
"annual_leave_days": "24.0",
"active": false,
"currency": "eur",
"gross_salary": 45000.0,
"gross_salary_effective_on": "2021-05-27",
"workload_percentage": "100.0",
"available_leave_days": "0.0",
"available_extra_hours": "0.0",
"create_offboarding": false
}
Update a contract
PUT /api/v3/employees/{employee_id}/contracts/{contract_id}
Request
{
"start_on": "2020-05-27",
"annual_leave_days": 32,
"workload_percentage": 80,
"contract_category_id": "7959a043-0eb1-45f5-8da9-0a5b4aea6404",
"working_category_id": "8802f881-04c4-4ad0-b56b-28851b1e6825",
"job_position_id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
"contract_end_reason_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58",
"gross_salary": 48000,
"salary_effective_on": "2020-05-27"
}
Response 200
{
"id": "8d429d99-fbd4-4196-a9ac-94f1dc481344",
"employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
"employee_name": "Employee name",
"contract_category_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58",
"contract_category_name": "Part time",
"working_category_id": "8802f881-04c4-4ad0-b56b-28851b1e6825",
"working_category_name": "Full day",
"contract_end_reason_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58",
"contract_end_reason_name": "Resignation",
"job_category_id": "9956bff3-c5c8-458a-a594-1946a50c85e8",
"job_category_name": "Junior developer",
"job_position_id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
"job_position_name": "Developer",
"start_on": "2020-05-27",
"end_on": "2023-09-28",
"annual_leave_days": "32.0",
"active": false,
"currency": "eur",
"gross_salary": 45000.0,
"gross_salary_effective_on": "2021-05-27",
"workload_percentage": "80.0",
"available_leave_days": "0.0",
"available_extra_hours": "0.0",
"create_offboarding": false
}
Delete a contract
DELETE /api/v3/employees/{employee_id}/contracts/{contract_id}
Response 200
{}