Skip to main content

Invite (or provision) a single user

POST 
/users/invite

Creates a user account in the org and optionally sends an invitation email. If the email already exists in the org, the existing user is returned with created: false. Supply externalRef for idempotent upserts — a second call with the same ref returns the existing entity.

Request​

Header Parameters

    Idempotency-Key string

    Optional idempotency key (24 h cache). Repeat calls with the same key and path return the cached response.

Body

required

    emailemailrequired
    Example: alice@example.com
    namestringrequired

    Possible values: non-empty

    Example: Alice Smith
    rolestring

    Org role. admin/platform_admin are rejected. Defaults to 'user'.

    Example: developer
    projectIdsuuid[]

    Projects to add the user to as member.

    sendInviteboolean

    Send email invitation. Default true.

    Example: true

    externalRef

    object

    Optional provider reference for idempotent upserts.

    providerstringrequired

    Possible values: non-empty

    Example: illumera
    externalTypestringrequired

    Possible values: non-empty

    Example: user
    externalIdstringrequired

    Possible values: non-empty

    Example: illumera-user-001

    metadata

    object

    property name*any

OK (user already existed)

Schema

    userIduuidrequired
    Example: 9a8b7c6d-0000-0000-0000-000000000002
    inviteIduuidnullablerequired

    Set when an invitation email was dispatched.

    Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
    createdbooleanrequired

    True when a new user/invitation was created; false when an existing entity was returned.

    Example: true
    statusstringrequired

    Possible values: [invited, existing, linked]

    Example: invited