Create usage
Creates a new usage for an activity definition.
Tip
Check the Swagger page for more technical information on the endpoints.
Endpoint details
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/{structureVersionId}/levels/{level}/activity-definitions/{activityDefinitionReference}/usages
Headers: Authorization: Bearer {token}, User-Agent: {agent}
Scope: connector-protimeapi-activity-definitions.write
URL parameters
These parameters need to be filled in when calling this endpoint.
| Parameter | Description |
|---|---|
<structureVersionId> |
The ID of the activity structure. Can be found in the configuration in myProtime. |
<level> |
Defines the level in the structure. |
<activityDefinitionReference> |
The internal ID or an external reference. |
Body properties
| Field | Type | Required | Writable | Description |
|---|---|---|---|---|
activityUsageKind |
string | Yes | Yes | Determines the rights on People, Groups, or Circles. Valid values: Person, Group, Circle. |
usageReference.id |
integer | Yes | Yes | ID or a Custom external reference. |
from |
date | Yes | Yes | Start date of the usage (YYYY-MM-DD). |
until |
date | No | Yes | End date of the usage (YYYY-MM-DD). If no end date is required, omit “until” or send it as an empty string (""). |
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 |
|---|---|---|
activity-definitions |
@data-entry-code, @external-reference |
Supported |
circles |
None | Supported |
groups |
None | 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.
Success response
200 OK
Error responses
| Status | Condition |
|---|---|
400 |
Validation error or invalid external reference format |
401 |
Missing or invalid access token, or insufficient scope |
404 |
Activity definition not found |
Examples
Create usage for a circle
Example creating usage for circle with ID 13:
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/b2347a7a-d60d-446f-b03b-7es2cc8c3281/levels/3/activity-definitions/38fc2206-b51f-434a-9c36-9e0esfc5e70e/usages
{
"activityUsageKind": "Circle",
"usageReference": {
"id": 13
},
"from": "2025-01-01",
"until": "2025-12-31"
}Create usage for a group
Example creating usage for group with ID 5:
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/b2347a7a-d60d-446f-b03b-7es2cc8c3281/levels/2/activity-definitions/22d320ed-f6ed-44bd-b7b1-fe58f518960c/usages
{
"activityUsageKind": "Group",
"usageReference": {
"id": 5
},
"from": "2025-01-01"
}Create usage for a person
Example creating usage for person with ID 1234:
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/b2347a7a-d60d-446f-b03b-7es2cc8c3281/levels/1/activity-definitions/a7d853ea-89eb-4735-83d1-b891c6fde398/usages
{
"activityUsageKind": "Person",
"usageReference": {
"id": 1234
},
"from": "2025-01-01",
"until": "2026-01-01"
}Create open-ended usage (no end date)
Example creating open-ended usage for circle with ID 20:
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/b2347a7a-d60d-446f-b03b-7es2cc8c3281/levels/3/activity-definitions/38fc2206-b51f-434a-9c36-9e0esfc5e70e/usages
{
"activityUsageKind": "Circle",
"usageReference": {
"id": 20
},
"from": "2025-01-01"
}