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: the .read or .write scope of each collection you call, plus connector-protimeapi-external-references.write to register or delete a custom reference and connector-protimeapi-external-references.read to list or retrieve one.

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

You can also request several references for the same collection. Each one is returned under that collection’s externalReferences object:

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

{
  "id": 39577408,
  "person": {
    "id": 123152,
    "externalReferences": {
      "@badge-number": "6767676",
      "@employee-number": "E-00421"
    }
  },
  "date": "2024-01-05",
  "timeOfDayInMinutes": 480,
  "kind": "InOut"
}

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

The reference must already be registered for the correct person. This body resolves HRMID to a person — it does not assign HRMID to anyone. See the next two sections for registering one.

Register a custom reference while creating a person

The people and activity-definitions create endpoints accept an externalReferenceIdentifier body property, which registers the reference in the same call. This saves a round trip compared with the management endpoint below.

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

{
  "firstName": "John",
  "lastName": "Doe",
  "inServiceDate": "2021-01-15",
  "externalReferenceIdentifier": {
    "HRMID": "Emp123"
  }
}

The new person can afterwards be addressed as ?externalReferences=(people,HRMID).

The property holds exactly one key-value pair, and only the create endpoint honours it — PUT /people/{personReference} ignores it. See Create a person for the predefined-key behaviour and the error cases.

Manage custom external references

Create or update a custom external reference for a resource that already exists. 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"
}

Listing and deleting custom references is described in External references reference.

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