Invite a user
Invite a user into one of your child clients. SQUAKE emails them a link to sign up.
Invites a user into one of the authenticated client's child clients and queues the invitation email. Calling it again for the same email address and client resends the email.
Request
POST /v2/invitations
client_idstring (UUID)requiredThe child client to invite the user into. It must be a descendant of the authenticated client. The authenticated client itself is refused.
user_emailstringrequiredThe invited user's email address. SQUAKE trims it and stores it in lowercase.
rolestringrequiredThe role the user gets in the child client, a client-level role such as admin or user. SQUAKE-internal roles can't be assigned through the API.
first_namestringThe user's first name. Kept as it is on a resend that omits it.
last_namestringThe user's last name. Kept as it is on a resend that omits it.
localestringLanguage of the invitation email and the acceptance page: en, de or fr. Defaults to en for a new invitation. A resend that omits it keeps the earlier locale.
POST /v2/invitations in the API reference{
"client_id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
"user_email": "Jane.Doe@example.com",
"role": "user",
"first_name": "Jane",
"last_name": "Doe",
"locale": "de"
}Save the request as invitation.json and send it:
curl --request POST "https://api.sandbox.squake.earth/v2/invitations" \
--header "Authorization: Bearer $SQUAKE_API_KEY" \
--header "Content-Type: application/json" \
--data @invitation.jsonResponse
SQUAKE responds with 201 Created and the invitation:
{
"id": "8f6a1c9c-3f28-4b3e-9a1b-24a0f0c7f5b1",
"client_id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
"user_email": "jane.doe@example.com",
"first_name": "Jane",
"last_name": "Doe",
"role": "user",
"locale": "de",
"sent_at": "2026-08-31T10:23:14Z",
"accepted_at": null,
"invitation_url": "https://app.squake.earth/accept-invite/6b3a2e1c-9e5d-4b7a-b0f8-2c8f6a4d1e11?token=eyJhbGciOi..."
}| Field | Type | Description |
|---|---|---|
id | string (UUID) | The invitation's ID. Store it to check the invitation later. |
client_id | string (UUID) | The child client the user is invited into. |
user_email | string | The email address, trimmed and in lowercase. |
first_name | string | null | The user's first name, if provided. |
last_name | string | null | The user's last name, if provided. |
role | string | The role the user gets in the child client. |
locale | string | Language of the email and the acceptance page. |
sent_at | string (date-time) | null | When the invitation email was last sent. Updated on every resend. |
accepted_at | string (date-time) | null | When the user accepted, or null while the invitation is open. |
invitation_url | string | null | The acceptance link from the email. The user follows it to set a password and finish signing up. Stays the same when you send the invitation again. |
Treat the invitation link like a password reset link
Whoever opens invitation_url can set the user's password. Only share it with the invited person.
Resending an invitation
Send the same request again to resend the email. SQUAKE returns the existing invitation with a new sent_at, and the id and invitation_url stay the same. Fields you omit, such as first_name or locale, keep their earlier values. After the user accepts, the invitation can't be sent again.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | invalid_role | role is missing, unknown, or not a client-level role. |
400 | invalid_locale | locale isn't en, de or fr. |
401 | The API key is missing or invalid. | |
403 | client_not_invitable | client_id is the authenticated client or was omitted. Invitations only go into child clients. |
404 | Not found. Check that client_id is a client in your hierarchy. | |
422 | email_not_available | The email address already belongs to a user outside this child client. |
422 | invitation_already_accepted | The user with this email address has already accepted an invitation to this child client. |
Related
- Retrieve an invitation
- Create a child client
- Invite a User in the API reference