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

# Send an onboarding invitation

> POST /api/v1/onboarding-invites: ClearAML creates the client in the firm's register and emails them their onboarding link.

```http theme={null}
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

**email** `string` *required*

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

**first\_name** `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.

**last\_name** `string`

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

**reference** `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

**201 sent** `object`

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

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

**200 already\_invited** `object`

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

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

**409 existing\_client** `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.

```json theme={null}
{ "error": { "code": "existing_client", "message": "…" }, "client_id": "6f1c…", "request_id": "…" }
```

Other errors are listed in the [overview](https://docs.clearaml.com.au/api/overview.md#errors).

## Example

```bash curl theme={null}
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"}'
```

```javascript Node.js theme={null}
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.


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