Clockings

Introduction

The Protime API supports the following kinds of clockings:

  • In/Out Clockings
  • Reason Clockings
  • Activity Clockings
  • End Activity Clockings

Please refer to the access clockings page when you are looking for that collection of data!

Properties

Property Type Description
id integer Unique identifier for the clocking.
person.id integer Internal ID of the person who performed the clocking.
date string Date of the clocking (YYYY-MM-DD).
timeOfDayInMinutes integer Minutes since midnight (0-1439) representing the time of the clocking on the specified date.
originalTimeOfDayInMinutes integer Original time of the clocking as registered by the terminal or input source. Only present if the clocking has been edited.
calculatedTimeOfDayInMinutes integer The time of day in minutes after any corrections or calculations.
isGenerated boolean Indicates if the clocking was generated by the system.
terminal.id integer Internal ID of the terminal on which the clocking occurred.
geolocation.longitude number Longitude coordinate where the clocking was registered.
geolocation.latitude number Latitude coordinate where the clocking was registered.
kind string Type of clocking (InOut, Reason, Activity, ActivityEnd).
reason.id integer Internal ID of the reason for the clocking (only present if kind is Reason).
activityLevels array Array of activity levels, each with a level and an activityDefinition.id (only present if kind is Activity).
status string Status of the clocking (Unknown, Active, Deleted).

External references

It’s possible to use predefined external references and custom external references. More information can be found on the External References Page

For a list of predefined external references, see the external reference options section.

Example with an employee number:
GET https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings?filter=person in (1,2,3) and date ge '2024-01-01' and date le '2024-01-05' and kind eq 'InOut'&externalReferences=(people,@employee-number)

Endpoints

Below you can find the supported endpoints for this data collection.

GET a clocking by Id

You can retrieve a clocking by the internal ID using the GET call. The IDs are available in the location header after a successful POST call for creating a clocking.

GET https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings/{id}

  • <id>
    • The Id’s are available in the location header after a successful POST call

GET a list of clockings

You can retrieve a list of clockings using a filter.

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

Filter requirements

Example with people, employee number and InOut clockings:
GET https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings?filter=person in (1,2,3) and date ge '2024-01-01' and date le '2024-01-05' and kind eq 'InOut' &externalReferences=(people,@employee-number)

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

Delta

It’s possible to retrieve changes with the delta. Check the Delta page how to use this.

Filter requirements when using the delta

Example for clockings with a delta:
GET https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings?filter=date ge '2025-01-01'&externalReferences=(people,@employee-number)&delta

Webhooks

It’s possible to retrieve change-events with webhooks. Check the Webhooks page how to use this.

POST a clocking

You can create a clocking with the POST call.

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

Overnight clockings

The Protime API supports handling overnight clockings. Clocking data is imported on the correct day, based on the configuration of the day program within Protime.

Kinds

Following clocking kinds can be chosen:

In/Out Clockings: “InOut”

Example for creating an in/out clocking with badge number:

// POST https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings
{
  "person": {
    "externalReferences": {
      "@badge-number": "1955"
    }
  },
  "date": "2024-12-17",
  "timeOfDayInMinutes": 500,
  "kind": "InOut",
  "status": "Active"
}
Reason clockings: “Reason”

Example for creating a reason clocking:

// POST https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings
{
  "person": {
        "id": 76547
  },
  "date": "2024-12-17",
  "timeOfDayInMinutes": 500,
  "kind": "Reason": {
        "id": 6578
    },
  "status": "Active"
}
Activity clockings: “Activity”

When creating an activity clocking, a structure version is not required, as the Protime API automatically selects the active structure version.

Example for creating an activity clocking with external references on an employee number, a terminal and an activity definition:

// POST https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings
{
    "person": {
        "externalReferences": {
            "@employee-number": "01256"
        }
    },
    "date": "2024-01-05",
    "timeOfDayInMinutes": 480,
    "terminal": {
        "externalReferences": {
            "SapTerminalCode": "SAPTO1"
        }
    },
    "geolocation": {
        "longitude": "51.144127",
        "latitude": "4.392225"
    },
    "kind": "Activity",
    "activityLevels": [
        {
            "level": 1,
            "activityDefinition": {
                "externalReferences": {
                    "@data-entry-code": "00014"
                }
            }
        },
        {
            "level": 2,
            "activityDefinition": {
                "externalReferences": {
                    "@data-entry-code": "10019"
                }
            }
        }
    ],
    "status": "Active"
}
End activity clockings: “ActivityEnd”

An activity definition isn’t required. It will end the active activity clocking.

Example for ending an activity:

// POST https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings
{
  "person": {
        "id": 76547

  },
  "date": "2024-12-17",
  "timeOfDayInMinutes": 480,
  "kind": "ActivityEnd",
  "status": "Active"
}

Special case

Soft-deleted clockings

When a clocking from a physical terminal is manually deleted by a user, the record is not physically removed from the system. Instead, it is marked with a "Deleted" status, representing a soft delete. This allows the clocking to remain visible (e.g., shown with strikethrough styling in Protime), while being functionally invalid.

In webhooks or delta’s, soft-deleted records appear as:

  • "changeType": "InsertOrUpdate" indicating whether the record was added or updated (InsertOrUpdate) or physically deleted (Delete).
  • "status": "Deleted" indicating whether a clocking is active or soft-deleted.

Example of a soft-delete:

{
  "changeType": "InsertOrUpdate",
  "data": {
    "status": "Deleted",
    "timeOfDayInMinutes": 9999,
    "originalTimeOfDayInMinutes": 551,
    "date": "2025-04-22",
    "kind": "InOut",
    "terminal": {
        "id": 684743
    },
    //...
  }
}