Delete usage

Reference

Collections

Activities

Activity definitions

Usages

Delete usage

Deletes an existing usage for an activity definition.

Tip

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

Endpoint details

DELETE

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 date is present, 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

204 No Content

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

Delete usage for a circle with end date

Example deleting usage for circle with ID 13:

DELETE

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"
}

Response:
204 No Content

Delete usage for a group

Example deleting usage for group with ID 5:

DELETE

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"
}

Response:
204 No Content

Delete usage for a person

Example deleting usage for person with ID 1234:

DELETE

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"
}

Response:
204 No Content

Delete open-ended usage (no end date)

Example deleting open-ended usage for circle with ID 20:

DELETE

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",
  "until": ""
}

Response:
204 No Content

Update usage