Skip to main content

Access and rate limits

Two things decide what a call may do:

  • Access groups decide which operations a key may call, and company scope decides whose data.
  • The rate tier decides how much the key may call, measured in points.

GET /v3/me shows all of it for your key, live, and costs nothing.

Access groups​

An access group is a named set of operations. Access is denied by default: a key may call only the operations of the groups it holds. A key with several groups may call the operations of all of them.

GroupAllows
core_readThe read operations (GET)
core_writeThe operations that create or change data (POST, PUT)

"Read only" means core_read. "Read and write" means core_read and core_write.

  • Every operation, with its group and cost is listed below. In the machine-readable document they are each operation's x-zooza-access ({"groups": […], "cost": …}), and the reference shows them at the end of each operation's description.
  • Calling an operation outside the key's groups answers 403.
  • A key can never do more than its owner. The token acts as the owner named in the token request, and access groups only narrow what that owner may do.
  • A change to a key's groups applies to tokens requested after the change (so within 60 minutes at most). See Keys.

Company scope​

A key acts for exactly one company: the company that created it (company scope pinned). It can't read or change another company's data, even a company the same owner also owns or one in the same network. You don't send a company id; every call works on the key's company.

GET /v3/me​

{
"client_id": "zk_…",
"region": "EU",
"groups": ["core_read"],
"tier": "free",
"points": {
"limit_minute": 60, "remaining_minute": 54,
"limit_day": 1000, "remaining_day": 872,
"reset_day": "2026-11-19T00:00:00Z"
},
"token": { "expires_at": "2026-11-18T11:00:00Z" },
"operations": [
{ "op": "get_courses", "method": "GET", "path": "/v3/courses", "cost": 2 }
]
}
FieldMeaning
client_idThe key
regionEU, UK or ASIA: the key's region
groupsThe key's access groups
tierYour company's rate tier, the same for all its keys
pointsThe company's budget per minute and per day, what's left, and when the day resets (midnight UTC)
token.expires_atWhen the token used for this call expires
operationsEvery operation the key may call, with its cost

It's the recommended way to check remaining budget and permissions before a batch job.

Rate limits: points​

Limits are counted in points, not requests. Each operation costs points, and your company's rate tier gives it a budget per minute and per day. The day window resets at midnight UTC.

The budget belongs to the company, not to a key: all of its keys draw on the same points, so two integrations running at once share it. The tier follows the company's Zooza plan; see GET /v3/me for the live numbers.

Today's defaults

The costs and tiers below are today's defaults and may change. The authoritative numbers are in the table of operations and the tier table below (both generated from the published document), and GET /v3/me.

Costs

Kind of callPoints
Read one record (GET with an id)1
Read a list2
Create or change (POST, PUT)5
Download link (invoice PDF)10
GET /v3/me, POST /v3/token0

Costs per operation​

Generated from the published OpenAPI document, so it always matches what is charged.

OperationRequestAccess groupPoints
Get an access tokenPOST /v3/tokenany key0
Get key details and budgetGET /v3/meany key0
Get an agreement versionGET /v3/agreements/{ID}core_read1
List sessionsGET /v3/eventscore_read2
Create sessionsPOST /v3/eventscore_write5
Update several sessionsPUT /v3/eventscore_write5
Get a sessionGET /v3/events/{ID}core_read1
Update a sessionPUT /v3/events/{ID}core_write5
Set an extra field on a registrationPOST /v3/extra_fieldscore_write5
Update an extra fieldPUT /v3/extra_fields/{ID}core_write5
Get a session's attendance registerGET /v3/attendancecore_read2
Calendar of sessionsGET /v3/calendarcore_read2
Search registrationsGET /v3/registrationscore_read2
Get a registrationGET /v3/registrations/{ID}core_read1
Update a registrationPUT /v3/registrations/{ID}core_write5
List programmesGET /v3/coursescore_read2
Create a programmePOST /v3/coursescore_write5
Get a programmeGET /v3/courses/{ID}core_read1
Update a programmePUT /v3/courses/{ID}core_write5
List classesGET /v3/schedulescore_read2
Create a classPOST /v3/schedulescore_write5
Get a classGET /v3/schedules/{ID}core_read1
Update a classPUT /v3/schedules/{ID}core_write5
List billing periodsGET /v3/billing_periodscore_read2
List customer invoicesGET /v3/customer_invoicescore_read2
Create a customer invoicePOST /v3/customer_invoicescore_write5
Get a customer invoiceGET /v3/customer_invoices/{ID}core_read1
Get a download link for an invoiceGET /v3/customer_invoices/{ID}/downloadcore_read10
Get a download link for several invoicesGET /v3/customer_invoices/downloadcore_read10
List venuesGET /v3/placescore_read2
List usersGET /v3/userscore_read2

Rate tiers

TierPoints per minutePoints per day
free601,000
standard30020,000
partner_xl1,200100,000

The tier is your company's and follows its Zooza plan. GET /v3/me shows which tier applies.

When points are charged​

  • Points are charged before the call runs.
  • They are refunded only when the API couldn't handle the call at all: 503 (temporarily unavailable) and 504 (no answer in time).
  • Every other answer costs the operation's points, including 400 and 500.

Rate-limit headers​

Every successful call and every 429 carries the budget, in points:

HeaderMeaning
X-RateLimit-LimitPoints per minute
X-RateLimit-RemainingPoints left in the current minute
X-RateLimit-ResetSeconds until the minute budget resets
X-RateLimit-Limit-DayPoints per day
X-RateLimit-Remaining-DayPoints left today (UTC)
X-RateLimit-Reset-DaySeconds until the daily budget resets

Handling 429​

Over budget, the API answers 429 with a Retry-After header: the number of seconds to wait.

  • Wait at least Retry-After seconds before the next call. Don't retry in a tight loop.
  • For batch jobs, watch X-RateLimit-Remaining and slow down before you hit zero.
  • If you regularly run out of the daily budget, cache what you read: programmes, classes and venues change rarely.
async function callWithRetry(url, options, attempts = 3) {
for (let i = 0; i < attempts; i++) {
const res = await fetch(url, options);
if (res.status !== 429) return res;
const wait = Number(res.headers.get('Retry-After') || 1);
await new Promise((r) => setTimeout(r, wait * 1000));
}
throw new Error('Still rate limited after retries');
}

The token operation has its own, separate limit: see Authentication.

  • Keys: changing a key's access groups
  • Errors: 403, 429 and the other error bodies
  • API reference: the groups and cost of every operation