SmengoAPI

Check-ins

Returns check-ins — employees' actual arrival and departure marks, with pagination and filters by period, department, and employee.

Scope

Requires the checkins.read scope. Without it, the key gets 403 missing_scope. See Scopes and permissions → Scope table for which permission the key's creator needs to grant this scope.

Query parameters

Parameter Required Description
limit no Integer 1..200, defaults to 100.
cursor no The meta.next_cursor value from the previous response — for the next page.
from, to no YYYY-MM-DD dates in the organization's timezone, boundaries inclusive — filters by entry_date. Passed only as a pair; the maximum range is 366 days. When omitted, the current calendar month is used.
department_id no A department UUID. Matched through the employee's department: you get the check-ins of that department's employees. An unknown or another organization's department_id is not an error, it just returns an empty list.
employee_id no An employee UUID — exact match. An unknown or foreign employee_id also returns an empty list, not an error.

The resource has no other parameters: any extra parameter returns 400 validation_error — it's explicitly rejected, not silently ignored (see Conventions → Filters). Passing only from without to (or vice versa) is also rejected — 400 with the hint pass both from and to, or neither.

Request

Without parameters — the current month's check-ins in the organization's timezone:

curl -s https://smengo.com/api/v1/check-ins \
  -H "Authorization: Bearer smg_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

For a specific period and a department:

curl -s "https://smengo.com/api/v1/check-ins?from=2026-07-01&to=2026-07-31&department_id=9c1a2e34-5678-4abc-9def-0123456789ab" \
  -H "Authorization: Bearer smg_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response

{
  "data": [
    {
      "id": "4d8f2c6a-1e3b-4f7d-9c5a-8b0e2f4a6c19",
      "employee_id": "5e6d9f2a-3b7c-4e2f-9a1d-7c8e2f6b4a10",
      "entry_date": "2026-07-14",
      "check_in_at": "2026-07-14T05:58:12.000Z",
      "check_out_at": "2026-07-14T14:03:47.000Z",
      "source": "telegram",
      "schedule_entry_id": "7a3c1d5e-8f2b-4c6a-9e1f-2d4b6a8c0e13"
    },
    {
      "id": "6c0a2e4d-7b9f-4c1e-8a3d-5e7f9b1d3a64",
      "employee_id": "0b2f5e7a-9c31-4d6e-8a2b-4f1e6c9d3a52",
      "entry_date": "2026-07-15",
      "check_in_at": "2026-07-15T06:02:33.000Z",
      "check_out_at": null,
      "source": "telegram",
      "schedule_entry_id": null
    }
  ],
  "meta": { "next_cursor": null }
}

Response fields

Field Type Description
id string (uuid) The check-in's unique identifier.
employee_id string (uuid) The employee the mark belongs to. The employee's name is not embedded in the response (unlike schedule entries) — resolve employee_id via Employees.
entry_date string (YYYY-MM-DD) The mark's day, in the organization's timezone; the list is sorted by this field (plus id as a tiebreaker).
check_in_at string (ISO 8601 UTC) | null The arrival mark's instant; null — no check-in happened.
check_out_at string (ISO 8601 UTC) | null The departure mark's instant; null — no check-out happened (or hasn't happened yet). Any combination of null in the check_in_at/check_out_at pair is possible, including a check-in without a check-out.
source string The mark's source. This is an open string, not a closed enum: currently the only writer of check-ins is the Telegram bot with the value telegram; other values may appear in the future.
schedule_entry_id string (uuid) | null The link to a schedule entry (see Schedule entries); null — a check-in outside the schedule.

Terminated employees never appear in this response — they're excluded entirely, along with their check-ins, regardless of filters.

Pagination

The list is sorted by entry_date, id. If there are more check-ins than limit, meta.next_cursor holds a cursor for the next page — pass it verbatim as cursor on the next request:

curl -s "https://smengo.com/api/v1/check-ins?limit=1&cursor=eyJrIjoiMjAyNi0wNy0xNCIsImlkIjoiNGQ4ZjJjNmEtMWUzYi00ZjdkLTljNWEtOGIwZTJmNGE2YzE5In0" \
  -H "Authorization: Bearer smg_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

meta.next_cursor is null once there are no more check-ins. Full pagination rules are in Conventions → Pagination.

What's next

Was this article helpful?