Reference
External references

External references

This page documents the external references specification for the Protime API, including predefined reference options, custom reference format, management endpoints, and uniqueness requirements.

External reference types

The Protime API supports two types of external references, distinguished by the @ prefix:

Type Prefix Description
Predefined @ Selected properties within the Protime software suite, read-only via the API.
Custom None Flexible key-value pairs managed entirely by the third party.

Predefined external references options

Replace collection and external reference in the query parameter with the appropriate values from the table below. Predefined external references are always prefixed with @.

Collection Identifier External reference Query parameter
absence-definitions Absence Code @absence-code ?externalReferences=(absence-definitions,@absence-code)
activity-definitions Data Entry Code @data-entry-code ?externalReferences=(activity-definitions,@data-entry-code)
External Reference @external-reference ?externalReferences=(activity-definitions,@external-reference)
counter-definitions Counter Code @counter-code ?externalReferences=(counter-definitions,@counter-code)
people Badge Number @badge-number ?externalReferences=(people,@badge-number)
Employee Number @employee-number ?externalReferences=(people,@employee-number)
shift-definitions Shift Code @shift-code ?externalReferences=(shift-definitions,@shift-code)
terminals External Code @external-code ?externalReferences=(terminals,@external-code)

Query format

Single external reference:

?externalReferences=({collection},{external reference})

Multiple external references:

?externalReferences=({collection1},{reference1})({collection2},{reference2})

Example – requesting multiple predefined external references:

GET /connector/protimeapi/api/v1/activity-durations?filter=date%20ge%20'2025-01-01'%20and%20date%20le%20'2025-01-05'&externalReferences=(people,@employee-number)(activity-definitions,@data-entry-code)(absence-definitions,@absence-code)(counter-definitions,@counter-code) HTTP/1.1
Host: <tenant>.myprotime.eu

GET response with predefined external reference 

{
    "id": 39577408,
    "calculatedTimeOfDayInMinutes": 480,
    "isGenerated": false,
    "person": {
        "id": 123152,
        "externalReferences": {
            "@badge-number": "6767676"
        }
    },
    "date": "2024-01-05",
    "timeOfDayInMinutes": 480,
    "kind": "InOut"
}

POST/PUT body with predefined external reference 

{
    "person": {
        "externalReferences": {
            "@badge-number": "6767676"
        }
    },
    "date": "2024-01-05",
    "timeOfDayInMinutes": 480,
    "kind": "InOut"
}

Custom external references

Custom external references allow third parties to assign their own identifier to a Protime resource. A custom external reference has a reference name (freely chosen, without @) and a reference value (the external identifier).

There can only be one reference value linked to one Protime resource per reference name.

Custom external references are only known within the Protime API and are not visible elsewhere in the Protime software.

Request format for manipulating resources 

{
    "{property}": {
        "externalReferences": {
            "{external reference}": "ExternalReferenceX"
        }
    }
}

GET response with custom external reference 

{
    "id": 39577408,
    "calculatedTimeOfDayInMinutes": 480,
    "isGenerated": false,
    "person": {
        "id": 123152,
        "externalReferences": {
            "HRMID": "6767676"
        }
    },
    "date": "2024-01-05",
    "timeOfDayInMinutes": 480,
    "kind": "InOut"
}

POST body with custom external reference 

{
    "person": {
        "externalReferences": {
            "HRMID": "Emp123"
        }
    },
    "date": "2024-01-05",
    "timeOfDayInMinutes": 480,
    "kind": "InOut"
}

External reference management endpoints

Add or update a custom external reference

PUT
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/external-references/{collectionName}/{referenceName}/{externalReference}

Request body:

{
    "internalReference": "4781"
}

This links the external reference value ({externalReference}) to the Protime internal identifier (internalReference) within the specified collection and reference name.

Delete a custom external reference

DELETE
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/external-references/{collectionName}/{referenceName}/{externalReference}

Endpoint path segments

Segment Description
{collectionName} The collection the external reference belongs to (e.g. people)
{referenceName} The name of the reference group (e.g. HRMID)
{externalReference} The external reference value (e.g. Emp123)

Uniqueness requirements

Within a collection, external reference values (both predefined and custom) must be unique per reference name. If an identifier is not unique, its purpose as an identification reference is lost.

Additionally, every object in the collection should have a value for the external reference. Objects with empty values will not fail, but the external reference system cannot provide references consistently and accurately for those objects.

@ prefix convention

  • Predefined external references always start with @ (e.g. @badge-number).
  • Custom external references never start with @ (e.g. HRMID).

See also

Webhooks