Concepts
Architecture overview

Architecture overview

Why does the connector exist?

Workforce management platforms accumulate deeply interconnected data – clockings, absences, calculated totals, contracts, activity definitions – that external systems frequently need to consume or update. Exposing the internal data model directly would couple every integrator to implementation details that change with each product release, creating a maintenance burden on both sides.

The Protime API Connector solves this problem by presenting a stable, versioned REST API layer between external integrators and the Protime workforce management suite. It translates domain operations into a consistent set of HTTP resources with predictable URIs, authentication, filtering, pagination, and change-tracking semantics, regardless of how the underlying platform evolves.

Connector role

The connector acts as the single integration surface for the Protime platform. All reads and writes from third-party systems flow through it, which provides several advantages:

  • Version stability – the API version is embedded in the URI (/api/v1/), and the team evolves the contract in a backwards-compatible way.
  • Tenant isolation – every request is scoped to exactly one tenant; the connector enforces this automatically.
  • Uniform conventions – resource names use kebab-casing, collections are plural nouns, and standard HTTP verbs map to CRUD operations.
  flowchart LR
    A["External Integrator"] -->|"HTTPS / REST"| B["Protime API Connector"]
    B -->|"Internal protocols"| C["Protime Platform"]
    style B fill:#f0f4ff,stroke:#3366cc,stroke-width:2px

The integrator never communicates with the Protime platform directly. The connector handles authentication verification, scope enforcement, request validation, pagination, delta tracking, and webhook dispatch on behalf of the platform.

Domain slices

The API surface is organized into domain slices, each grouping logically related collections.

Domain Collections Typical use cases
Time clockings, absences, absence-definitions, absence-groups, breaks, break-definitions, work-interruptions, calculated-totals, paid-presences, counters, counter-definitions, counter-groups, shift-definitions Import/export clockings, synchronize absence calendars, read payroll totals
Activities activity-definitions, activity-durations, activity-usages, activity-restrictions Map cost-center or project codes to Protime activities
People people, contracts, department-histories, employer-histories, job-histories, job-category-histories, sector-histories, work-location-histories Synchronize HR master data, track contract changes
Foundation departments, employers, jobs, job-categories, sectors, work-locations Maintain organizational structure references
Planning assignments Read or write shift assignments
Access access-clockings Retrieve badge swipes from physical access points

Most collections follow a common URI pattern:

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/<collection>

For example, retrieving clockings for a tenant called acme:

https://acme.myprotime.eu/connector/protimeapi/api/v1/clockings?filter=date ge '2026-01-01'

Some resources in the Activities domain use nested paths that reflect their hierarchical structure. See the collections reference for precise URI details.

Cross-cutting concerns

Three mechanisms cut across all domain slices:

Delta (change tracking)

Rather than re-fetching entire collections, integrators can request only what has changed since their last synchronization. The delta mechanism provides cursor-based change tracking with InsertOrUpdate and Delete change types. This dramatically reduces data volume and processing time for ongoing integrations.

Webhooks (event delivery)

For scenarios where near-real-time awareness of changes is required, the connector can push events to a consumer-provided HTTPS endpoint whenever a resource in a subscribed collection changes. Webhooks complement delta by eliminating the need to poll.

External references (ID mapping)

External systems rarely share Protime’s internal identifiers. The external reference system allows integrators to map their own IDs – whether predefined fields already in Protime (prefixed with @, such as @badge-number) or fully custom key-value pairs – onto Protime resources. This mapping can then be used in both read and write operations, removing the need for the integrator to maintain a separate translation table.

Further reading

Delta synchronization