Create a clocking

Creates a new clocking record.

Endpoint details

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

Body properties

External references

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

The following collections are supported for this endpoint:

Error responses

Success response

201 Created with a Location header pointing to the new clocking.

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"
}  

Reason clockings: “Reason”

Example for creating a reason clocking:

{
  "person": {
        "id": 76547
  },
  "date": "2024-12-17",
  "timeOfDayInMinutes": 500,
  "kind": "Reason",
  "reason": {
        "id": 6578
    }
}  

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"
                }
            }
        }
    ]
}

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"
}  

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"
}

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"
}

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