Retrieve usages
Introduction
Returns usages for a specific 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
URL parameters
These parameters need to be filled in when calling this endpoint.
| Parameter | Description |
|---|---|
<structureVersionId> |
The ID of the activity structure. The ID can be found in the configuration in myProtime. |
<level> |
Defines the level in the structure. |
<activityDefinitionReference> |
The internal ID or an external reference. |
Response properties
This list of properties is returned by this endpoint.
| Property | Type | Description |
|---|---|---|
changeVersion |
string | Property to indicate the order of changes. |
activityDefinition.id |
string | Unique identifier for the activity definition. |
usages.activityUsageKind |
string | The kind of usage: (circle, group, or person). |
usages.usageReference.id |
integer | The reference ID for the usage (circle, group, or person). |
usages.from |
string | Start date (YYYY-MM-DD) for the usage. |
usages.until |
string | End date (YYYY-MM-DD) for the usage. If not set, usage is open-ended. |
External references
It’s possible to use predefined external references and custom external references. More information can be found on the External References Page.
For a list of predefined external references, see the external reference options section.
Note
Check the query options below the endpoint on the Swagger page for the relevant external references.
Caution
There are some restrictions on the characters allowed in URL requests. See the fetching resources page for more information.
Examples
Retrieve usages with internal ID
Example retrieving usages for activity definition with internal ID 38fc2206-b51f-434a-9c36-9e0esfc5e70e:
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
Retrieve usages with external reference
Example retrieving usages with data entry code 30002:
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/b2347a7a-d60d-446f-b03b-7es2cc8c3281/levels/3/activity-definitions/30002/usages?externalReferences=(activity-definitions,@data-entry-code)
Retrieve with external reference in response
Example retrieving usages with internal ID 38fc2206-b51f-434a-9c36-9e0esfc5e70e and requesting data entry code in response:
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?externalReferences=(activity-definitions,@data-entry-code)