Retrieve a list

Reference

Collections

People

Personal information

Retrieve a list

Returns a list of personal information, for all people or for the people selected by the person filter.

Tip

Check the Swagger page for more technical information on the endpoints.

Endpoint details

GET

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

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

Response properties

Field	Type	Required	Writable	Description
`id`	integer	—	Read-only	Internal unique identifier for the person.
`externalReferences`	object	—	Read-only	External references of the person, keyed by reference name. Returned only for the references requested with the `externalReferences` query parameter that have a value 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.

Filters

This list of filters can be used for this endpoint.

Filter	Type	Description
`person`	Optional	Internal person IDs (`person in (1, 2, 3)`), or the current members of circles (`person in circle(2, 8)`) or org-groups (`person in org-group(121, 122)`). When omitted, all people are returned.

Note

The person filter cannot be combined with delta. A request with both returns 400 Bad Request.
With a person filter, results are paged per 100 people. If the people matched by the filter change between pages (for example, a circle or org-group membership change), the next page returns 409 Conflict; restart from the first request.

Check the Fetching Resources page on how to use the filter.

To retrieve one person, use Retrieve a person.

External references

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

The following collections are supported for this endpoint:

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

The requested references are returned in the externalReferences property of each person. They do not select people: use the person filter for that.

Error responses

Status	Condition
`400`	Invalid filter value, invalid external reference, or a `person` filter combined with `delta`
`401`	Missing or invalid access token, or insufficient scope
`409`	The people matched by the `person` filter changed between pages
`414`	Request URI too long (continuation token)

Examples

Retrieve all people

Example to retrieve all people that have been configured in Protime:

GET

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

Retrieve the members of a circle

Example to retrieve the people that are currently members of circle 2:

GET

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/people?filter=person in circle(2)

Retrieve people with an external reference

Example to retrieve person 1234 with the custom reference sapNr:

GET

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/people?filter=person in (1234)&externalReferences=(people,sapNr)

{
  "value": [
    {
      "id": 1234,
      "externalReferences": {
        "sapNr": "Pers13"
      },
      "changeVersion": "0001DC350000B079001E",
      "lastName": "Doe",
      "firstName": "John",
      "inServiceDate": "2021-01-15",
      "employeeNumber": "EMP1234",
      "badgeNumber": "123456"
    }
  ]
}

Retrieve a person Retrieve a delta