Create a clocking

Introduction

You can create a clocking with the POST call.

Endpoint details

Body properties

This list of properties is applicable for this endpoint.

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.

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 schedule within Protime.

There are two scenarios for handling overnight clockings. In most cases, the standard approach is all you need.

Standard approach: let the schedule determine the day (recommended)

When the schedules in Protime are properly configured for night shifts, you only need to send clockings with the actual clock time expressed in normal minutes since midnight (0–1439). Protime will automatically determine the correct day each clocking belongs to, based on the schedule configuration.

This is the expected and recommended approach. Clients should send clockings with normal time values and rely on the schedule configuration to determine on which day the clocking will appear.

Example — Night shift with schedule configuration

A company has configured the day schedules so that a night shift starting on the evening of 13 February and ending the morning of 14 February is assigned to the day of 14 February.

An employee clocks in at 22:00 on 13 February and clocks out at 06:00 on 14 February.

You simply create two clockings:

1. A clocking on 2025-02-13 with timeOfDayInMinutes: 1320 (22:00)
2. A clocking on 2025-02-14 with timeOfDayInMinutes: 360 (06:00)

Protime will use the schedule configuration to determine that both clockings belong to the day of 14 February. You do not need to use any special negative or high values.

Override approach: explicitly control the day with extended time values

In rare cases, you may need to override the schedule configuration and explicitly place a clocking on a previous or next day. For this purpose, the timeOfDayInMinutes property supports values from -1440 up to 2880:

Examples

In/Out Clockings: “InOut”

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

{
  "person": {
    "externalReferences": {
      "@badge-number": "1955"
    }
  },
  "date": "2024-12-17",
  "timeOfDayInMinutes": 500,
  "kind": "InOut",
  "status": "Active"
}  

Reason clockings: “Reason”

Example for creating a reason clocking:

{
  "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:

{
    "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:

{
  "person": {
        "id": 76547
  },
  "date": "2024-12-17",
  "timeOfDayInMinutes": 480,
  "kind": "ActivityEnd",
  "status": "Active"
}  

Overnight clocking: night shift example

This example demonstrates the recommended standard approach for overnight clockings. The employee works a night shift from 22:00 on 13 February to 06:00 on 14 February. The schedule in Protime is configured so that this night shift belongs to 14 February.

You create the check-in clocking on 13 February with the actual time (22:00 = 1320 minutes):

{
  "person": {
    "externalReferences": {
      "@badge-number": "1955"
    }
  },
  "date": "2025-02-13",
  "timeOfDayInMinutes": 1320,
  "kind": "InOut",
  "status": "Active"
}

And the check-out clocking on 14 February with the actual time (06:00 = 360 minutes):

{
  "person": {
    "externalReferences": {
      "@badge-number": "1955"
    }
  },
  "date": "2025-02-14",
  "timeOfDayInMinutes": 360,
  "kind": "InOut",
  "status": "Active"
}

Protime will automatically assign both clockings to 14 February based on the schedule configuration. No special time values are needed.