Introduction
This guide is aimed at helping you send the clock-ins and clock-outs of your own punch clock to Lucca Timesheet. Lucca Timesheet then computes the worked time of your employees from these time-punches, as it does for time-punches made on a Lucca punch clock.Prerequisites
You will need:- Your domain name
{yourDomain}, eg: “https://myawesomecompany.ilucca.net”. - An API key
{apiKey}with the “Edit time-punches” permission on all departments (see step 1). - Employees on a clock-in time-tracking profile.
- The Lucca identifier of each employee who clocks in and out on your punch clock (see step 2).
Guide
1. Create an API key
In your Lucca account settings, create a new API key dedicated to your punch clock integration. Then, in the role of this API key (listed at the very bottom of the roles administration page, under the same name as the key), grant the “Edit time-punches” permission (“Modifier les pointages” in French) in Lucca Timesheet, on all departments, so that the key can send time-punches for any employee. Learn more about API keys and how to use them on the Authentication page.2. Map your punch clock identifiers to Lucca employees
Your punch clock identifies employees with its own identifiers: badge identifiers, personal PIN codes, logins, etc. Lucca identifies them with their Lucca employee identifier, and each time-punch you send must reference it. Your integration must therefore maintain a mapping between the identifiers of your punch clock and the identifiers of Lucca employees. When an employee clocks in or out, use this mapping to tell Lucca which employee the time-punch belongs to. Lucca employees and their identifiers can be retrieved through the users API.3. Send each time-punch
Each time an employee clocks in or out, send a POST request to the/timmi-timesheet/api/time-punches endpoint.
Please refer to the API reference.
employee:{ "id": ... }, with the Lucca identifier of the employee.clientWalledTime: the date and time the employee clocked in or out, in local time without any offset (“Z”, “+01:00”, etc…).direction:infor a clock-in,outfor a clock-out.
201 Created with the created time-punch, or a 200 OK with the existing time-punch if it was
already sent (see step 4).
Resolved time. Lucca resolves the
clientWalledTime in the time zone of the employee’s establishment on that
date, and returns it as the resolvedTime of the time-punch, with its offset. For an employee of a Paris
establishment, the time-punch above has a resolvedTime of 2026-10-22T08:04:23+02:00.4. Retry time-punches that were not sent
Your punch clock will sometimes fail to send a time-punch: network outage, timeout, temporary error on Lucca’s side. Keep every time-punch in a local queue until Lucca acknowledges it, and retry it according to the response. Sending the same time-punch twice is safe. Lucca never creates the same time-punch twice: if you send a time-punch again with the sameemployee, clientWalledTime and direction, Lucca answers 200 OK with the existing
time-punch, instead of creating a new one.
So, when you retry a time-punch, send exactly the same request body. In particular, keep the original
clientWalledTime: never replace it with the time of the retry, or Lucca will create a second time-punch.
Then, depending on the response:
5. Check the time-punches sent
You can retrieve the time-punches for a given period and set of employees with a GET request to the same endpoint.links.next.href, call it to get the next page.