Hanna CRM API v44.0.0

Warning: If you still use the legacy REST API v3 (/api/v3/...), open the Legacy API v3 documentation.

MCP tools are documented separately: MCP Tools documentation.

API keys

1. Sign in to Hanna CRM as a user with access to Setup → API & MCP.
2. Create a key in Setup → API & MCP.
3. Copy the token immediately after creation — it is shown only once.
4. Send it on every API request: Authorization: Bearer {token}.

Scopes (choose when creating the key):

• read — GET requests
• write — POST and PATCH
• delete — DELETE

Access: A personal key acts as your staff user (your role permissions). A global key uses the module permissions configured on that key.

Optional fields

Response fields are not a fixed contract: an account can switch modules and features on or off, and can hide individual fields through Setup → form field management (per account, and optionally per role or per user). The API key’s staff user decides which of those rules apply.

A field that is turned off is omitted from the JSON object entirely — it is never returned as null. So a missing key means "disabled for this key’s user", while a key that is present with a null value means "enabled, but this record has no value". Treat absent keys as optional rather than as an error.

Because this documentation is served without signing in, the schemas below reflect the account-level defaults. A key whose role or user has extra field overrides can therefore receive fewer fields than documented (for example legal_type on clients, which follows the client_is_juridical form field).

Rate limit

Requests are throttled per minute, counted per authenticated API user (unauthenticated requests are counted per IP address). The default allowance is 60 requests per minute; accounts can be configured between 1 and 400 by Hanna CRM support.

Exceeding it returns 429 Too Many Requests with a Retry-After header (seconds to wait). Every response also carries X-RateLimit-Limit and X-RateLimit-Remaining. Clients that poll should spread requests out and honour Retry-After rather than retrying immediately.

This instance

• API v4 base URL: https://default.hannacrm.app/api/v4
• API documentation: https://default.hannacrm.app/api/docs

Response schemas in this document reflect fields enabled for this tenant’s configuration.

curl --request GET \
  --url https://default.hannacrm.app/api/v4/me \
  --header 'Authorization: Bearer <token>'