Concepts
External reference model

External reference model

Why external references exist

Every system in an integration landscape has its own way of identifying records. An HR platform assigns employee number E-4821, a badge system knows the same person as badge 6767676, and Protime stores that person with internal ID 123152. When these systems exchange data, each needs a way to say “I mean that person” using terminology the other side understands.

Without a bridging mechanism, integrators are forced to maintain a separate mapping table that translates between their identifiers and Protime’s internal IDs. That table must be kept in sync, adds a point of failure, and complicates every API call. The external reference model eliminates this burden by embedding the ID mapping directly into the API.

How the model works 

  flowchart LR
    A["External System ID<br/>(e.g. E-4821)"] <-->|"External<br/>Reference"| B["Protime API<br/>Connector"]
    B <-->|"Internal ID<br/>(e.g. 123152)"| C["Protime Platform"]
    style B fill:#f0f4ff,stroke:#3366cc,stroke-width:2px

An external reference associates an external identifier with a Protime internal identifier for a resource within a specific collection. Once this association exists, the external identifier can be used in place of the Protime ID in both read and write operations, making the API feel native to the integrating system.

Two types of external references

The model distinguishes between two categories based on where the identifier originates.

Predefined external references

Predefined references expose fields that already exist within the Protime software suite. They are identified by the @ prefix in their name. Examples include:

Collection Predefined reference Protime field
people @badge-number Badge number linked to the person
people @employee-number Employee number in Protime
activity-definitions @data-entry-code Data entry code of the activity
activity-definitions @external-reference External reference field on the activity
absence-definitions @absence-code Absence code in Protime
counter-definitions @counter-code Counter code in Protime
shift-definitions @shift-code Shift code in Protime
terminals @external-code External code of the terminal

Because these fields are managed inside Protime (typically by a functional administrator), they are available to all API consumers without any setup beyond knowing the reference name.

Custom external references

Custom references allow an integrator to attach its own identifiers to Protime resources. The integrator chooses a reference name (for example, HRMID) and assigns a reference value (for example, Emp123) to a specific Protime resource. The mapping is created and managed entirely through the API.

Key characteristics of custom references:

  • The reference name is freely chosen by the integrator and does not use the @ prefix.
  • Custom references are visible only through the API; they do not appear anywhere in the Protime user interface.
  • They are managed via dedicated PUT and DELETE endpoints under /external-references/.

Custom references are particularly useful when the Protime resource has no pre-existing field that matches the external system’s identifier – for instance, when an HRM platform needs to link its own employee ID to a Protime person.

Uniqueness and coverage requirements

For external references to function reliably as identifiers, two properties must hold:

  1. Uniqueness – within a given collection and reference name, each reference value must point to exactly one resource. If two people share the same badge number, the API cannot unambiguously resolve a request that uses @badge-number to identify a person.
  2. Coverage – ideally, every resource in the collection should carry a value for the chosen reference. A person without a badge number will be unreachable via @badge-number, which can cause silent gaps in synchronization.

Neither constraint is technically enforced as a hard error, but violating them undermines the purpose of external references and can lead to unexpected behavior.

Where external references apply

External references participate in three categories of API operations:

  • Reading – an integrator can request that responses include external identifiers alongside internal IDs, so that the consuming system can correlate records without a separate lookup.
  • Writing – when creating or updating a resource that references another resource, external references allow the integrator to identify that related resource using its own identifier rather than the Protime internal ID.
  • Managing – custom external reference mappings are created, updated, and removed through dedicated management endpoints.

For query syntax, endpoint details, and concrete examples, see Use external references and External references reference.

Predefined vs. custom – choosing the right type

Consideration Predefined (@) Custom
Source of truth Protime (managed by administrators) External system (managed by the integrator)
Setup required None – field already exists in Protime Integrator must create mappings via the API
Visibility in Protime UI Yes – the underlying field is visible No – API-only
Best for Leveraging identifiers that Protime already knows Attaching foreign keys from an external system

In practice, many integrations use both types: predefined references for fields that are naturally maintained in Protime (badge numbers, absence codes) and custom references for identifiers that originate outside Protime (HRM employee IDs, ERP cost-center codes).

Further reading

Activity structure modelMulti-tenancy