Reference data

An all-institutions key has "allInstitutions": true and an empty institutionIds. expiresAt (epoch seconds) appears when the key expires.

curl -s "$MASK/integration/key" -H "Authorization: Bearer $KEY"

{
  "id": 26,
  "name": "Docs example: payroll pull (Docs Example School)",
  "scopes": ["employees:read", "cards:read", "events:read", "sessions:read", "reports:read"],
  "allInstitutions": false,
  "institutionIds": [1],
  "rateLimitPerMinute": 120
}

Archived institutions are included. timezone and dayBoundaryMinutes are what you need to interpret times, and enabledEventCodes lists the codes accepted there: an event with another code is refused. status is active, inactive or archived.

curl -s "$MASK/integration/institutions" -H "Authorization: Bearer $KEY"

[
  {
    "id": 1,
    "name": "Docs Example School",
    "shortName": "DES",
    "displayName": "DES",
    "timezone": "Europe/Sarajevo",
    "dayBoundaryMinutes": 240,
    "status": "active",
    "enabledEventCodes": ["clock_in", "clock_out"]
  }
]

An institution outside the key:

curl -s "$MASK/integration/institutions/4" -H "Authorization: Bearer $KEY"      # a key that covers only institution 1

{"status": "error", "code": "not_found", "message": "Institution with ID 4 not found", "requestId": "08a620e2-d578-486d-a714-dc4ab77bf57b"}

opensInterval is the kind of stretch the code starts (work, break, personal, business), absent for a code that only closes. The catalog changes rarely: reading it once a day is enough.

curl -s "$MASK/integration/event-codes" -H "Authorization: Bearer $KEY"

[
  {"code": "clock_in", "displayName": "Clock in", "opensSession": true, "closesSession": false, "opensInterval": "work", "countsAsWork": true, "sortOrder": 10},
  {"code": "clock_out", "displayName": "Clock out", "opensSession": false, "closesSession": true, "countsAsWork": false, "sortOrder": 20},
  {"code": "break_start", "displayName": "Break start", "opensSession": false, "closesSession": false, "opensInterval": "break", "countsAsWork": false, "sortOrder": 30},
  {"code": "break_end", "displayName": "Break end", "opensSession": false, "closesSession": false, "opensInterval": "work", "countsAsWork": true, "sortOrder": 40},
  {"code": "business_exit", "displayName": "Business exit", "opensSession": false, "closesSession": false, "opensInterval": "business", "countsAsWork": true, "sortOrder": 50},
  {"code": "business_return", "displayName": "Business return", "opensSession": false, "closesSession": false, "opensInterval": "work", "countsAsWork": true, "sortOrder": 60},
  {"code": "personal_exit", "displayName": "Personal exit", "opensSession": false, "closesSession": false, "opensInterval": "personal", "countsAsWork": false, "sortOrder": 70},
  {"code": "personal_return", "displayName": "Personal return", "opensSession": false, "closesSession": false, "opensInterval": "work", "countsAsWork": true, "sortOrder": 80}
]