Create activity definition

Introduction

Create a new activity definition using the POST endpoint. The ID of the newly created activity definition will be available in the Location header of the response.

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.

Examples

Create basic activity definition

Example creating a basic activity definition:

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

Create activity definition with hierarchy

Example creating an activity definition with a parent hierarchy:

{
  "name": {
    "default": "Cleaning",
    "translations": {
      "nl": "Schoonmaken",
      "fr": "Nettoyer"
    }
  },
  "parent": {
    "id": "0b3642ae-16c9-4914-b099-2ba4b99d5ee9"
  },
  "shortCode": "CL_001",
  "dataEntryCode": "00025",
  "externalReference": "Cleaning",
  "info": "Cleaning the main building",
  "activeFrom": "2025-01-01",
  "activeUntil": "2026-01-01"
}

Create activity definition with external reference for parent

Example creating an activity definition using an external reference for the parent:

{
  "name": {
    "default": "Sales Activities",
    "translations": {
      "nl": "Verkoopactiviteiten",
      "fr": "Activités de vente"
    }
  },
  "parent": {
    "externalReferences": {
      "@data-entry-code": "10000"
    }
  },
  "shortCode": "SA_001",
  "dataEntryCode": "10001",
  "externalReference": "SALES01",
  "info": "All sales related activities",
  "activeFrom": "2025-01-01"
}

Create activity definition without end date

Example creating an activity definition without an end date:

{
  "name": {
    "default": "HR"
  },
  "shortCode": "HR",
  "dataEntryCode": "2002",
  "externalReference": "HR00002",
  "info": "Human Resource department",
  "activeFrom": "2025-01-01"
}