Developer reference

ZenchronityAPI reference

Read your people, leave and audit data over REST, and bring it into payroll, reporting or your own tools.

JSON over HTTPSRead-onlyUp to 100 per pageHosted in the EU

Your first call in three steps

1
Create a key
An admin creates one in the app's organization settings, with an expiry of up to 365 days. It is shown once.
2
Send it with every call
As Authorization: Bearer zc_live_… or in an X-API-Key header.
3
Check the connection
GET /health answers with your organization code and the key's access level.
https://api.zenchronity.com/api/public-api
/health/users/users/:id/requests/leave-types/departments/teams/audit-logsErrorsRate limitsKeeping keys safeWriting it with AI
GET/healthAny key

Health check

Checks that your key works. Returns your organization code and the key's access level.

curl "https://api.zenchronity.com/api/public-api/health" \
  -H "Authorization: Bearer $ZENCHRONITY_API_KEY"
Response200
{
  "status": "ok",
  "orgCode": "acme",
  "accessLevel": "read",
  "timestamp": "2026-09-27T10:30:00.000Z"
}
GET/usersRead access

List users

Everyone in your organization, sorted by last name, a page at a time.

Parameters

  • pageinteger

    Page number. Default 1.

  • limitinteger

    Items per page. Default 50, at most 100.

curl "https://api.zenchronity.com/api/public-api/users?page=1&limit=50" \
  -H "Authorization: Bearer $ZENCHRONITY_API_KEY"
Response200
{
  "data": [
    {
      "id": "3f1c2a9e-7b4d-4c1a-9e2f-5d8b6a0c1e72",
      "email": "emma.clarke@acme.com",
      "firstName": "Emma",
      "lastName": "Clarke",
      "jobTitle": "Product Designer",
      "internalId": "EMP-0142",
      "countryCode": "IE",
      "startDate": "2023-03-01",
      "status": "active"
    }
  ],
  "meta": {
    "total": 25,
    "page": 1,
    "limit": 50,
    "totalPages": 1
  }
}
GET/users/:idRead access

Get a user

One user by id, with their department, team and manager. If no user has that id, the body is { "error": "User not found", "statusCode": 404 }.

Parameters

  • iduuidrequired

    The user's id, in the path.

curl "https://api.zenchronity.com/api/public-api/users/3f1c2a9e-7b4d-4c1a-9e2f-5d8b6a0c1e72" \
  -H "Authorization: Bearer $ZENCHRONITY_API_KEY"
Response200
{
  "id": "3f1c2a9e-7b4d-4c1a-9e2f-5d8b6a0c1e72",
  "email": "emma.clarke@acme.com",
  "firstName": "Emma",
  "lastName": "Clarke",
  "jobTitle": "Product Designer",
  "internalId": "EMP-0142",
  "countryCode": "IE",
  "startDate": "2023-03-01",
  "status": "active",
  "departmentId": "a2b7c9d1-0e3f-4a5b-8c6d-7e8f9a0b1c2d",
  "teamId": "c4d5e6f7-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
  "managerId": "e6f7a8b9-2c3d-4e5f-a0b1-c2d3e4f5a6b7"
}
GET/requestsRead access

List leave requests

Leave requests, newest first, with the person who asked. Filter by status, person or dates.

Parameters

  • pageinteger

    Page number. Default 1.

  • limitinteger

    Items per page. Default 50, at most 100.

  • statusstring

    pending, approved, rejected or cancelled.

  • userIduuid

    Only this person's requests.

  • fromdate

    Requests starting on or after, YYYY-MM-DD.

  • todate

    Requests ending on or before, YYYY-MM-DD.

curl "https://api.zenchronity.com/api/public-api/requests?status=approved&from=2026-10-01" \
  -H "Authorization: Bearer $ZENCHRONITY_API_KEY"
Response200
{
  "data": [
    {
      "id": "9d8c7b6a-5f4e-4d3c-b2a1-0f9e8d7c6b5a",
      "startDate": "2026-10-12",
      "endDate": "2026-10-16",
      "totalDays": 5,
      "status": "approved",
      "user": {
        "id": "3f1c2a9e-7b4d-4c1a-9e2f-5d8b6a0c1e72",
        "firstName": "Emma",
        "lastName": "Clarke",
        "email": "emma.clarke@acme.com"
      }
    }
  ],
  "meta": {
    "total": 10,
    "page": 1,
    "limit": 50,
    "totalPages": 1
  }
}
GET/leave-typesRead access

