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",
    "orquestId": 0,
    "error": "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.

  • orquestId: internal identifier of the consolidated clockguard in Orquest. This field is not required, as it is automatically generated by the system.

  • error: error message related to the record, if applicable.

Request example

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

[
  {
    "employeeId": "1006357",
    "locationId": "04",
    "clockguardType": "WORK",
    "recordType": "IN",
    "date": "2024-06-15T09:00:00Z",
    "lat": 37.389091,
    "lon": -5.984459,
    "device": "12345",
    "error": "No error"
  },
  {
    "employeeId": "1006357",
    "locationId": "04",
    "clockguardType": "WORK",
    "recordType": "OUT",
    "date": "2024-06-15T14:00:00Z",
    "lat": 37.389091,
    "lon": -5.984459,
    "device": "12345",
    "error": "No error"
  }
]

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.

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

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

If the time or date format is incorrect, the request will return a 400 Bad Request error.

If the specified employee ID is incorrect, the request will return a 400 Bad Request error.

If the clockguardType field is not defined with the correct values, the request will return a 406 Not Acceptable error, with the message must match "(OTHER|REST|WORK)".

If the recordType field is not defined with the correct values, the request will return a 406 Not Acceptable error, with the message must match "(IN|OUT)".

Useful links

What is a clockguard?

How to integrate clockguards?