TimeClockEventRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/hoursquare/json-schema/hoursquare-time-clock-event-request-schema.json",
  "title": "TimeClockEventRequest",
  "description": "Body of POST /api/public/v1/time-clock/events — a live punch (plan §6).",
  "x-generated": "2026-11-03",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/hoursquare-openapi.json#/components/schemas/TimeClockEventRequest",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "employee",
    "type",
    "occurredAt"
  ],
  "properties": {
    "employee": {
      "description": "The employee, by HourSquare id and/or external id. At least one is required; both must match when both are sent.",
      "oneOf": [
        {
          "$ref": "#/$defs/EmployeeSelector"
        }
      ]
    },
    "type": {
      "description": "clock_in, clock_out or toggle (open session for that day exists ? clock_out : clock_in — the recommended type for dumb clocks).",
      "oneOf": [
        {
          "$ref": "#/$defs/TimeClockEventType"
        }
      ]
    },
    "occurredAt": {
      "type": "string",
      "description": "When the punch happened: RFC 3339 with an explicit offset (2026-09-14T08:59:12+04:00). At most 5 minutes in the future and 30 days in the past.",
      "format": "date-time",
      "minLength": 1
    },
    "deviceId": {
      "type": [
        "string",
        "null"
      ],
      "description": "Optional identifier of the device or bridge that sent the punch (at most 64 characters). Stored on the entry's notes as [device: …].",
      "maxLength": 64
    },
    "note": {
      "type": [
        "string",
        "null"
      ],
      "description": "Optional note for the manager (at most 500 characters).",
      "maxLength": 500
    }
  },
  "$defs": {
    "EmployeeSelector": {
      "type": "object",
      "description": "How a public request names an employee (company API keys plan 2026-09-15, §6 \"Employee\nidentification\"): by HourSquare id, by the external (badge / HRIS) id, or both — every supplied\nselector must match, and both are resolved inside the caller's company only.",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": [
            "string",
            "null"
          ],
          "description": "The employee's HourSquare id.",
          "format": "guid"
        },
        "externalId": {
          "type": [
            "string",
            "null"
          ],
          "description": "The external id set through the Hub or PUT /employees/{id}/external-id (case-sensitive, at most 64 characters)."
        }
      }
    },
    "TimeClockEventType": {
      "type": "string",
      "description": "The type of a time-clock event (plan §6). toggle is the recommended type for\n            dumb clocks: open session on that day (or the previous day) exists ? clock_out : clock_in.",
      "x-enumNames": [
        "ClockIn",
        "ClockOut",
        "Toggle"
      ],
      "enum": [
        "clock_in",
        "clock_out",
        "toggle"
      ]
    }
  }
}