List leave types

The active leave types, sorted by name, with how each one is counted.

curl "https://api.zenchronity.com/api/public-api/leave-types" \
  -H "Authorization: Bearer $ZENCHRONITY_API_KEY"
Response200
[
  {
    "id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
    "key": "vacation",
    "name": "Annual leave",
    "planned": true,
    "color": "primary",
    "quotaType": "separate"
  },
  {
    "id": "d3e4f5a6-b7c8-4d9e-a0f1-2b3c4d5e6f7a",
    "key": "sick_leave",
    "name": "Sick leave",
    "planned": false,
    "color": "danger",
    "quotaType": "unlimited"
  }
]
GET/departmentsRead access

List departments

Every department, sorted by name.

curl "https://api.zenchronity.com/api/public-api/departments" \
  -H "Authorization: Bearer $ZENCHRONITY_API_KEY"
Response200
[
  {
    "id": "a2b7c9d1-0e3f-4a5b-8c6d-7e8f9a0b1c2d",
    "name": "Engineering",
    "description": "Product and platform",
    "managerId": "e6f7a8b9-2c3d-4e5f-a0b1-c2d3e4f5a6b7"
  }
]
GET/teamsRead access

List teams

Every team, sorted by name.

curl "https://api.zenchronity.com/api/public-api/teams" \
  -H "Authorization: Bearer $ZENCHRONITY_API_KEY"
Response200
[
  {
    "id": "c4d5e6f7-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
    "name": "Design",
    "managerId": "e6f7a8b9-2c3d-4e5f-a0b1-c2d3e4f5a6b7"
  }
]
GET/audit-logsRead access

List audit logs

Sign-ins, leave requests, approvals and security events, newest first. Audit logs are kept for 3 months.

Parameters

  • pageinteger

    Page number. Default 1.

  • limitinteger

    Items per page. Default 50, at most 100.

  • fromdate

    Events on or after, YYYY-MM-DD.

  • todate

    Events on or before, YYYY-MM-DD.

  • searchstring

    Text to look for in the message or action.

curl "https://api.zenchronity.com/api/public-api/audit-logs?from=2026-09-01&search=login" \
  -H "Authorization: Bearer $ZENCHRONITY_API_KEY"
Response200
{
  "data": [
    {
      "action": "login",
      "message": "User emma.clarke@acme.com logged in",
      "ip": "192.0.2.14",
      "createdAt": "2026-09-27T08:02:11.000Z",
      "actor": {
        "email": "emma.clarke@acme.com",
        "firstName": "Emma",
        "lastName": "Clarke"
      },
      "targetUser": null,
      "meta": null
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 50,
    "totalPages": 3
  }
}

Errors

A failed call answers with an HTTP status code and a JSON body that says what went wrong.

  • 401UnauthorizedThe key is missing, wrong, expired or revoked.
  • 404Not foundThere is no endpoint at that path.
  • 429Too many requestsMore than 100 requests in a minute. Wait a moment and try again.
  • 500Server errorSomething failed on our side. Try again, and tell us if it keeps happening.

Rate limits

You can make up to 100 requests a minute. Every response says how many you have left, so a script can slow down before it hits the limit. Past it, calls answer 429 until the window resets.

  • X-RateLimit-Limit: 100Requests allowed in the current window.
  • X-RateLimit-Remaining: 97Requests left in the window.
  • X-RateLimit-Reset: 42Seconds until the window starts again.
  • Retry-After: 42Sent with a 429: seconds to wait before trying again.

Syncing everything? Ask for 100 items a page and pause when X-RateLimit-Remaining reaches 0. A nightly sync of a few thousand people fits well inside the limit.

Keeping keys safe

  • Keep keys on your server. Put them in environment variables, never in a browser or mobile app.
  • We store only a hash. A lost key can't be recovered, only replaced with a new one.
  • Every key expires. After at most 365 days, and an admin can revoke one at any time.
  • Read access is enough. Every endpoint today only reads data.

Writing it with AI

Paste the address of this page into ChatGPT, Claude or Gemini and say what you need. The whole reference is also there as plain text, at /llms-full.txt.

For example

“Using the Zenchronity API, write a Python script that saves next month's approved leave as a CSV file.”

Need something the API doesn't do yet?

Tell us what you're building and which data you need from Zenchronity.

Contact usSecurity