Developers

API reference

The Kumry API is a JSON-over-HTTPS API. It is the same API the Kumry app uses, so a key sees the organisation’s data through the same permission checks as a person.

Base URL

https://api.kumry.com

Paths are grouped by area, for example /contacts, /invoices and /reports/trial-balance. The resources page lists the main read endpoints.

Requests and responses

Send the key as Authorization: Bearer km_live_… on every request.
Send request bodies as JSON with Content-Type: application/json. Responses are JSON.
Errors return a JSON body with an error message and, where there is one, a machine-readable code.
Requests are scoped to the organisation that issued the key; there is no organisation parameter.

Example

curl https://api.kumry.com/reports/trial-balance \
  -H "Authorization: Bearer km_live_..."

Rate limits

Each key has its own per-minute request limit, 600 requests a minute by default. Every response to a key carries two headers:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 597

When the limit is reached the API answers 429 with {"code":"API_KEY_RATE_LIMITED","retryAfter":<seconds>}. Wait that long before sending more requests.

Errors

Kumry API error statuses and codes
Status	Code	Meaning
401	AUTH_REQUIRED	No Authorization header, or it is not a Bearer token.
401	API_KEY_INVALID	The key is unknown, expired or revoked, or its issuer is no longer an owner or admin.
402	—	The organisation’s subscription does not cover this request. The body says why.
403	API_KEY_PATH_FORBIDDEN	Keys cannot use this part of the API (sign-in, billing, membership, administration).
403	—	The key’s access level (viewer or editor) does not permit this action.
429	API_KEY_RATE_LIMITED	The key has used its requests for the current minute. Wait retryAfter seconds.
503	AUTHORITY_UNAVAILABLE	Kumry could not check the key just now. Retry later.

API access is available on request

Organisation owners and admins create API keys and webhooks under Settings → Integrations. If you are building an integration and want to talk it through first, get in touch.