Collections
Activities
Activity definitions
Usages
Update usage

Update usage

Introduction

Update an existing usage for an activity definition. When updating, you must provide both the original dates and the updated dates to identify which usage to modify.

Tip

Check the Swagger page for more technical information on the endpoints.

Endpoint details

PUT
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. 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

This list of properties is applicable for this endpoint.

Property Type Description
activityUsageKind string Determines the rights on People, Groups, or Circles. Valid values: Person, Group, Circle. Required
usageReference.id integer ID or a Custom external reference. Required
originalFrom string The existing start date in myProtime (YYYY-MM-DD). It must match the current value in the system. Required
originalUntil string The existing end date in myProtime (YYYY-MM-DD). If no end date exists, omit originalUntil from the request; otherwise, use the current value.
updatedFrom string The new start date for the usage (YYYY-MM-DD). Required
updatedUntil string The new end date for the usage (YYYY-MM-DD). If no end date is required, omit updatedUntil or send it as an empty string ("").

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.

Good to Know

Overlapping usages

Usages cannot have overlapping date periods for the same combination of activity definition, usage kind, and usage reference. When updating a usage, ensure that the new date range does not overlap with other existing usages. If the updated dates would create an overlap, the API will return an error.

To modify dates that would overlap with another usage, you must first adjust or delete the conflicting usage record.

Examples

Update usage dates for a circle

Example updating usage dates for circle with ID 13:

PUT
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
  },
  "originalFrom": "2025-01-01",
  "originalUntil": "2025-12-31",
  "updatedFrom": "2025-01-15",
  "updatedUntil": "2025-12-31"
}

Update usage for a person

Example updating usage for person with ID 1234:

PUT
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
  },
  "originalFrom": "2025-01-01",
  "originalUntil": "2026-01-01",
  "updatedFrom": "2025-02-01",
  "updatedUntil": "2025-12-31"
}
Create usageDelete usage