# Managing Timecard Punches

> Learn how to create and delete timecard punches.

The Untether Labs API provides endpoints for managing timecard punches, allowing you to create and delete time tracking entries for your workforce.

## Terminology

Before working with timecard punches, it's important to understand the key terms:

-   **Punch**: A single time entry that records when a provider performs an action (clock in, clock out, break start, break end).
    Typically timecard punches follow a logical sequence. You'll have pairs of clock_in/clock_out punches, with optional break_start/break_end punches in between.
-   **Timecard**: A collection of punches that represent a complete work session for a provider
-   **Action**: The type of punch being recorded (`clock_in`, `clock_out`, `break_start`, `break_end`)
-   **State**: The admin approval status of a punch (`pending`, `approved`, `rejected`)

## Creating Punches

Use the `POST /v1/timekeeping/timecard/punches` endpoint to create new timecard punches.

```bash Clock In Request icon=file-terminal
curl -X POST --location "https://app.untetherlabs.com/api/v1/timekeeping/timecard/punches" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "123e4567-e89b-12d3-a456-426614174000",
    "action": "clock_in",
    "time": "2025-09-10T08:00:00Z",
    "state": "pending",
    "providerNote": "Starting my shift"
  }'
```

### Other Actions (Clock Out, Breaks)

```bash Clock Out Request icon=file-terminal
curl -X POST --location "https://app.untetherlabs.com/api/v1/timekeeping/timecard/punches" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "123e4567-e89b-12d3-a456-426614174000",
    "action": "clock_out",
    "time": "2025-09-10T17:00:00Z",
    "state": "pending",
    "providerNote": "Finished my shift"
  }'
```

### Response

```json Create Punch Response icon=braces
{
    "id": "789e1234-e89b-12d3-a456-426614174002",
    "timecard": "456e7890-e89b-12d3-a456-426614174001",
    "provider": "123e4567-e89b-12d3-a456-426614174000",
    "action": "clock_in",
    "state": "pending",
    "time": "2025-09-10T08:00:00Z",
    "generated": false,
    "createdAt": "2025-09-10T08:00:01Z",
    "updatedAt": "2025-09-10T08:00:01Z",
    "providerNote": "Starting my shift"
}
```

## Deleting Punches

Use the `DELETE /v1/timekeeping/timecard/punches/{punchId}` endpoint to remove a specific punch.

```bash Delete Punch Request icon=file-terminal
curl -X DELETE --location "https://app.untetherlabs.com/api/v1/timekeeping/timecard/punches/789e1234-e89b-12d3-a456-426614174002" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"
```

<Warning>
    When deleting the last punch in a timecard, the entire timecard will be automatically
    deleted. To re-add punches you must start over with a new `clock_in`.
</Warning>

### Response

The delete operation returns the deleted punch object:

```json Delete Punch Response icon=braces
{
    "id": "789e1234-e89b-12d3-a456-426614174002",
    "timecard": "456e7890-e89b-12d3-a456-426614174001",
    "provider": "123e4567-e89b-12d3-a456-426614174000",
    "action": "clock_in",
    "state": "pending",
    "time": "2025-09-10T08:00:00Z",
    "generated": false,
    "createdAt": "2025-09-10T08:00:01Z",
    "updatedAt": "2025-09-10T08:00:01Z",
    "providerNote": "Starting my shift"
}
```