# Invite a User

Invites a user to one of the authenticated client's sub-clients. The user is created if they don't already exist, or reused if the 
email address already belongs to a user of that sub-client. An invitation email is then queued.

This endpoint only supports sub-clients:  must refer to a sub-client of the authenticated client. You can't invite users 
to the authenticated client itself. Omitting  also targets the authenticated client (as it does elsewhere in v2), so both 
cases return  (). To manage users in your own organization, use the SQUAKE Dashboard.

Re-inviting the same email address for the same sub-client is safe. The existing invitation is returned with an updated , 
and the email is sent again. The acceptance URL stays the same, so any previously sent invitation link will continue to work. If
 is omitted when re-inviting a user, the locale from the previous invitation is preserved.


Endpoint: POST /v2/invitations
Security: Bearer-Auth

## Request fields (application/json):

  - `client_id` (string, required)
    The sub-client to invite the user into. Must be a descendant of the authenticated client; the authenticated client itself is refused.

  - `user_email` (string, required)
    The invitee's email address

  - `role` (string, required)
    The role the invited user will hold in the sub-client (for example  or )

  - `first_name` (string)
    The invitee's first name. Optional; kept as-is on resend when omitted.

  - `last_name` (string)
    The invitee's last name. Optional; kept as-is on resend when omitted.

  - `locale` (string)
    The language used for the invitation email and acceptance page. Optional;
defaults to  for a new invitation and is kept as-is on resend when omitted.
    Enum: "en", "de", "fr"

## Response 201 fields (application/json):

  - `id` (string, required)
    The invitation's unique identifier (UUID).

  - `client_id` (string, required)
    The UUID of the sub-client the user is being invited into. Always a descendant of the authenticated client — never the authenticated client itself.

  - `user_email` (string, required)
    The email address the invitation was issued to. Normalized (trimmed and lower-cased) on creation.

  - `first_name` (string,null)
    The invited user's first name, if provided.

  - `last_name` (string,null)
    The invited user's last name, if provided.

  - `role` (string, required)
    The role the invited user will hold in the sub-client. One of the client-level roles
(for example  or ). SQUAKE-internal roles cannot be assigned via the API.

  - `locale` (string, required)
    The language used for the invitation email and acceptance page.
    Enum: "en", "de", "fr"

  - `sent_at` (string,null)
    When the invitation email was last sent. Updated on every resend.

  - `accepted_at` (string,null, required)
    When the invited user accepted the invitation, or  if it is still outstanding.

  - `invitation_url` (string,null, required)
    The acceptance URL the invited user follows to set a password and finish signing up. Stable across resends.

## Response 400 fields (application/json):

  - `errors` (array)

  - `errors.code` (string, required)
    An application-specific error code, expressed as a string value.
    Enum: "field_validation_error", "invalid_params", "server_error", "not_authorized", "not_found", "invalid_methodology", "invalid_type", "client_not_found", "invalid_parent_client", "client_has_children", "parent_id_immutable", "travel_data_not_found"

  - `errors.detail` (string)
    A human-readable explanation specific to this occurrence of the problem. Like title, this field's value can be localized.

  - `errors.source` (object)
    An object containing references to the primary source of the error

  - `errors.source.id` (string)

  - `errors.source.attribute` (string, required)

  - `errors.source.model` (string)

## Response 401 fields (application/json):

  - `errors` (array)

  - `errors.code` (string, required)
    An application-specific error code, expressed as a string value.
    Enum: "field_validation_error", "invalid_params", "server_error", "not_authorized", "not_found", "invalid_methodology", "invalid_type", "client_not_found", "invalid_parent_client", "client_has_children", "parent_id_immutable", "travel_data_not_found"

  - `errors.detail` (string)
    A human-readable explanation specific to this occurrence of the problem. Like title, this field's value can be localized.

  - `errors.source` (object)
    An object containing references to the primary source of the error

  - `errors.source.id` (string)

  - `errors.source.attribute` (string, required)

  - `errors.source.model` (string)

## Response 403 fields (application/json):

  - `errors` (array)

  - `errors.code` (string, required)
    An application-specific error code, expressed as a string value.
    Enum: "field_validation_error", "invalid_params", "server_error", "not_authorized", "not_found", "invalid_methodology", "invalid_type", "client_not_found", "invalid_parent_client", "client_has_children", "parent_id_immutable", "travel_data_not_found"

  - `errors.detail` (string)
    A human-readable explanation specific to this occurrence of the problem. Like title, this field's value can be localized.

  - `errors.source` (object)
    An object containing references to the primary source of the error

  - `errors.source.id` (string)

  - `errors.source.attribute` (string, required)

  - `errors.source.model` (string)

## Response 404 fields (application/json):

  - `errors` (array)

  - `errors.code` (string, required)
    An application-specific error code, expressed as a string value.
    Enum: "field_validation_error", "invalid_params", "server_error", "not_authorized", "not_found", "invalid_methodology", "invalid_type", "client_not_found", "invalid_parent_client", "client_has_children", "parent_id_immutable", "travel_data_not_found"

  - `errors.detail` (string)
    A human-readable explanation specific to this occurrence of the problem. Like title, this field's value can be localized.

  - `errors.source` (object)
    An object containing references to the primary source of the error

  - `errors.source.id` (string)

  - `errors.source.attribute` (string, required)

  - `errors.source.model` (string)

## Response 422 fields (application/json):

  - `errors` (array)

  - `errors.code` (string, required)
    An application-specific error code, expressed as a string value.
    Enum: "field_validation_error", "invalid_params", "server_error", "not_authorized", "not_found", "invalid_methodology", "invalid_type", "client_not_found", "invalid_parent_client", "client_has_children", "parent_id_immutable", "travel_data_not_found"

  - `errors.detail` (string)
    A human-readable explanation specific to this occurrence of the problem. Like title, this field's value can be localized.

  - `errors.source` (object)
    An object containing references to the primary source of the error

  - `errors.source.id` (string)

  - `errors.source.attribute` (string, required)

  - `errors.source.model` (string)