Skip to main content
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.

​
Base URL

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:
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, 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.

​
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.