Create a time-punch

curl --request POST \
  --url https://{host}/timmi-timesheet/api/time-punches \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "employee": {
    "id": "416"
  },
  "clientWalledTime": "2026-10-22T08:04:23",
  "direction": "in"
}
'

import requests

url = "https://{host}/timmi-timesheet/api/time-punches"

payload = {
    "employee": { "id": "416" },
    "clientWalledTime": "2026-10-22T08:04:23",
    "direction": "in"
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    employee: {id: '416'},
    clientWalledTime: '2026-10-22T08:04:23',
    direction: 'in'
  })
};

fetch('https://{host}/timmi-timesheet/api/time-punches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{host}/timmi-timesheet/api/time-punches",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'employee' => [
        'id' => '416'
    ],
    'clientWalledTime' => '2026-10-22T08:04:23',
    'direction' => 'in'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{host}/timmi-timesheet/api/time-punches"

	payload := strings.NewReader("{\n  \"employee\": {\n    \"id\": \"416\"\n  },\n  \"clientWalledTime\": \"2026-10-22T08:04:23\",\n  \"direction\": \"in\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{host}/timmi-timesheet/api/time-punches")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"employee\": {\n    \"id\": \"416\"\n  },\n  \"clientWalledTime\": \"2026-10-22T08:04:23\",\n  \"direction\": \"in\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{host}/timmi-timesheet/api/time-punches")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"employee\": {\n    \"id\": \"416\"\n  },\n  \"clientWalledTime\": \"2026-10-22T08:04:23\",\n  \"direction\": \"in\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "93874",
  "type": "time-punch",
  "url": "https://example.ilucca.net/timmi-timesheet/api/time-punches/93874",
  "employee": {
    "id": "416",
    "type": "employee",
    "url": "https://example.ilucca.net/lucca-api/employees/416"
  },
  "resolvedTime": "2026-10-22T08:04:23+02:00",
  "direction": "in",
  "source": "integration",
  "isManual": true,
  "isArchived": true,
  "createdAt": "2026-10-22T06:04:25.1234567+00:00"
}

{
  "id": "93874",
  "type": "time-punch",
  "url": "https://example.ilucca.net/timmi-timesheet/api/time-punches/93874",
  "employee": {
    "id": "416",
    "type": "employee",
    "url": "https://example.ilucca.net/lucca-api/employees/416"
  },
  "resolvedTime": "2026-10-22T08:04:23+02:00",
  "direction": "in",
  "source": "integration",
  "isManual": true,
  "isArchived": true,
  "createdAt": "2026-10-22T06:04:25.1234567+00:00"
}

{
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Direction": [
      "Direction is required"
    ]
  }
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "errors": {}
}

Time-punches

Create a time-punch

Create a clock-in or clock-out for an employee, for instance when they clock in on your own punch clock integrated with Lucca.

The API key must have the “Edit time-punches” permission on the employee, and the employee must be on a clock-in time-tracking profile on the date of the time-punch.

The clientWalledTime you send is a local date and time, without offset. Lucca resolves it in the time zone of the employee’s establishment on that date, and returns the result as the resolvedTime of the time-punch, with its offset. For instance, a clientWalledTime of 2026-10-22T08:04:23 for an employee of a Paris establishment gives a resolvedTime of 2026-10-22T08:04:23+02:00.

Sending the same time-punch again (same employee, clientWalledTime and direction) does not create a duplicate: Lucca returns the existing time-punch with a 200 OK.

Please see this guide on how to send time-punches from a third-party punch clock.

POST

timmi-timesheet

api

time-punches

Create a time-punch

curl --request POST \
  --url https://{host}/timmi-timesheet/api/time-punches \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "employee": {
    "id": "416"
  },
  "clientWalledTime": "2026-10-22T08:04:23",
  "direction": "in"
}
'

import requests

url = "https://{host}/timmi-timesheet/api/time-punches"

payload = {
    "employee": { "id": "416" },
    "clientWalledTime": "2026-10-22T08:04:23",
    "direction": "in"
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    employee: {id: '416'},
    clientWalledTime: '2026-10-22T08:04:23',
    direction: 'in'
  })
};

