Use external references

This guide shows how to use external references to address Protime resources with your own system’s identifiers instead of internal Protime IDs.

Before you begin

• Obtain a valid access token. See Authenticate.
• Understand the difference between predefined (@-prefixed) and custom external references. See External reference model for background.
• Required scopes: .read or .write scopes for the target collections and connector-protimeapi-external-references.write for managing custom references.

Fetch resources with a predefined external reference

Add the externalReferences query parameter to any GET request. Predefined references use the @ prefix.

GET /connector/protimeapi/api/v1/clockings/{clockingId}?externalReferences=(people,@badge-number) HTTP/1.1
Host: <tenant>.myprotime.eu
Authorization: Bearer eyJ...Uc

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

See External references reference for all available predefined reference options.

Fetch resources with a custom external reference

Custom external references use the reference name you chose when creating them – without the @ prefix.

GET /connector/protimeapi/api/v1/clockings/{clockingId}?externalReferences=(people,HRMID) HTTP/1.1
Host: <tenant>.myprotime.eu
Authorization: Bearer eyJ...Uc

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

Use multiple external references in one request

Append additional (collection,reference) pairs to the query parameter:

GET /connector/protimeapi/api/v1/clockings/{clockingId}?externalReferences=(people,@badge-number)(activity-definitions,@data-entry-code) HTTP/1.1
Host: <tenant>.myprotime.eu

Create a resource using a predefined reference

Replace the id field with an externalReferences object in the POST body. Use the @ prefix for predefined references.

POST /connector/protimeapi/api/v1/clockings HTTP/1.1
Host: <tenant>.myprotime.eu
Authorization: Bearer eyJ...Uc
Content-Type: application/json

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

The badge number must already be configured for the correct person in Protime.

Create a resource using a custom reference

Use the custom reference name without the @ prefix.

POST /connector/protimeapi/api/v1/clockings HTTP/1.1
Host: <tenant>.myprotime.eu
Authorization: Bearer eyJ...Uc
Content-Type: application/json

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

Manage custom external references

Create or update a custom external reference using the external-references endpoint. The URL path contains the collection name, your chosen reference name, and the external reference value. The body maps it to the internal Protime ID.

Host: <tenant>.myprotime.eu
Authorization: Bearer eyJ...Uc
Content-Type: application/json

{
  "internalReference": "4781"
}

Additional management endpoints (list, delete) are available in the Swagger UI.

Related

• External references reference – predefined reference options table and forbidden URL characters
• External reference model – how predefined and custom references work
• Create, update, and delete resources – general POST, PUT, and DELETE patterns