Contact
Overview
COMMITLY Public API 3.0.0
Section titled “COMMITLY Public API 3.0.0”Machine-readable description of this API: openapi.yaml (OpenAPI 3.1). Import it into Postman, Insomnia or your AI coding tool.
REST API for reading and writing cash-flow data in COMMITLY: categories, plans, bank accounts, invoices (open items), transactions and budgets.
Access
The API is included from Business Edition upwards. To get credentials, open COMMITLY and go to Add-ons > COMMITLY Public API (German UI: Erweiterungen) and connect the add-on. This generates a Client ID and a Client Secret. A credential pair is bound to one company; to work with several companies, create a credential pair per company.
Group-level access (all companies of a group) requires the Enterprise Edition; credentials for group-level access are issued by support@commitly.com. See the tag Group level (Enterprise).
Authentication
OAuth 2.0, client credentials grant.
- Request an access token from
POST https://app.commitly.com/api/auth/token/, sendinggrant_type=client_credentials,client_idandclient_secretin the request body (form-encoded, multipart or JSON). HTTP Basic authentication of the client is not supported. - Send the token with every request:
Authorization: Bearer <access_token>. - An access token is valid for 5 minutes (
expires_in: 300). When it has expired, request a new one with the client credentials.
| Situation | Status | Body |
|---|---|---|
No Authorization header | 403 | {"detail": "User must be authenticated to access this resource."} |
| Invalid or expired token | 401, header WWW-Authenticate: Bearer | {"detail": "Invalid token."} |
Language of messages
Error and validation messages are localized. Choose the language with the
Accept-Language request header: de, en or it. Without the header, messages
are in German. The 403 message for a missing token is always in English.
Conventions
- All paths end with a trailing slash (
/invoices/, not/invoices). A request without the trailing slash is answered with a 301 redirect, and the request body is lost on the redirect. - Request and response bodies are JSON unless stated otherwise.
- Dates are
YYYY-MM-DD; timestamps are ISO 8601 in UTC. - Amounts are decimals with two decimal places. Requests accept JSON numbers or numeric strings; responses return JSON numbers.
- A leaf category is a category without subcategories. Budgets, invoices and transactions can only be mapped to leaf categories.
Pagination
Paginated list endpoints accept page (starting at 1) and page_size
(default 100, maximum 1000; larger values are reduced to 1000). The response
contains count, next and previous.
Always call https://app.commitly.com/api. If a next or previous link
points to another host, read the page parameter from it and send the request to
https://app.commitly.com/api with the same path and filters.
GET /categories/ and GET /plans/ are not paginated and return a plain JSON
array.
Errors
| Status | Body |
|---|---|
| 400 | Validation errors per field: {"field": ["message", ...]}. Errors not tied to a field are listed under non_field_errors. For request bodies that are arrays, the body is a list with one error object per item. |
| 401, 403, 404, 405 | {"detail": "..."} |
| 500 | Not JSON. Treat any 500 as an unexpected server error. |
Rate limits
Please avoid excessive request rates: cache
the access token, use page_size and sync changes instead of full data sets.
Status codes
| Code | Meaning |
|---|---|
| 200 | OK |
| 201 | Created |
| 204 | Deleted, no content |
| 301 | Path without trailing slash; the request body is dropped |
| 400 | Bad request (invalid body or parameters) |
| 401 | Invalid or expired access token |
| 403 | No access token, or not allowed to call this endpoint |
| 404 | Not found |
| 500 | Unexpected server error (not JSON) |
Authentication
Section titled “Authentication”commitlyOAuth
Section titled “commitlyOAuth”OAuth 2.0 client credentials. Send client_id and client_secret in the body of
the token request (form-encoded, multipart or JSON; HTTP Basic is not
supported). Use the returned token as Authorization: Bearer <access_token>.
Access tokens are valid for 5 minutes.
Security scheme type: oauth2
Flow type: clientCredentials
Token URL: https://app.commitly.com/api/auth/token/