fetch('https://{host}/timmi-timesheet/api/time-punches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{host}/timmi-timesheet/api/time-punches",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'employee' => [
        'id' => '416'
    ],
    'clientWalledTime' => '2026-10-22T08:04:23',
    'direction' => 'in'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{host}/timmi-timesheet/api/time-punches"

	payload := strings.NewReader("{\n  \"employee\": {\n    \"id\": \"416\"\n  },\n  \"clientWalledTime\": \"2026-10-22T08:04:23\",\n  \"direction\": \"in\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{host}/timmi-timesheet/api/time-punches")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"employee\": {\n    \"id\": \"416\"\n  },\n  \"clientWalledTime\": \"2026-10-22T08:04:23\",\n  \"direction\": \"in\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{host}/timmi-timesheet/api/time-punches")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"employee\": {\n    \"id\": \"416\"\n  },\n  \"clientWalledTime\": \"2026-10-22T08:04:23\",\n  \"direction\": \"in\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "93874",
  "type": "time-punch",
  "url": "https://example.ilucca.net/timmi-timesheet/api/time-punches/93874",
  "employee": {
    "id": "416",
    "type": "employee",
    "url": "https://example.ilucca.net/lucca-api/employees/416"
  },
  "resolvedTime": "2026-10-22T08:04:23+02:00",
  "direction": "in",
  "source": "integration",
  "isManual": true,
  "isArchived": true,
  "createdAt": "2026-10-22T06:04:25.1234567+00:00"
}

{
  "id": "93874",
  "type": "time-punch",
  "url": "https://example.ilucca.net/timmi-timesheet/api/time-punches/93874",
  "employee": {
    "id": "416",
    "type": "employee",
    "url": "https://example.ilucca.net/lucca-api/employees/416"
  },
  "resolvedTime": "2026-10-22T08:04:23+02:00",
  "direction": "in",
  "source": "integration",
  "isManual": true,
  "isArchived": true,
  "createdAt": "2026-10-22T06:04:25.1234567+00:00"
}

{
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Direction": [
      "Direction is required"
    ]
  }
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "errors": {}
}

Headers

Authorization

string

required

API key. Value must be formatted like so: lucca application={api_key}.

Body

application/json

employee

object

required

The employee who clocked in or out.

Show child attributes

clientWalledTime

string<date-time-local>

required

The date and time when the employee clocked in or out, in the local time of the employee's establishment. Do not include any offset/timezone information ("Z", "+01:00", etc...). Lucca resolves it into the resolvedTime of the time-punch.

Example:

"2026-10-22T08:04:23"

direction

enum<string>

required

Whether the time-punch is a clock-in (in) or a clock-out (out).

Available options:

in,

out

isManual

boolean

default:false

Whether the time-punch was entered by hand rather than produced by a punch clock.

Response

OK. A non-archived time-punch with the same employee, clientWalledTime and direction was already sent. The existing time-punch is returned, and no new one is created. A time-punch in the other direction at the same date and time is created as a new one.

A clock-in or clock-out of an employee.

string

Unique identifier of the time-punch.

Example:

"93874"

type

string

Allowed value: "time-punch"

url

string<uri>

Example:

"https://example.ilucca.net/timmi-timesheet/api/time-punches/93874"

employee

object

The employee who clocked in or out.

Show child attributes

resolvedTime

string<date-time>

The date and time when the employee clocked in or out, with the offset of the time zone of the employee's establishment. For a time-punch created with an API key, it is the clientWalledTime sent, resolved in that time zone.

Example:

"2026-10-22T08:04:23+02:00"

direction

enum<string>

Whether the time-punch is a clock-in (in) or a clock-out (out).

Available options:

in,

out

source

enum<string>

The system the time-punch came from:

integration: a punch clock integrated with an API key, such as your own.
desktop: Lucca virtual punch clock, from a web browser.
mobileApp: Lucca virtual punch clock, from the mobile app.
lucca: a Lucca punch clock.

Available options:

integration,

desktop,

mobileApp,

lucca

isManual

boolean

Whether the time-punch was entered by hand rather than produced by a punch clock.

isArchived

boolean

Whether the time-punch is archived. Archived time-punches are no longer taken into account to compute worked time.

createdAt

string<date-time>

Date and time the time-punch was created in Lucca, with offset.

Example:

"2026-10-22T06:04:25.1234567+00:00"

Documentation

Files

Organization Structure API

Core HR API

Recruitment API

Expenses API

Invoices API

Absences API

Office API

Project API

Schedule API

Timesheet API

Mealvouchers API

Compensation API

Training API

Create a time-punch

Headers

Body

Response