> ## Documentation Index > Fetch the complete documentation index at: https://docs.gominerva.com/llms.txt > Use this file to discover all available pages before exploring further. # Send a verification invite > Accepts an application API key or a dashboard session. `delivery: email` preserves the established email flow. `delivery: none` is application-principal-only and returns a verify URL directly with a single-use invite credential whose TTL defaults to and cannot exceed 15 minutes; the URL is never logged. The recipient is ALWAYS the LINKED PROFILE's email resolved from the Minerva profiles service AT SEND TIME for email delivery; the request no longer carries `to_email`. Direct delivery performs no profile-email lookup. An empty profile email -> 422 `idv_profile_email_missing` (add an email to the profile first); a profile-service lookup failure -> 503 `idv_profile_lookup_unavailable`. Creates or refreshes an invite credential (default lifetime 72 hours), builds the verify URL on the public verification host, and sends the email. The invite is persisted AFTER the email resolves but BEFORE delivery, so a 502 leaves a usable invite for a re-invite retry. The recipient email is PII: never persisted or logged; the invite code appears only in the emailed URL fragment. ## OpenAPI ````yaml /api-reference/idv-svc.json post /sessions/{sessionId}/invite openapi: 3.1.0 info: title: Minerva IDV API version: 1.0.0-draft description: >- Customer API for identity verification. Create verification sessions for profiles, deliver invites, track capture progress, and read review outcomes. For the end-to-end flow, see the [IDV Integration Guide](/api-reference/idv-integration-guide). Reviewer-safe responses never expose storage keys, checksums, wrapped keys, encryption context, raw OCR, or raw model output. Decrypted personal data is available only on `GET /sessions/{sessionId}/data`, to an authenticated in-scope principal, with fail-closed auditing. servers: - url: https://api.gominerva.com/idv/v1 description: The production API server for Minerva identity verification security: [] tags: - name: sessions description: >- Verification sessions and invite delivery (application or dashboard authentication). - name: capture description: End-user capture flow (session or invite credentials). - name: review description: Review decisions and audited structured-data access. - name: workflows description: Workflow configuration for verification sessions. - name: themes description: Branding themes and managed logo assets. paths: /sessions/{sessionId}/invite: post: tags: - sessions summary: Send a verification invite description: > Accepts an application API key or a dashboard session. `delivery: email` preserves the established email flow. `delivery: none` is application-principal-only and returns a verify URL directly with a single-use invite credential whose TTL defaults to and cannot exceed 15 minutes; the URL is never logged. The recipient is ALWAYS the LINKED PROFILE's email resolved from the Minerva profiles service AT SEND TIME for email delivery; the request no longer carries `to_email`. Direct delivery performs no profile-email lookup. An empty profile email -> 422 `idv_profile_email_missing` (add an email to the profile first); a profile-service lookup failure -> 503 `idv_profile_lookup_unavailable`. Creates or refreshes an invite credential (default lifetime 72 hours), builds the verify URL on the public verification host, and sends the email. The invite is persisted AFTER the email resolves but BEFORE delivery, so a 502 leaves a usable invite for a re-invite retry. The recipient email is PII: never persisted or logged; the invite code appears only in the emailed URL fragment. parameters: - $ref: '#/components/parameters/SessionId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/InviteSessionRequest' responses: '200': description: Direct application handoff issued; no email was sent content: application/json: schema: $ref: '#/components/schemas/DirectInviteSessionResponse' '202': description: Invite accepted for delivery content: application/json: schema: $ref: '#/components/schemas/InviteSessionResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': description: >- Dashboard principals cannot request `delivery:none` (`idv_direct_invite_forbidden`). content: application/json: schema: $ref: '#/components/schemas/Error' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': description: >- The linked profile has no email address (`idv_profile_email_missing`). content: application/json: schema: $ref: '#/components/schemas/Error' '502': $ref: '#/components/responses/BadGateway' '503': description: > Email delivery could not resolve the linked profile (`idv_profile_lookup_unavailable`), or direct delivery has no public verification URL configured (`idv_direct_invite_unavailable`). content: application/json: schema: $ref: '#/components/schemas/Error' security: - applicationApiKey: [] - dashboardUserToken: [] components: parameters: SessionId: name: sessionId in: path required: true schema: type: string IdempotencyKey: name: Idempotency-Key in: header required: false description: > 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. schema: type: string minLength: 1 maxLength: 160 schemas: InviteSessionRequest: type: object description: > 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. properties: delivery: type: string enum: - email - none default: email description: > `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. locale: type: string description: BCP-47-like tag echoed into the email template (e.g. en-US). org_name: type: string description: >- Organization name shown in the invite email (overrides the theme company name). redirect_base_url: type: string format: uri description: > 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. DirectInviteSessionResponse: type: object required: - verify_url - invite_expires_at properties: verify_url: type: string format: uri description: > Verification URL containing the one-time invite credential only in its fragment. Returned once and never persisted or logged. invite_expires_at: type: string format: date-time InviteSessionResponse: type: object required: - invited - invite_expires_at properties: invited: type: boolean description: Always true on the 202 path. No credential material is returned. invite_expires_at: type: string format: date-time delivery_state: type: string enum: - sent description: > Durable delivery state of the emailed invite. Present only on the white-label invitation-email outbox path; `sent` means the provider durably accepted the message, which is also the point at which the successor credential replaces the previously emailed link. A provider outcome that cannot be confirmed returns 502 `invite_delivery_retrying` and leaves the prior link usable. Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string example: idv_session_not_found message: type: string responses: BadRequest: description: Validation error content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: >- Missing or invalid credentials (uniform for token plane, no existence oracle) content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Session/workflow not found or out of scope (indistinguishable by design) content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: Domain-state conflict (e.g. concurrent update, illegal transition) content: application/json: schema: $ref: '#/components/schemas/Error' BadGateway: description: >- Delivery failure at the verification email service; the invite is persisted and can be retried content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: applicationApiKey: type: apiKey in: header name: Authorization description: >- `Authorization: Api-Key ` (legacy `X-Api-Key` also accepted). dashboardUserToken: type: apiKey in: header name: x-user-token description: > Dashboard session token for Minerva dashboard users. Management routes accept it alongside an application API key; any in-scope workspace user (member or above) can read sessions and record review decisions, while workflow and theme writes need a management-capable role. Send it with the `x-tenant-id` and `x-workspace-id` headers; a header/access mismatch is refused with 403, and when dashboard authentication is disabled (the default) any request carrying this header gets a uniform 401. ````