External references

General information

Protime API identifies resources from our software with IDs. To make it easier to work for external parties, Protime API offers the possibility to allocate an “external reference” onto certain resources. This will allow your integration to address a resource with your own system’s identification.

Firstly a distinction has to be made between two types. When using external references, the difference between the two types is made with an “@"-symbol.

• Predefined external references: selected properties within our Protime software suite (stated by the “@"-symbol when used in this API).
• Custom external references: fully flexible key-value pairs, managed by the 3rd party.

When fetching resources with the corresponding external references, it can be done by adding a filter to the endpoint.
Example to request an external reference:
https://<endpoint>?externalReferences=({collection},{external reference}) \

When manipulating resources and using an externalReference, use the format of an externalReference.

{
	"{property}":{
		"externalReferences":{
			"{external reference}":"ExternalReferenceX"
		}
	}
}

External reference types

Predefined external references

Within the Protime environment, many domain resources can carry various identification fields. We expose them via the “predefined external references” system. To discover all the fields exposed as predefined external reference, take a look at the external reference options page.

A predefined external reference will start with “@” in its name. E.g. “@badge-number” will refer to the badge number field that is linked to a person in Protime.

Predefined external reference - GET
When fetching data, it is possible to get the data with the corresponding external references (predefined and custom references). A referenceType can be chosen per managed collection by adding an “externalReferences”-filter to the endpoint. Here states the same rule: use for predefined references the “@"-symbol.

Example to request a badge number:
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings/{clockingId}?externalReferences=(people,@badge-number)

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

When multiple collections are needed with external references, just expand the list with all the external references like in the example below.
Example with multiple external references:
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings/{clockingId}?externalReferences=(people,@badge-number)(activity-definitions,@data-entry-code)

Predefined external references options

Replace collection and external reference with the appropriate values from the table below. Note that the predefined external reference should always be prefixed with an @ symbol.

Example to request an employee number in the clockings collection:
GET https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings?externalReferences=(people,@employee-number)&filter=people in (1,2,3) and date ge '2024-01-01' and date le '2024-01-05'
Example to request multiple predefined external references:
GET https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-durations?filter=date ge '2025-01-01' and date le '2025-01-05' &externalReferences=(people,@employee-number)(activity-definitions,@data-entry-code)(absence-definitions,@absence-code)(counter-definitions,@counter-code)

Predefined external reference - POST
Let’s take an example where people are using their own badge number on a device that is controlled by a 3rd party. These clockings need to be sent to Protime.

The badge number must be configured to the correct person in the Protime system to be able to create this clocking using the predefined reference @badge-number.

Example to post a clocking based on the badge number:

// POST https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings
{
	"person":{
		"externalReferences":{
			"@badge-number":"6767676"
		}
	},
	"date":"2024-01-05",
	"timeOfDayInMinutes":480,
	"kind":"InOut"
}

Custom external references

Custom external references allow partners to assign their own identifier to a resource that is known within our software. If a resource (person, activity, absence, …) has a specific identifier in your environment, the external references system can be used to allocate that identifier to our resource.

An external reference has a reference name and a reference value linked to the identifier of our resource. The reference name will be the way to address the specific collection of external references you want to target. The reference value or “externalReference” will be the value of your own identifier.

There can only be one reference value linked to one of our resources for one reference name.

These custom external references are only known when using the Protime API and remain unknown throughout the rest of Protime.

Managing custom external references
Let’s say an HRM system is managing the employees for your company. A person is hired and has to be created in Protime. Since a lot of the integrations will be done via this HRM system, it is desired that the person identifier from the HRM system is linked to the Protime person. Future integrations can address this resource using the HRM identifier.

As seen in Manipulating-resources, whenever a resource has been created, the response will provide a link to the new resource with its Protime identifier. This request can then be followed up with an add or update external reference call.

The name of the reference can be freely chosen. Let’s call the name of the reference group “HRMID”. The new person will receive the HRMID “Emp123”. This unique reference must be linked to the internal identifier (or system number) Protime generates for this person, this is called the internal reference.

Example to create a custom external reference:

// PUT https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/external-references/people/HRMID/Emp123
{
	"internalReference":"4781"
}

More endpoints to manage custom external references can be found in Swagger.

Custom external reference example - GET
When fetching data, it is possible to get the data with the corresponding external references (predefined and custom references). A referenceType can be chosen per managed collection by adding an “externalReferences”-filter to the endpoint. Here states the same rule: use for custom external references the name chosen earlier (without ‘@’-symbol).

Example to request a custom external reference:
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings/{clockingId}?externalReferences=(people,HRMID)

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

When multiple collections are needed with external references, just expand the list with all the external references like in the example below. \

Example to request multiple external references in a GET endpoint:
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings/{clockingId}?externalReferences=(people,HRMID)(activity-definitions,ORDER123)

Custom external reference example - POST
Let’s take an example where clockings are imported using the people HRM identifier. These clockings need to be sent to Protime. Addressing the resource using the custom external reference in a POST, make sure no ‘@’-symbol is used in the beginning.

Example to use a custom external reference in a POST endpoint:

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