Retrieve a person

Returns a single personal information record by its internal ID or external reference.

Endpoint details

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/people/{PersonReference}

Headers: Authorization: Bearer {token}, User-Agent: {agent} Scope: connector-protimeapi-people.read

URL parameters

Parameter	Description
{PersonReference}	The internal ID or external reference of the person.

Response properties

Field	Type	Required	Writable	Description
id	integer	—	Read-only	Internal unique identifier for the person.
changeVersion	string	—	Read-only	Property to indicate the order of changes.
periodClosingDate	string	—	Read-only	Date of the period closing, used to lock the calendar.
hourlyRateCurrencyDefinition.id	integer	—	Read-only	Internal unique identifier for the hourly rate currency.
advanceCurrencyDefinition.id	integer	—	Read-only	Internal unique identifier for the advance currency.
lastName	string	Yes	Yes	Last name of the person.
firstName	string	Yes	Yes	First name of the person.
initials	string	—	Read-only	Initials of the person.
telephone	string	No	Yes	Telephone number.
mobile	string	No	Yes	Mobile phone number.
email	string	No	Yes	Email address.
address	string	No	Yes	Street address with the number.
postalCode	string	No	Yes	Postal code.
town	string	No	Yes	Town or city.
countryISOCode	string	No	Yes	ISO code of the country.
nationalityISOCode	string	No	Yes	ISO code of the nationality.
sex	string	No	Yes	Sex of the person (Unknown, Female, Male, Other).
maritalStatus	string	—	Read-only	Marital status (Unknown, Single, Married, Widow, Widower, Divorced, LivingTogether).
birthDate	string	No	Yes	Birth date of the person (YYYY-MM-DD).
placeOfBirth	string	—	Read-only	Place of birth.
drivingLicense	string	—	Read-only	Driving license number.
registerNumber	string	—	Read-only	Register number.
passportNumber	string	—	Read-only	Passport number.
socialSecurityNumber	string	—	Read-only	Social security number.
bankAccount	string	—	Read-only	Bank account number.
inServiceDate	string	Yes	Yes	Date when the person entered service (YYYY-MM-DD).
outOfServiceDate	string	No	Yes	Date when the person stopped service (YYYY-MM-DD). To infinity if empty.
wtdStartDate	string	—	Read-only	WTD start date (YYYY-MM-DD).
employeeNumber	string	No	Yes	Employee number.
payGroup	string	No	Yes	Pay group of the person.
hourlyRate	number	—	Read-only	Hourly rate.
maxAdvance	number	—	Read-only	Maximum advance allowed.
terminalGroup.id	integer	—	Read-only	Internal unique identifier for the terminal group the person is linked to.
badgeNumber	string	No	Yes	Badge number of the person. Needs to be unique.
pinCode	integer	—	Read-only	PIN code.
terminalLanguageISOCode	string	—	Read-only	ISO code of the terminal language for this person.

External references

The endpoint supports predefined and custom external references. See the external references page for details.

The following collections are supported for this endpoint:

Collection	Predefined	Custom
people	@badge-number, @employee-number	Supported

On this endpoint the reference only resolves {PersonReference}: the response does not include an externalReferences property. To retrieve the external references of a person, use the list endpoint with a person filter.

Error responses

Status	Condition
400	Invalid external reference key or value
401	Missing or invalid access token, or insufficient scope
404	Person with the given ID or external reference does not exist

Examples

Retrieving a person by internal ID

Example with internal ID 8526:

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

With predefined external reference - badge number

Example with badge number6526:

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/people/6526?externalReferences=(people,@badge-number)

With predefined external reference - employee number

Example with employee number 005325:

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/people/005325?externalReferences=(people,@employee-number)