Create or update activity definitions

Reference

Collections

Activities

Definitions

Create or update activity definitions

Creates or updates an activity definition record (upsert). If the referenced activity definition exists, it is updated. If it does not exist, a new one is created.

Tip

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

Caution

If some other required fields are missing from the request, they will be left empty.

Endpoint details

PUT

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/{structureVersionId}/levels/{level}/activity-definitions/{activityDefinitionReference}

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. The ID can be found in the configuration in myProtime.
`<level>`	Defines the level in the structure.
`<activityDefinitionReference>`	The internal ID (GUID) or an external reference of the activity definition.

Body properties

Field	Type	Required	Writable	Description
`name.default`	string	Yes	Yes	Default name value of the activity definition. Shown to users if no translation is available.
`name.translations`	object	No	Yes	A list of translated names by language code. Allows localization for different languages.
`parent.id`	Guid	No	Yes	Unique identifier of the parent activity definition in a hierarchy set-up. Only used when creating (upsert).
`parent.externalReferences`	object	No	Yes	External references to resolve the parent activity definition. Only used when creating (upsert).
`shortCode`	string	No	Yes	Short code for the activity definition.
`dataEntryCode`	string	No	Yes	Data entry code for the activity definition, mostly used on hardware devices. Mandatory or optional depending on configuration. Can only be 16 characters long!
`externalReference`	string	No	Yes	External reference identifier for the activity definition. Needs to be unique within the structure and level when used! Can only be 16 characters long!
`info`	string	No	Yes	Additional information about the activity definition. Can be used for notes or extra details.
`activeFrom`	date	No	Yes	Start date (YYYY-MM-DD) when the activity definition is active. Controls when the definition becomes available for registrations.
`activeUntil`	date	No	Yes	End date (YYYY-MM-DD) when the activity definition is no longer active. Must be greater than or equal to `activeFrom` when both are specified.

Tip

If your configuration requires users to manually enter the data entry code when creating an activity definition, the dataEntryCode field is mandatory and must be provided in the request body. It cannot be null or omitted. If this field is missing, the API will return a 400 Bad Request error. Please ensure you include dataEntryCode when required by your configuration.

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

Caution

There are some restrictions on the characters allowed in URL requests. See the fetching resources page for more information.

Success response

Returns 200 OK when an existing activity definition is updated, or 201 Created when a new activity definition is created.

Error responses

Status code	Description
400	Bad request. Validation failed, the external reference is invalid, or parent validation failed.
401	Unauthorized. The bearer token is missing, expired, or invalid.
404	Not found. The referenced activity definition does not exist and no external reference was specified for creation.

Examples

Create activity definition

Example creating an activity definition using custom external reference Cleaning:

PUT

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/b2347a7a-d60d-446f-b03b-7es2cc8c3281/levels/3/activity-definitions/Cleaning?externalReferences=(activity-definitions,CustomActivityReference)

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

PUT

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/b2347a7a-d60d-446f-b03b-7es2cc8c3281/levels/3/activity-definitions/20003?externalReferences=(activity-definitions,@data-entry-code)

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

PUT

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/b2347a7a-d60d-446f-b03b-7es2cc8c3281/levels/2/activity-definitions/Maintenance?externalReferences=(activity-definitions,CustomActivityReference)

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

PUT

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/b2347a7a-d60d-446f-b03b-7es2cc8c3281/levels/3/activity-definitions/122456?externalReferences=(activity-definitions,CustomActivityReference)

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

Create activity definition