Create activity definition

Creates a new activity definition record.

Endpoint details

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.

Body properties

External references

This endpoint takes its references from the request body. An externalReferences query parameter sent to this endpoint has no effect.

See the external references page for details.

External reference identifier

externalReferenceIdentifier holds exactly one key-value pair. The key is either a predefined reference (@data-entry-code, @external-reference) or a custom reference name; the value is the identifier the activity definition carries in the external system.

Any key starting with @ is treated as predefined; only @data-entry-code and @external-reference are valid. When an existing activity definition already carries the same reference, the request returns 409 and the activity definition is not created. Omitting the property skips this check.

Success response

Returns 201 Created with a Location header pointing to the new activity definition. The response body is empty.

Error responses

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. The reference name is supplied inside parent.externalReferences; no externalReferences query parameter is needed on this endpoint:

{
  "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 with a custom external reference identifier

The pair is stored for the activity-definitions collection, so the activity definition can afterwards be addressed as ?externalReferences=(activity-definitions,erp-activity-id).

{
  "name": {
    "default": "Logistics"
  },
  "shortCode": "LOG",
  "dataEntryCode": "3003",
  "externalReferenceIdentifier": {
    "erp-activity-id": "ERP-4711"
  }
}

Create activity definition with a predefined external reference identifier

The value of @data-entry-code must match the dataEntryCode field. Nothing is stored: the entry only guarantees that no other activity definition on this structure version and level already uses data entry code 3004.

{
  "name": {
    "default": "Maintenance"
  },
  "shortCode": "MNT",
  "dataEntryCode": "3004",
  "externalReferenceIdentifier": {
    "@data-entry-code": "3004"
  }
}

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