Punch Events

This module describes the API endpoints for managing punch events. A punch event represents a point in time with a type (start, stop, break start, break stop). The endpoints allow creating, viewing, listing, and deleting (soft-delete) events. Punch events are used to track working hours (time trackings).

Valid Attributes

Attribute	Description	Details
`discarded_at`	Time of removal (or `null`)	Cannot be set manually. Automatically set when deleted (soft-delete).
`punched_at`	Time of punching	Cannot be set manually. Set server-side upon creation.
`punch_type`	Type of event	Must be set. Allowed values: `'start'`, `'stop'`, `'break_start'`, `'break_stop'`.
`user_id`	ID of the user associated with the event	Cannot be set manually. Set in the backend to the current user.

Relationships

The following relationships can be included in the request using the include parameter:

Relationship	Type	Description
`user`	has_one	The user associated with the punch event.

Meta-Data: Permissions

Can be included in the request using the meta[permissions] parameter. They indicate which actions the current user can perform on a punch event.

Group	Description
`actions`	Indicates whether the user can delete the punch event (`delete`).

Create

Use this endpoint to create a new punch event.

Endpoint

POST /api/v1/punch_events

Request

{
  "data": {
    "type": "punch_event",
    "attributes": {
      "punch_type": "start"
    }
  }
}

Response

{
  "data": {
    "id": "0e2f7b86-9b1e-4c1a-9d9a-7a0b6f1c5e3d",
    "type": "punch_event",
    "attributes": {
      "punch_type": "start",
      "punched_at": "2025-08-12T08:15:30Z",
      "user_id": "c2c3a4c9-5a9e-4ad8-9b7b-9a7d6c5b2e1f",
      "discarded_at": null
    }
  }
}

View

Use this endpoint to retrieve the details of a single punch event.

Endpoint

GET /api/v1/punch_events/:id

Parameters

Name	Description
`id`	The ID of the punch event to retrieve.

Response

{
  "data": {
    "id": "0e2f7b86-9b1e-4c1a-9d9a-7a0b6f1c5e3d",
    "type": "punch_event",
    "attributes": {
      "punch_type": "start",
      "punched_at": "2025-08-12T08:15:30Z",
      "user_id": "c2c3a4c9-5a9e-4ad8-9b7b-9a7d6c5b2e1f",
      "discarded_at": null
    }
  }
}

List

Use this endpoint to retrieve all punch events you have permission to view.

Endpoint

GET /api/v1/punch_events

Response

{
  "data": [
    {
      "id": "0e2f7b86-9b1e-4c1a-9d9a-7a0b6f1c5e3d",
      "type": "punch_event",
      "attributes": {
        "punch_type": "start",
        "punched_at": "2025-08-12T08:15:30Z",
        "user_id": "c2c3a4c9-5a9e-4ad8-9b7b-9a7d6c5b2e1f",
        "discarded_at": null
      }
    }
  ]
}

Examples

List all punch events:

GET /api/v1/punch_events

Filter by type:

GET /api/v1/punch_events?filter[punch_type]=eq:start

Filter by user:

GET /api/v1/punch_events?filter[user_id]=eq:123

Sort by punch time (descending):

GET /api/v1/punch_events?sort=-punched_at

Delete

Use this endpoint to delete a punch event. The event will be soft-deleted; discarded_at will be set automatically.

Endpoint

DELETE /api/v1/punch_events/:id

Parameters

Name	Description
`id`	The ID of the punch event to delete.

Response

{
  "data": {
    "id": "0e2f7b86-9b1e-4c1a-9d9a-7a0b6f1c5e3d",
    "type": "punch_event",
    "attributes": {
      "punch_type": "start",
      "punched_at": "2025-08-12T08:15:30Z",
      "user_id": "c2c3a4c9-5a9e-4ad8-9b7b-9a7d6c5b2e1f",
      "discarded_at": "2025-08-12T10:03:11Z"
    }
  }
}