Create an assignment
Creates a new assignment record.
Caution
This endpoint is only available if clients are not using Planning Flex or Shift.
Tip
Check the Swagger page for more technical information on the endpoints.
Endpoint details
POST
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/assignments
Headers: Authorization: Bearer {token}, User-Agent: {agent}
Scope: connector-protimeapi-assignments.write
Body properties
| Field | Type | Required | Writable | Description |
|---|---|---|---|---|
person.id |
integer | Yes | Yes | Internal ID of the person who the assignment is for (or use external reference). |
from |
string | Yes | Yes | Start date of the assignment (YYYY-MM-DD). |
until |
string | No | Yes | End date of the assignment (YYYY-MM-DD). |
startTimeInMinutes |
integer | No | Yes | Start time in minutes since midnight (-1440 and 2880). |
endTimeInMinutes |
integer | No | Yes | End time in minutes since midnight (-1440 and 2880). |
breakDurationInMinutes |
integer | No | Yes | Duration of the break in minutes. |
comments |
string | No | Yes | Comments associated with the assignment. |
activityLevels.level |
integer | Yes | Yes | A list of levels in the activity structure of the registered activity definition. |
activityLevels.activityDefinition.id |
string | Yes | Yes | Unique identifier for the activity definition registered. |
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 |
|---|---|---|
people |
@badge-number, @employee-number |
Supported |
activity-definitions |
@data-entry-code, @external-reference |
Supported |
Error responses
| Status | Condition |
|---|---|
400 |
Validation failed (missing required fields, invalid values) |
401 |
Missing or invalid access token, or insufficient scope |
Success response
201 Created with a Location header pointing to the new assignment.
Examples
Create an assignment with internal IDs
Example creating an assignment for person with ID 1234:
POST
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/assignments
{
"person": {
"id": 1234
},
"from": "2025-03-10",
"until": "2025-03-10",
"startTimeInMinutes": 480,
"endTimeInMinutes": 1020,
"breakDurationInMinutes": 30,
"comments": "Morning shift",
"activityLevels": [
{
"level": 1,
"activityDefinition": {
"id": "a7d853ea-89eb-4735-83d1-b891c6fde398"
}
}
]
}Create an assignment with external reference for person
Example creating an assignment using the employee number as the external reference:
POST
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/assignments
{
"person": {
"externalReferences": {
"@employee-number": "5678"
}
},
"from": "2025-03-10",
"until": "2025-03-10",
"startTimeInMinutes": 480,
"endTimeInMinutes": 1020,
"breakDurationInMinutes": 30,
"activityLevels": [
{
"level": 1,
"activityDefinition": {
"id": "a7d853ea-89eb-4735-83d1-b891c6fde398"
}
}
]
}Create an assignment with multiple activity levels
Example creating an assignment with multiple activity levels:
POST
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/assignments
{
"person": {
"id": 1234
},
"from": "2025-03-10",
"until": "2025-03-10",
"startTimeInMinutes": 480,
"endTimeInMinutes": 1020,
"breakDurationInMinutes": 30,
"activityLevels": [
{
"level": 1,
"activityDefinition": {
"id": "a7d853ea-89eb-4735-83d1-b891c6fde398"
}
},
{
"level": 2,
"activityDefinition": {
"id": "22d320ed-f6ed-44bd-b7b1-fe58f518960c"
}
}
]
}