How-to Guides
Fetch resources

Fetch resources

This guide explains how to retrieve data from the Protime API using filters, pagination, and expand parameters.

Before you begin

  • Obtain a valid access token. See Authenticate.
  • Know the collection you want to query (e.g. clockings, people). See Collections reference for the full list.
  • Required scopes: a .read scope for the target collection (e.g. connector-protimeapi-clockings.read).

Construct a filtered GET request

Most list requests require at least one filter. Omitting a required filter returns a 400 Bad Request. Some collections (e.g. departments, employers) do not require filters.

GET /connector/protimeapi/api/v1/<resource-collection>?filter=<filter-expression> HTTP/1.1
Host: <tenant>.myprotime.eu
Authorization: Bearer eyJ...Uc
User-Agent: YourService/v1 (YourCompany)

Combine multiple filter conditions with and:

GET /connector/protimeapi/api/v1/clockings?filter=person%20in%20(1,2,3)%20and%20date%20ge%20'2024-01-01'%20and%20date%20le%20'2024-01-05' HTTP/1.1
Host: <tenant>.myprotime.eu
Filter as narrowly as possible. The API enforces rate limiting on excessively broad requests. See Filtering reference for all supported operators.

Paginate through results

The API returns large result sets in pages. Each page may include a nextLink pointing to the next page.

  1. Send your initial GET request.
  2. Check the response for a nextLink property.
  3. If nextLink is present, send a GET to that URL to retrieve the next page.
  4. Repeat until the response no longer contains a nextLink.
A page with an empty value array does not mean the end of the data. Always check for the presence of nextLink to determine whether more pages remain.

Example – first request:

GET /connector/protimeapi/api/v1/clockings?filter=person%20in%20circle%20(1,2,3)%20and%20date%20ge%20'2024-01-01'%20and%20date%20le%20'2024-12-31' HTTP/1.1
Host: <tenant>.myprotime.eu

Response:

{
  "value": [
    {
      "id": 21369,
      "calculatedTimeOfDayInMinutes": 480,
      "isGenerated": true,
      "person": { "id": 1 },
      "date": "2024-01-02",
      "timeOfDayInMinutes": 480,
      "kind": "InOut"
    }
  ],
  "nextLink": "/connector/protimeapi/api/v1/clockings?filter=person in circle (1,2,3) and date ge '2024-01-01' and date le '2024-12-31'&continuationToken=eyJ2YWxpZGF0..."
}

Send a GET to the nextLink URL and continue until no nextLink is returned.

Use the expand parameter

Some GET endpoints support the expand query parameter to include related data in the response.

Append ?expand=<field> (or &expand=<field> if other query parameters are already present):

GET /connector/protimeapi/api/v1/activity-structure-versions/<versionId>/levels/3/activity-definitions/<definitionId>?expand=usages,restrictions HTTP/1.1
Host: <tenant>.myprotime.eu

Check the Swagger page for each endpoint to see which expand values are available.

Related

AuthenticateCreate, update, and delete resources