Create a contract
Creates a new contract for a person.
Tip
Check the Swagger page for more technical information on the endpoints.
Endpoint details
POST
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/contracts
Headers: Authorization: Bearer {token}, User-Agent: {agent}
Scope: connector-protimeapi-contracts.write
Body properties
| Field | Type | Required | Writable | Description |
|---|---|---|---|---|
person.id |
integer | Yes | Yes | Internal ID of the person the contract belongs to (or use person.externalReferences). |
person.externalReferences |
object | No | Yes | External reference identifying the person, instead of person.id. |
code |
string | No | Yes | The contract code. Maximum 50 characters. |
from |
string | Yes | Yes | Start date of the contract (YYYY-MM-DD). Must be on or after 1900-01-01. |
until |
string | No | Yes | End date of the contract (YYYY-MM-DD). Must be on or after from. |
contractHoursInMinutes |
integer | Yes | Yes | Contracted hours in minutes. Between 1 and 5999. |
fullTimeEquivalentInMinutes |
integer | Yes | Yes | The equivalent in minutes for a full-time contract. Between 1 and 5999. |
numberOfWorkingDaysPerWeek |
integer | Yes | Yes | The number of working days per week. Between 0 and 7. |
numberOfDaysInContractPeriod |
integer | Yes | Yes | The number of days in the contract period. Between 7 and 364, and a multiple of 7. |
kind |
string | Yes | Yes | The kind of contract (Unknown, Contract, Addendum). |
parentContract.id |
integer | No | Yes | Internal ID of the parent contract. Required when kind is Addendum, and rejected otherwise. |
External references
The endpoint resolves person.externalReferences from the request body. See the external references page for details.
| Collection | Predefined | Custom |
|---|---|---|
people |
@badge-number, @employee-number |
Supported |
parentContract is resolved by internal ID only.
Error responses
| Status | Condition |
|---|---|
400 |
The person external reference cannot be resolved |
400 |
Validation failed (missing required fields, value out of range, until before from, parentContract supplied for a non-addendum, parentContract missing for an addendum) |
401 |
Missing or invalid access token, or insufficient scope |
Success response
201 Created with a Location header pointing to the new contract. The response body is empty.
Examples
Create a contract with an internal person ID
POST
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/contracts
{
"person": {
"id": 112568
},
"code": "CONTRACT-2025",
"from": "2025-01-01",
"until": "2025-06-30",
"contractHoursInMinutes": 2400,
"fullTimeEquivalentInMinutes": 2400,
"numberOfWorkingDaysPerWeek": 5,
"numberOfDaysInContractPeriod": 7,
"kind": "Contract"
}Create a contract with a person external reference
POST
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/contracts
{
"person": {
"externalReferences": {
"@employee-number": "EMP1234"
}
},
"from": "2025-01-01",
"contractHoursInMinutes": 2280,
"fullTimeEquivalentInMinutes": 2400,
"numberOfWorkingDaysPerWeek": 5,
"numberOfDaysInContractPeriod": 14,
"kind": "Contract"
}Create an addendum
An addendum requires a parent contract.
POST
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/contracts
{
"person": {
"id": 112568
},
"from": "2025-07-01",
"until": "2025-12-31",
"contractHoursInMinutes": 1200,
"fullTimeEquivalentInMinutes": 2400,
"numberOfWorkingDaysPerWeek": 3,
"numberOfDaysInContractPeriod": 7,
"kind": "Addendum",
"parentContract": {
"id": 186
}
}