Create usage

Introduction

Create a new usage for an activity definition to limit who can use it. You can assign usage rights to circles, groups, or individual people.

Endpoint details

URL parameters

These parameters need to be filled in when calling this endpoint.

Body properties

This list of properties is applicable for this endpoint.

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.

Good to Know

Overlapping usages

Usages cannot have overlapping date periods for the same combination of activity definition, usage kind, and usage reference. If you attempt to create a usage where the start and end dates overlap with an existing usage record, the API will return an error indicating that overlapping usages are not allowed.

To add a usage during an already covered period, you must first modify or delete the existing usage.

Examples

Create usage for a circle

Example creating usage for circle with ID 13:

{
  "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:

{
  "activityUsageKind": "Group",
  "usageReference": {
    "id": 5
  },
  "from": "2025-01-01"
}

Create usage for a person

Example creating usage for person with ID 1234:

{
  "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:

{
  "activityUsageKind": "Circle",
  "usageReference": {
    "id": 20
  },
  "from": "2025-01-01"
}