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:

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 @.

Query format

Single external reference:

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

Multiple external references:

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

Multiple references may be requested for the same collection. Each requested reference is resolved independently and returned under that collection’s externalReferences object:

?externalReferences=(people,@badge-number)(people,@employee-number)

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

GET response with multiple references for one collection

When several references are requested for the same collection, the response returns all of them under that collection’s externalReferences object:

{
    "id": 39577408,
    "calculatedTimeOfDayInMinutes": 480,
    "isGenerated": false,
    "person": {
        "id": 123152,
        "externalReferences": {
            "@badge-number": "6767676",
            "@employee-number": "E-00421"
        }
    },
    "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.

How a custom reference is registered

A custom reference has to exist before it can be used to address a resource. There are two ways to create one:

The externalReferenceIdentifier property holds exactly one key-value pair and is honoured only on the create (POST) endpoint of those two collections — the corresponding update endpoints ignore it. See Create a person for the full behaviour.

Request format for addressing a related resource

Once a reference exists, use it in place of an id when a request body points at another resource. This form resolves the reference — it looks up the resource already linked to that value. It never creates or changes a reference.

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

These endpoints operate on custom references only. A reference name starting with @ is rejected with a 400.

Add or update a custom external reference

Scope: connector-protimeapi-external-references.write

Request body:

{
    "internalReference": "4781"
}

A successful response returns 200 OK.

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

Scope: connector-protimeapi-external-references.write

A successful response returns 204 No Content.

List the custom external references of a collection

Scope: connector-protimeapi-external-references.read

Returns 200 OK with every custom reference registered for the collection.

List the custom external references of one reference name

Scope: connector-protimeapi-external-references.read

Returns 200 OK with every value registered under that reference name.

Retrieve one custom external reference

Scope: connector-protimeapi-external-references.read

Returns 200 OK, or 404 Not Found when the value is not registered.

Error responses

Endpoint path segments

Uniqueness requirements

@ prefix convention

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

See also

• How to use external references
• External reference model