> ## Documentation Index > Fetch the complete documentation index at: https://developers.luccasoftware.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](/api-reference/legacy/timmi-timesheet/guides/send-time-punches) on how to send time-punches from a third-party punch clock. ## OpenAPI ````yaml /openapi-specs/timmi-timesheet.yaml post /timmi-timesheet/api/time-punches openapi: 3.1.0 info: title: Lucca Timesheet API (not v3) version: '1.0' description: The latest documentation for Lucca Timesheet API. contact: name: API Support url: https://www.luccasoftware.com email: no-reply@luccasoftware.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 servers: - url: https://{host} description: Your Lucca account URL. variables: host: default: example.ilucca.net description: >- The URL of your dedicated Lucca account: `{account}.{env}.{region}`. Account reflects your company name. Env indicates the environment. Region depends on your server location. **Please, use your test or sandbox environments (and not your production env.) for testing purposes.** **Please, use your test or sandbox environments (and not your production env.) for testing purposes.** Environments: - `ilucca`: production environment for customers. - `ilucca-test`: test environment for customers. - `ilucca-demo`: demo environment for prospects. Regions: - `.ch` for Swiss located accounts. - `.net` for the others. Regarding sandboxes, the pattern differs: `https://{account}-{sandboxName}.sandbox.{server}.luccasoftware.com`, where: - `{sandboxName}` is automatically generated upon creation. - `{server}` may be "eu1", "eu2" or "ch1". security: [] tags: - name: TimeEntries description: TimeEntries are the actual working hours observed by a user. - name: Workflow description: All actions regarding the approval process of timesheets. - name: TimePunches description: TimePunches are the clock-ins and clock-outs of employees. paths: /timmi-timesheet/api/time-punches: parameters: - $ref: '#/components/parameters/Authorization' post: tags: - TimePunches summary: Create a time-punch description: >- 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](/api-reference/legacy/timmi-timesheet/guides/send-time-punches) on how to send time-punches from a third-party punch clock. operationId: post-timmi-timesheet-api-time-punches requestBody: required: true content: application/json: schema: type: object properties: employee: type: object description: The employee who clocked in or out. properties: id: type: string minLength: 1 example: '416' description: Unique identifier of the employee. required: - id clientWalledTime: type: string format: date-time-local example: '2026-10-22T08:04:23' description: >- 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. direction: type: string enum: - in - out description: >- Whether the time-punch is a clock-in (`in`) or a clock-out (`out`). isManual: type: boolean default: false description: >- Whether the time-punch was entered by hand rather than produced by a punch clock. required: - employee - clientWalledTime - direction examples: Clock-in: value: employee: id: '416' clientWalledTime: '2026-10-22T08:04:23' direction: in responses: '200': description: >- 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. content: application/json: schema: $ref: '#/components/schemas/TimePunch' '201': description: Created content: application/json: schema: $ref: '#/components/schemas/TimePunch' '400': description: >- Bad Request. Either a required property is missing, or the employee is not on a clock-in time-tracking profile on the date of the time-punch. content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' examples: Missing property: value: title: One or more validation errors occurred. status: 400 errors: Direction: - Direction is required '401': description: Unauthorized. The API key is missing or invalid. '403': description: >- Forbidden. The API key does not have the "Edit time-punches" permission on this employee. content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' components: parameters: Authorization: name: Authorization required: true description: 'API key. Value must be formatted like so: `lucca application={api_key}`.' in: header schema: type: string schemas: TimePunch: title: TimePunch type: object description: A clock-in or clock-out of an employee. properties: id: type: string description: Unique identifier of the time-punch. example: '93874' type: type: string const: time-punch url: type: string format: uri example: https://example.ilucca.net/timmi-timesheet/api/time-punches/93874 employee: type: object description: The employee who clocked in or out. properties: id: type: string example: '416' type: type: string const: employee url: type: string format: uri example: https://example.ilucca.net/lucca-api/employees/416 resolvedTime: type: string format: date-time example: '2026-10-22T08:04:23+02:00' description: >- 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. direction: type: string enum: - in - out description: Whether the time-punch is a clock-in (`in`) or a clock-out (`out`). source: type: string enum: - integration - desktop - mobileApp - lucca description: >- 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. isManual: type: boolean description: >- Whether the time-punch was entered by hand rather than produced by a punch clock. isArchived: type: boolean description: >- Whether the time-punch is archived. Archived time-punches are no longer taken into account to compute worked time. createdAt: type: string format: date-time example: '2026-10-22T06:04:25.1234567+00:00' description: Date and time the time-punch was created in Lucca, with offset. ProblemDetails: title: ProblemDetails type: object description: Error details. properties: title: type: string status: type: integer detail: type: string errors: type: object additionalProperties: type: array items: type: string ```` ## Related topics - [How to Send Time-Punches from Your Own Punch Clock](https://developers.luccasoftware.com/api-reference/legacy/timmi-timesheet/guides/send-time-punches.md) - [Get a time-punch](https://developers.luccasoftware.com/api-reference/legacy/timmi-timesheet/time-punches/get-time-punch.md) - [List time-punches](https://developers.luccasoftware.com/api-reference/legacy/timmi-timesheet/time-punches/list-time-punches.md) - [The time-punch resource](https://developers.luccasoftware.com/api-reference/legacy/timmi-timesheet/time-punches/time-punch.md) - [Archive or restore a time-punch](https://developers.luccasoftware.com/api-reference/legacy/timmi-timesheet/time-punches/archive-time-punch.md)