Collections
Clockings
Create a clocking

Create a clocking

Introduction

You can create a clocking with the POST call.

Tip

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

Endpoint details

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

Body properties

This list of properties is applicable for this endpoint.

Property Type Description
person.id integer Internal ID of the person who performed the clocking.
person.externalReferences object External references for the person (e.g., badge number, employee number).
date string Date of the clocking (YYYY-MM-DD).
timeOfDayInMinutes integer Minutes since midnight (-1440 and 2880) representing the time of the clocking.
terminal.id integer Internal ID of the terminal on which the clocking occurred.
terminal.externalReferences object External references for the terminal.
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 for Reason kind).
activityLevels array Array of activity levels (only for Activity kind).
status string Status of the clocking (Active).

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.

Note

Check the query options below the endpoint on the Swagger page for the relevant external references.

Good to know

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.

Note

The timeOfDayInMinutes property supports values from -1440 up to 2880. This allows you to register clockings that occur before midnight (previous day) or after midnight (next day), which is especially useful for night shifts and overnight clockings.

Examples

In/Out Clockings: “InOut”

Example for creating an in/out clocking with badge number as the external reference:

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",
  "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 the person, the terminal and the 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 here; this will end the activity clocking that is currently active.

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"
}
Retrieve a clocking