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)required

The child client to invite the user into. It must be a descendant of the authenticated client. The authenticated client itself is refused.

user_emailstringrequired

The invited user's email address. SQUAKE trims it and stores it in lowercase.

rolestringrequired

The 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_namestring

The user's first name. Kept as it is on a resend that omits it.

last_namestring

The user's last name. Kept as it is on a resend that omits it.

localestring

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

See every field of 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.json

Response

SQUAKE responds with 201 Created and the invitation:

201 Createdapplication/json
{
  "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..."
}
FieldTypeDescription
idstring (UUID)The invitation's ID. Store it to check the invitation later.
client_idstring (UUID)The child client the user is invited into.
user_emailstringThe email address, trimmed and in lowercase.
first_namestring | nullThe user's first name, if provided.
last_namestring | nullThe user's last name, if provided.
rolestringThe role the user gets in the child client.
localestringLanguage of the email and the acceptance page.
sent_atstring (date-time) | nullWhen the invitation email was last sent. Updated on every resend.
accepted_atstring (date-time) | nullWhen the user accepted, or null while the invitation is open.
invitation_urlstring | nullThe 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

StatusCodeMeaning
400invalid_rolerole is missing, unknown, or not a client-level role.
400invalid_localelocale isn't en, de or fr.
401The API key is missing or invalid.
403client_not_invitableclient_id is the authenticated client or was omitted. Invitations only go into child clients.
404Not found. Check that client_id is a client in your hierarchy.
422email_not_availableThe email address already belongs to a user outside this child client.
422invitation_already_acceptedThe user with this email address has already accepted an invitation to this child client.

On this page

POST/v2/invitations

Run this request against the sandbox with your test key.

Open in API reference