Create or update activity definitions

Introduction

You can use this endpoint to create a new or update an existing activity definition. This behavior depends on the use of the reference, as follows:

• If the external reference corresponds to an existing activity definition, that definition will be updated.
• If the external reference does not match any existing activity definition, a new one will be created.
• Creating or updating activity definitions is only possible using an external reference.

When using an internal ID as a reference, only an update is supported since these ID’s are generated during creations and can’t be provided. An update of the activity definition will happen when it already exists, or a “404: not found” error will be responded when the internal ID is not known in our system.

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

Data entry code configuration

The dataEntryCode field behavior depends on your Protime configuration:

• Auto-generated: Protime automatically generates data entry codes when creating activity definitions.
• Manual entry: When configured to require manual entry, you must provide the dataEntryCode in your request. The field becomes mandatory and the API will return a 400 Bad Request error if it’s missing or null.

Data entry codes are primarily used on hardware devices for quick activity selection. See the property table above for field constraints.

Understanding hierarchy

A hierarchy is a structured way to organize and manage complex data by adding order and relationships. For instance, in a multinational organization, tracking an activity might become challenging when every country has a “Sales” department. Instead of using overly detailed names (e.g., “Country - City - Sales”), a hierarchy allows the user to define levels such as Company > Country > Location > Department. This ensures uniqueness and simplifies tasks like filtering reports (e.g., selecting all activities for “Country” with one filter).

Add hierarchy

If you want to add a hierarchy, a parent ID must be included in the request. This ID is available in the location header after a successful POST call for an activity definition. It’s possible to use predefined or custom external references for the parent.

Hierarchy can only be used when an activity definition is created. Updating a hierarchy isn’t possible.

Default usage

When your activity structure contains hierarchical levels, you can enable “default usage” in the activity structure configuration. This automatically adds a usage with an infinite period for the organizational chart group(s) to whom the structure is assigned for any activity definition created in the top level of your hierarchy.

This can be useful as you no longer need to assign usages to hierarchies manually. Manual usage configuration is still possible if you need to limit access to specific circles, groups, or people.

Parent in hierarchy

If the ID matches an existing activity definition and it has a parent, the parent should be included in the request. Otherwise, a “Bad Request” response will be returned. It’s possible to use an external reference for the parent.

Examples

Create activity definition

Example creating an activity definition using custom external reference Cleaning:

{
  "name": {
    "default": "Cleaning",
    "translations": {
      "nl": "Schoonmaken",
      "fr": "Nettoyer"
    }
  },
  "shortCode": "CL_002",
  "dataEntryCode": "00026",
  "externalReference": "Cleaning",
  "info": "Cleaning the main building",
  "activeFrom": "2025-01-01",
  "activeUntil": "2026-01-01"
}

Update activity definition with data entry code

Example updating an activity definition using data entry code 20003:

{
  "name": {
    "default": "Cleaning"
  },
  "shortCode": "A003",
  "dataEntryCode": "20003",
  "externalReference": "CL01",
  "info": "Updating Activity Definition",
  "activeFrom": "2025-01-01",
  "activeUntil": "2025-09-30"
}

Create activity definition with hierarchy

Example creating an activity definition with hierarchy using custom external reference Maintenance:

{
  "name": {
    "default": "Cleaning",
    "translations": {
      "nl": "Schoonmaken",
      "fr": "Nettoyer"
    }
  },
  "parent": {
    "id": "0b3642ae-16c9-4914-b099-2ba4b99d5ee9"
  },
  "shortCode": "CL_002",
  "dataEntryCode": "00026",
  "externalReference": "Cleaning",
  "info": "Cleaning activities under maintenance",
  "activeFrom": "2025-01-01",
  "activeUntil": "2026-01-01"
}

Update with custom external reference

Example updating with custom external reference 122456:

{
  "name": {
    "default": "Sales Activities",
    "translations": {
      "nl": "Verkoopactiviteiten",
      "fr": "Activités de vente"
    }
  },
  "shortCode": "SA_001",
  "dataEntryCode": "10001",
  "externalReference": "122456",
  "info": "All sales related activities",
  "activeFrom": "2025-01-01"
}