Skip to main content
POST
Send a verification invite

Authorizations

Authorization
string
header
required

Authorization: Api-Key <application_api_key> (legacy X-Api-Key also accepted).

Headers

Idempotency-Key
string

Email delivery only (delivery:none ignores it). Bounded opaque key (1-160 chars from [A-Za-z0-9._:-]). When absent or invalid the server generates a fresh key. A replay under a key that already owns a delivery reports that delivery's durable state: 202 sent once the provider has accepted the message, otherwise 502 invite_delivery_failed. A DIFFERENT key may replace the intent only once it has stopped owning a live send (delivered, or a terminally failed delivery); the message is then emailed again under the new key (the resend path). While a send is in flight, including an ambiguous provider outcome held as provider_retry, a different key is refused with 409 idv_state_conflict; a same-key replay never sends a second email.

Required string length: 1 - 160

Path Parameters

sessionId
string
required

Body

application/json

The recipient email is NOT accepted: it is always the linked profile's email resolved at send time for email delivery. Every field is optional.

delivery
enum<string>
default:email

email sends through the verification email service with the configured invite lifetime. none is application-principal-only and returns a single-use verify URL without looking up or sending to an email. Its lifetime defaults to 15 minutes and cannot exceed 15 minutes.

Available options:
email,
none
locale
string

BCP-47-like tag echoed into the email template (e.g. en-US).

org_name
string

Organization name shown in the invite email (overrides the theme company name).

redirect_base_url
string<uri>

Optional absolute HTTPS public base URL override for an intentional white-label verify link; falls back to the standard public verification URL when absent. HTTP is accepted only for loopback addresses in a positively local environment. Userinfo, query, and fragment components are forbidden.

Response

Direct application handoff issued; no email was sent

verify_url
string<uri>
required

Verification URL containing the one-time invite credential only in its fragment. Returned once and never persisted or logged.

invite_expires_at
string<date-time>
required