Employee PIN Verify

Authenticate an employee with their phone number and PIN. On success returns the employee record, current clock status, recent time entries, and a JWT, and sets an auth-token cookie.

POST /api/v1/auth/employee/verify

Authentication: none (this is how an employee obtains a token).

Request body

string

required

The employee’s phone number — at least 10 characters. The server normalizes the value (strips spaces, dashes, parentheses, dots) and also matches on the last 4 digits, so common formatting variations are tolerated.

string

required

The employee’s PIN — 4 to 6 digits (regex ^\d{4,6}$). Verified against the stored salted PIN hash.

Response

On success returns 200 with the employee (PIN and salt stripped), their clock status, up to 5 recent time entries, and a JWT.

object

The employee record with its company (id, name, payPeriodType, active, bookkeeperOrgId, and the org’s overtime settings + timezone). The pin and pinSalt fields are removed.

object

Show clockStatus

boolean

true if the employee currently has an open time entry (no clockOut).

object | null

{ id, clockIn } of the open entry, or null if not clocked in.

array

The 5 most recent time entries (newest first), each with id, clockIn, clockOut, totalHours, regularHours, overtimeHours, status.

string

The JWT to send as Authorization: Bearer <token> on employee requests. Also set as the auth-token httpOnly cookie.

Errors

Status	`error`	Cause
`400`	`Invalid PIN format` / `Invalid verification data`	PIN is not 4–6 digits, or the body failed validation.
`401`	`Authentication failed`	No matching active employee, or PIN incorrect.
`403`	`Company inactive`	The employee’s company is deactivated.
`500`	`Verification failed`	Unexpected server error.

Phone matching is lenient (exact match or last-4-digit suffix match) and only considers active employees. If two active employees share the same last 4 digits, the first match wins — pass a fully-formatted phone number to disambiguate.

Examples

curl -X POST https://app.paypunch.io/api/v1/auth/employee/verify \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "512-555-0142",
    "pin": "1234"
  }'

{
  "phone": "512-555-0142",
  "pin": "1234"
}

{
  "success": true,
  "data": {
    "employee": {
      "id": "e1f2...",
      "firstName": "John",
      "lastName": "Smith",
      "phone": "+15125550142",
      "employeeNumber": "EMP-001",
      "active": true,
      "companyId": "c9d8...",
      "company": {
        "id": "c9d8...",
        "name": "Builders R Us",
        "payPeriodType": "BI_WEEKLY",
        "active": true,
        "bookkeeperOrgId": "a1c2...",
        "bookkeeperOrg": {
          "overtimeThreshold": 40,
          "overtimeMultiplier": 1.5,
          "timezone": "America/New_York"
        }
      }
    },
    "clockStatus": {
      "isClockedIn": false,
      "openTimeEntry": null
    },
    "recentTimeEntries": [
      {
        "id": "t1...",
        "clockIn": "2026-06-16T13:00:00.000Z",
        "clockOut": "2026-06-16T21:30:00.000Z",
        "totalHours": 8,
        "regularHours": 8,
        "overtimeHours": 0,
        "status": "APPROVED"
      }
    ],
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Overview

Admin API

Employee API

Employee PIN Verify

Request body

Response

Errors

Examples

​Request body

​Response

​Errors

​Examples

Request body

Response

Errors

Examples