Send an onboarding invitation

POST https://www.clearaml.com.au/api/v1/onboarding-invites

Send a client’s email address; ClearAML creates the client in the firm’s register (or reuses a never-verified profile with the same email) and emails them their onboarding link. The firm’s wallet is charged exactly as for an invitation sent from ClearAML. The link itself is never returned: it reaches the client by email only.

Body

string

required

The client’s email address (at most 254 characters). Matching is not case-sensitive.

string

The client’s first name (at most 100 characters). Recommended: if the email already belongs to a never-verified profile that has a name, the invitation goes to that profile only when the first and last names match. The names are used only for this check and never stored.

string

The client’s last name (at most 100 characters). Send it with first_name.

string

Your own reference, such as an order or booking number. It appears on the check as its matter number. 1 to 100 characters: letters, digits, spaces and _ . / # -, starting with a letter or digit.

Any other field is refused (invalid_request).

Responses

object

The invitation was created and emailed. client_id is the client’s id in ClearAML; expires_at is when the link expires.

{ "status": "sent", "client_id": "6f1c…", "expires_at": "2026-10-29T03:00:00.000Z", "request_id": "…" }

object

An invitation for this email is already open. Nothing new was sent or charged.

{ "status": "already_invited", "client_id": "6f1c…", "expires_at": "2026-10-28T00:00:00.000Z", "request_id": "…" }

object

The person is already a client of the firm and should not be invited again automatically: they have been verified, a check is under way, the email belongs to a profile whose name doesn’t match the one you sent, or it matches more than one profile. Nothing was sent or charged, and the firm has been notified to decide.

{ "error": { "code": "existing_client", "message": "…" }, "client_id": "6f1c…", "request_id": "…" }

Other errors are listed in the overview.

Example

curl https://www.clearaml.com.au/api/v1/onboarding-invites \
  -H "Authorization: Bearer $CLEARAML_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"jo.citizen@example.com","first_name":"Jo","last_name":"Citizen","reference":"ORDER-1042"}'

const res = await fetch('https://www.clearaml.com.au/api/v1/onboarding-invites', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CLEARAML_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ email: 'jo.citizen@example.com', first_name: 'Jo', last_name: 'Citizen', reference: 'ORDER-1042' }),
  signal: AbortSignal.timeout(60_000),
});
const body = await res.json();
if (res.status === 201 || body.status === 'already_invited') {
  // Invitation on its way (or already sent).
} else if (res.status === 409 && body.error?.code === 'existing_client') {
  // Already a client: the firm has been told.
} else if (res.status === 429 || res.status >= 500 || body.error?.code === 'request_in_progress') {
  // Retry later; see Retry-After.
} else {
  // Fix the request or tell the firm: body.error.code says why.
}

What the client receives

An email from the firm (on its ClearAML branding) with a link to verify their identity and answer the onboarding questions. The link expires after 7 days; reminders are sent while it is open if the firm has them switched on. When the client finishes, the firm is notified and reviews the result in ClearAML.

Get Started

Core Features

API

Compliance Program

Team & Settings

Guides

Help

Send an onboarding invitation

Body

Responses

Example

What the client receives

​Body

​Responses

​Example

​What the client receives

Body

Responses

Example

What the client receives