> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clearaml.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

# ClearAML API: overview

> How a firm's own server sends clients their ClearAML onboarding link: base URL, authentication, errors, limits and the security checklist.

The ClearAML API lets a firm's own system, such as its website's signup form or its practice software, send a new client their ClearAML onboarding link automatically. Your server sends the client's email address; ClearAML creates the client in the firm's register and emails them their link. The firm reviews the result in ClearAML as usual.

This guide is for the developer connecting the firm's system. The firm first needs API access switched on and an API key: see [API access](/settings/api-access.md).

## Base URL

```text theme={null}
https://www.clearaml.com.au/api/v1
```

Use exactly this address, including `www`, and HTTPS only. Requests to other ClearAML addresses are redirected or refused, and most HTTP clients drop the `Authorization` header when they follow a redirect to another host.

## Authentication

Send the firm's API key in the `Authorization` header of every request:

```http theme={null}
Authorization: Bearer clr_live_…
```

> [!WARNING]
>
> Call the API from your server only. Requests from a web browser are refused (`browser_request_not_allowed`), and a key placed in a web page is public: anyone could send invitations charged to the firm's wallet. Keep the key in your server's configuration (an environment variable or secrets manager), never in source code or logs.

Check your setup with [`GET /api/v1/me`](/api/me), which costs nothing.

## Requests and responses

* Send JSON with `Content-Type: application/json`. Request bodies are limited to 8 KB.
* Every response is JSON and carries a `request_id` (also in the `X-Request-Id` header). Quote it if you contact support.
* Allow at least 60 seconds before timing out. Most requests take well under a second.

## Errors

Errors share one shape. Branch on `code`; `message` is for people and may change.

```json theme={null}
{
  "error": { "code": "daily_limit_reached", "message": "This API key has sent its daily limit of 20 invitations. It resets at midnight, Sydney time." },
  "request_id": "9b2f…"
}
```

| Status | `code` | Meaning |
| - | - | - |
| 400 | `invalid_request`, `invalid_json` | The body is not valid. `message` names the field. |
| 400 | `browser_request_not_allowed` | The request came from a web page. Call from your server. |
| 401 | `missing_api_key`, `invalid_api_key` | No key, or not a live key. Unknown and revoked keys get the same answer. |
| 402 | `billing_inactive` | The firm's ClearAML subscription is not in good standing. |
| 402 | `insufficient_funds` | The firm's wallet balance is too low. The firm has been notified. |
| 403 | `api_access_disabled` | API access is not switched on for the firm. |
| 403 | `firm_inactive` | The firm's ClearAML account is not active. |
| 403 | `ip_not_allowed` | The key may not be used from this IP address. The firm has been notified. |
| 403 | `insufficient_scope` | The key may not do this. |
| 404 | `not_found` | No such endpoint. |
| 409 | `existing_client` | The person is already a client of the firm. Nothing was sent or charged; the firm has been notified. |
| 409 | `request_in_progress` | Another request for the same email is being processed. Retry after `Retry-After` seconds. |
| 413 | `payload_too_large` | The body is over 8 KB. |
| 415 | `unsupported_media_type` | Send `Content-Type: application/json`. |
| 421 | `wrong_host` | Use the base URL above. |
| 429 | `rate_limited` | Too many requests. Retry after `Retry-After` seconds. |
| 429 | `daily_limit_reached` | The key's (or the firm's) daily invitation limit is reached. `Retry-After` gives the seconds until midnight, Sydney time. |
| 500 | `internal_error` | Something went wrong on our side. Retry the same request. |
| 502 | `link_creation_failed`, `email_delivery_failed` | The invitation could not be created or emailed, so it was withdrawn and none was sent. Retry the same request, after `Retry-After` seconds when given. |
| 503 | `billing_unavailable` | The charge could not be confirmed, so no invitation was sent. Retry after `Retry-After` seconds. |
| 503 | `temporarily_unavailable` | The service is briefly unavailable, or invitation emails failed a moment ago and new invitations are paused for about a minute. Retry after `Retry-After` seconds. |

## Limits

* **Invitations per key per day**: set by the firm (default 20, at most 500). Counts reset at midnight, Sydney time.
* **Invitations per firm per day**: 500 across all of the firm's keys.
* **Request rate**: 10 invitation requests and 30 `GET /api/v1/me` requests per minute per key.

When a request is refused for a limit, `Retry-After` says how many seconds to wait.

## Retrying safely

It is safe to send the same invitation again after a timeout, an error or a crash. If the first request went through, the second answers `already_invited` and nothing new is sent or charged. Retry `5xx` errors and `request_in_progress` with a short backoff, waiting at least `Retry-After` seconds when the response gives it. Don't retry `4xx` errors other than `409 request_in_progress` and `429`: they need a change first.

## Security checklist

* Call the API only after the person's email address has been verified or their payment or booking is confirmed. A public signup form that calls it directly lets anyone spend the firm's wallet.
* Show the person the same message whatever the API answers (for example "Check your email for your verification link"), so your site never reveals who is already a client of the firm.
* Ask the firm to set an IP allowlist on the key if your server has a fixed outbound address.
* Never log the key. ClearAML only ever displays its first characters.
* If the key may have leaked, or the person who created it leaves the firm, have the firm create a new key and revoke the old one.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.