Add a list of clockguards

This endpoint allows registering a collection of non-null clockguards.

POST /api/v1/import/business/{businessId}/clockguardrecords

Below is an explanation of each field in the request body.

Mandatory fields are marked with an asterisk (*).

Request body

JSON Analysis 
[
  {
    "employeeId": "string",
    "locationId": "string",
    "clockguardType": "string",
    "recordType": "string",
    "date": "string",
    "lat": 0,
    "lon": 0,
    "device": "string",
    "zoneId": "string"
  }
]
Details

  • employeeId*: identifier of the employee linked with the record.

  • locationId: identifier of the task where the record is made, if applicable.

  • clockguardType*: type of activity being recorded. The accepted values for this field are WORK, REST, and OTHER.

  • recordType*: type of record being made. The accepted values for this field are IN and OUT.

  • date*: date and time when the record is made, in UTC and in the format yyyy-MM-ddTHH:mm:ss.SSSZ.

  • lat: geographic latitude from where the record is sent. It can be null.

  • lon: geographic longitude from where the record is sent. It can be null.

  • device: identifier of the clock-in device.

  • zoneId: external identifier of the zone. If the specified zone does not exist, the record will be saved with a task, but without a zone, so it cannot be returned later in clockguards requests.

Request example

After analyzing the different fields, an example of the request body is shown:

[
    {
        "employeeId": "1006357",
        "clockguardType": "WORK",
        "recordType": "IN",
        "date": "2026-04-09T08:00:00.000Z",
        "locationId": "02",
        "zoneId": "ZG"
    },
    {
        "employeeId": "1006357",
        "clockguardType": "WORK",
        "recordType": "OUT",
        "date": "2026-04-09T15:00:00.000Z",
        "locationId": "02",
        "zoneId": "ZG"
    }
]

If the request is successful, the response will return a 200 OK status with a breakdown of the records that were registered in the system.

The level of detail in the response will depend on the data sent in the request and the business configuration. For instance, if the business has automatic clock-in consolidation enabled, the response will contain the internal identifier of the consolidated record (orquestId).

Considerations

Timestamps must be sent in UTC, and publication is done according to the service’s time zone.

The maximum number of elements allowed in this request is 4000.

Records sent through the API may appear in the system either as clockguard records or as consolidated clockguards. This behavior depends on the business configuration (Configuration parameters) and changing it requires consultation with the Orquest team.

If any of the records in the request contain errors, the request will still return a 200 OK status, including the type of error in the response:

  • If the record is duplicated with a previous one: clock_guard_duplicated. In this case, the record is not persisted.

  • If the checkout record cannot be matched with a previous check-in: error.previous_checkin_not_found.

  • If the specified employee identifier does not exist in the business: error.business_employee_not_found.

  • If the clockguard was made outside the distance radius allowed for the location: clock_guard_distance_restricted.

The system allows sending overlapping records: they will be stored and displayed exactly as they were included in the request.

If the record corresponds to a day marked as a day off for the employee, it is discarded without indicating any error in the response: the returned element will have orquestId and error set to null.

If no zone (zoneId) is specified, the clocking will be recorded for the specified task (locationId) in the General zone.

If the specified task (locationId) or zone (zoneId) does not match those in the system, the clocking will be recorded without an associated task.

Error codes

In addition to the common errors, this endpoint can return the following codes:

Code Message Description

400 Bad Request

-

The date format (date) of one or more records is not valid. It is recommended to use the yyyy-MM-ddTHH:mm:ss.SSSZ format.

406 Not Acceptable

The employee id cannot be null

The employeeId field is missing in one or more records.

Clockguard type cannot be null

The clockguardType field is missing in one or more records.

Record type cannot be null

The recordType field is missing in one or more records.

Date cannot be null

The date field is missing in one or more records.

must match "(OTHER|REST|WORK)"

The clockguardType field does not have one of the accepted values (WORK, REST, OTHER).

must match "(IN|OUT)"

The recordType field does not have one of the accepted values (IN, OUT).

-

The collection sent exceeds the allowed limit of 4000 elements. It is recommended to split the request into smaller batches.

409 Conflict

-

A conflict occurred while saving one or more records. It is recommended to check that the data sent does not violate any integrity constraint.

Useful links

What is a clockguard?

How to integrate clockguards?