Retrieve a contract
Returns a single contract record by its internal ID or external reference.
Tip
Check the Swagger page for more technical information on the endpoints.
Endpoint details
GET
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/contracts/{contractReference}
Headers: Authorization: Bearer {token}, User-Agent: {agent}
Scope: connector-protimeapi-contracts.read
URL parameters
| Parameter | Description |
|---|---|
{contractReference} |
The internal ID or external reference of the contract. |
Response properties
| Field | Type | Required | Writable | Description |
|---|---|---|---|---|
changeVersion |
string | — | Read-only | Property to indicate the order of changes. |
id |
integer | — | Read-only | Unique identifier for the contract record. |
person.id |
integer | — | Read-only | Internal ID of the person. |
code |
string | — | Read-only | The contract code. |
from |
string | — | Read-only | Start date of the contract for when it’s active. |
until |
string | — | Read-only | End date of the contract. |
contractHoursInMinutes |
integer | — | Read-only | Contracted hours in minutes. |
fullTimeEquivalentInMinutes |
integer | — | Read-only | The equivalent in minutes for a full-time contract. |
contractPercentage |
number | — | Read-only | Percentage of full-time contract. |
numberOfWorkingDaysPerWeek |
integer | — | Read-only | The number of working days per week. |
numberOfDaysInContractPeriod |
integer | — | Read-only | The number of days in the contract period. |
kind |
string | — | Read-only | The kind of contract (Contract, Addendum). |
parentContract.id |
integer | — | Read-only | Identifier of the parent contract. |
External references
The endpoint supports predefined and custom external references. See the external references page for details.
The following collections are supported for this endpoint:
| Collection | Predefined | Custom |
|---|---|---|
contracts |
Not available | Supported |
people |
@badge-number, @employee-number |
Supported |
Caution
There are some restrictions on the characters allowed in URL requests. See the fetching resources page for more information.
Error responses
| Status | Condition |
|---|---|
400 |
Invalid external reference key or value |
401 |
Missing or invalid access token, or insufficient scope |
404 |
Contract with the given ID or external reference does not exist |
Examples
Retrieving a contract by internal ID
Example with internal ID 186:
GET
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/contracts/186
With custom external reference
Example with custom external reference CONTRACT-2025:
GET
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/contracts/CONTRACT-2025?externalReferences=(contracts,customContractCode)