IDV Integration Guide

​

How it fits together

• A profile is the customer record in Minerva, created through the Profiles API.
• An IDV session is one verification attempt tied to a profile. It carries the capture flow (consent, liveness and document captures, questionnaire) and the review outcome.
• Review is the decision layer. Most sessions pass without a human; some are held for an analyst in your Minerva workspace to accept or reject.
• Webhooks tell your systems when a session changes state, so you do not have to poll.

​

Before you begin

• You need an application API key for your workspace. Create one from the Developers page; API Keys has the walkthrough. Keys are server-side credentials, so never ship one in a browser or a mobile app.
• You need a profile for the customer. If it does not exist yet, create it first (Step 1).
• Every endpoint in this guide uses the base URL https://api.gominerva.com/idv/v1 and authenticates with Authorization: Api-Key <YOUR_API_KEY>.

​

Step 1: Create the profile

• Create the profile on its own with POST https://api.gominerva.com/clm/v1/profiles, then create the session yourself with the rest of this guide. See Create a profile.
• Create and onboard the profile in one call with POST https://api.gominerva.com/clm/v1/onboarding/profiles, using an onboarding block to enable screening, identity verification, or both. See Create and screen a profile.

{
  "name": "Alex Morgan",
  "kind": "individual",
  "email": "alex.morgan@example.com",
  "onboarding": {
    "screening": { "enabled": true, "feeds": ["Sanctions"] },
    "idv": { "enabled": true, "workflowId": "idvw_5f8c2a1b" },
    "sequence": "screening_first"
  }
}

• Enabling IDV requires an email address on the profile and a workflow: either an explicit workflowId or your workspace’s default.
• sequence is one of screening_first (the default), idv_first, or parallel.
• When IDV onboarding is enabled, Minerva starts the verification session for the profile as part of the run. The rest of this guide covers the explicit flow, where your backend creates the session and delivers the invite itself.

​

Step 2: Create the IDV session

POST https://api.gominerva.com/idv/v1/sessions

{
  "profile_id": "66c391b92888a0db5cc6d3f6",
  "workflow": "liveness_and_id",
  "idempotency_key": "onboard-alex-001"
}

• profile_id is required. The profile must already exist in your workspace: a missing profile returns 400 idv_profile_not_found, and an unavailable profiles service returns 503 idv_profile_lookup_unavailable.
• workflow picks a preset flow: liveness_and_id, liveness_only, or id_only. You can instead pass a workflow_id you configured, pass an inline steps manifest, or omit all three to use your workspace’s default workflow.
• idempotency_key is an optional retry key (1 to 160 characters of letters, digits, and ., _, :, -). A retry with the same key and the same request returns the original session instead of creating a second one; reusing the key for a materially different request returns 409 idv_session_idempotency_conflict.

{
  "data": {
    "id": "idv-2cdf8b5c8b3db8a1d6f5d4ce9d46a63f",
    "profile_id": "66c391b92888a0db5cc6d3f6",
    "status": "collecting_artifacts",
    "review_status": "request_sent",
    "capture_manifest": {
      "workflow": "liveness_and_id",
      "required_kinds": ["liveness_front", "id_front", "id_back"]
    }
  },
  "session_token": "idvs_9c1f...",
  "token_expires_at": "2026-09-25T19:05:00Z"
}

​

Step 3: Deliver the verification flow

​

Email invite

curl -X POST https://api.gominerva.com/idv/v1/sessions/idv-2cdf8b5c8b3db8a1d6f5d4ce9d46a63f/invite \
  -H "Authorization: Api-Key $MINERVA_API_KEY" \
  -H "Idempotency-Key: onboard-alex-001-invite" \
  -H "Content-Type: application/json" \
  -d '{ "delivery": "email" }'

• The recipient is always the email address on the linked profile, resolved at send time. The request does not accept a recipient. A profile without an email returns 422 idv_profile_email_missing.
• Success is a 202 with invited: true and invite_expires_at. A delivery_state of sent means the email provider durably accepted the message.
• The emailed link is valid for 72 hours by default and stays reusable within that window, so a customer can reopen the email or continue on another device.
• Pass an Idempotency-Key header to make email retries safe (direct links ignore it; without a header Minerva generates its own key). A replay with the same key never sends a second email; it reports the delivery’s durable state instead: 202 with delivery_state: "sent" once the provider has accepted the message, or 502 invite_delivery_failed otherwise. While a send is still in flight, including an ambiguous provider outcome, a different key is refused with 409 idv_state_conflict; retry once it settles. After the earlier send has settled (delivered or terminally failed), a new key can replace it and email again.
• Optional presentation fields: locale and org_name (which overrides the theme company name in the email).

​

Direct link

curl -X POST https://api.gominerva.com/idv/v1/sessions/idv-2cdf8b5c8b3db8a1d6f5d4ce9d46a63f/invite \
  -H "Authorization: Api-Key $MINERVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "delivery": "none" }'

• The response is a 200 with verify_url and invite_expires_at. Hand the link to the user immediately: redirect to it or open it in a web view.
• Direct links work only with application keys. Dashboard-authenticated callers receive 403 idv_direct_invite_forbidden.
• The link is single-use and expires within 15 minutes (900 seconds, and the lifetime cannot be raised).
• The one-time credential sits in the URL fragment (#code=...), which browsers never send to servers and Minerva never logs. Treat the whole URL as a secret.
• If Minerva cannot construct a secure public link, the request fails closed with 503 idv_direct_invite_unavailable.

​

Which mode should you use?

​

Embed the hosted flow on your site

1. Open Configuration → Verification Workflows in the Minerva dashboard and edit the workflow.
2. Under Embedding security, turn on Allow iframe embedding. Enter each Allowed parent origin on its own line, for example https://example.com, then save the workflow. Add https://www.example.com separately if you use that origin too; the two origins do not match each other.
3. Have your backend create a new session with this workflow_id and request a direct link with delivery: "none". Put the returned verify_url in the iframe immediately. The direct link is single-use and expires within 15 minutes.

<iframe
  src="VERIFY_URL_FROM_DIRECT_INVITE"
  title="Identity verification"
  allow="camera"
></iframe>

​

Optional questionnaire-only approval

​

What the customer sees

1. Opens the link from the email, or arrives through your handoff.
2. Reviews and accepts the consent notice.
3. Completes the workflow steps, for example a questionnaire, liveness selfie, or photos of an identity document.
4. Submits the session for assessment.

​

Step 4: Track progress

​

Flow status

​

Review status

​

Step 5: Cancel a session

curl -X POST https://api.gominerva.com/idv/v1/sessions/idv-2cdf8b5c8b3db8a1d6f5d4ce9d46a63f/cancel \
  -H "Authorization: Api-Key $MINERVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Customer restarted onboarding" }'

• Cancellation is irreversible and moves the session to canceled.
• It consumes the capture token and the invite, so the link stops working for further capture.
• Re-canceling an already canceled session is a no-op, not an error.
• A session that is currently being assessed cannot be canceled: the call returns 409 idv_state_conflict (the same code covers other terminal states).
• The optional reason is recorded internally and is never shown to the customer.

​

Step 6: Read results and review outcomes

​

Structured results

• The document record: type, issuing country and subdivision, and confidence.
• OCR field values with per-field confidence.
• Questionnaire answers, with the step and question each answer belongs to.
• Any mismatch details between the captured data and the profile.

• Every access, success or denial, is written to an audit log before the response is returned. If the audit write fails, the request fails closed with no data.
• The endpoint is available to application keys and in-scope dashboard users only. It is never reachable with a session’s capture credential.

​

Review

POST https://api.gominerva.com/idv/v1/sessions/idv-2cdf8b5c8b3db8a1d6f5d4ce9d46a63f/review

{
  "status": "accepted",
  "note": "Reviewed against source documents"
}

​

Worked example: email invite

1. Create the profile with the Profiles API:

curl -X POST https://api.gominerva.com/clm/v1/profiles \
  -H "Authorization: Api-Key $MINERVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alex Morgan",
    "kind": "individual",
    "email": "alex.morgan@example.com"
  }'

{
  "msg": "OK",
  "result": {
    "profile": {
      "id": "66c391b92888a0db5cc6d3f6",
      "name": "Alex Morgan",
      "status": "not_screened"
    }
  }
}

2. Create the IDV session for that profile:

curl -X POST https://api.gominerva.com/idv/v1/sessions \
  -H "Authorization: Api-Key $MINERVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "66c391b92888a0db5cc6d3f6",
    "workflow": "liveness_and_id",
    "idempotency_key": "onboard-alex-001"
  }'

{
  "data": {
    "id": "idv-2cdf8b5c8b3db8a1d6f5d4ce9d46a63f",
    "profile_id": "66c391b92888a0db5cc6d3f6",
    "status": "collecting_artifacts",
    "review_status": "request_sent"
  },
  "session_token": "idvs_9c1f...",
  "token_expires_at": "2026-09-25T19:05:00Z"
}

3. Send the invite email:

curl -X POST https://api.gominerva.com/idv/v1/sessions/idv-2cdf8b5c8b3db8a1d6f5d4ce9d46a63f/invite \
  -H "Authorization: Api-Key $MINERVA_API_KEY" \
  -H "Idempotency-Key: onboard-alex-001-invite" \
  -H "Content-Type: application/json" \
  -d '{ "delivery": "email", "locale": "en", "org_name": "Example Bank" }'

{
  "invited": true,
  "invite_expires_at": "2026-09-28T18:30:00Z",
  "delivery_state": "sent"
}

4. Track progress with GET /sessions/{sessionId} or webhooks, and read the results with GET /sessions/{sessionId}/data when the assessment is done.

​

Worked example: direct link

curl -X POST https://api.gominerva.com/idv/v1/sessions/idv-2cdf8b5c8b3db8a1d6f5d4ce9d46a63f/invite \
  -H "Authorization: Api-Key $MINERVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "delivery": "none" }'

{
  "verify_url": "https://idv.gominerva.com/verify/idv-2cdf8b5c8b3db8a1d6f5d4ce9d46a63f#code=idvi_...",
  "invite_expires_at": "2026-09-25T19:05:00Z"
}

​

Web and mobile integration walkthrough

1. The customer taps a button in your web or mobile app. The tap calls your backend, never Minerva directly.
2. Your backend creates the profile (or reuses an existing one), creates the IDV session, and sends the email invite.
3. The customer receives the email, opens the verification page, consents, completes the capture steps, and submits.
4. Minerva assesses the session. Your backend receives IDV webhooks: idv.session.completed with the outcome (idv.session.approved, idv.session.requires_review, or idv.session.failed), and idv.document.captured for each uploaded artifact.
5. Update the customer’s experience: show something like “verification received, we are finishing your setup.” Never surface flags, review states, or analyst details to the customer.
6. If the session was held for review, an analyst reviews it in your Minerva workspace and marks the profile accepted or rejected. That disposition closes the loop with profile_onboarding.completed (and profile_status_updated), your signal to continue or stop the onboarding flow. Every onboarding delivery carries externalId (your reference), so you can close the loop against the same customer record you started. When the session runs inside a Minerva onboarding run, the delivery also carries the session’s stable sessionId under meta.idv; for per-session correlation, the IDV session events are the authoritative source.

// Server-side only. Never call Minerva from the browser or the app with an API key.
const MINERVA = "https://api.gominerva.com";

export async function startIdentityVerification(input: {
  name: string;
  email: string;
}) {
  const auth = { Authorization: `Api-Key ${process.env.MINERVA_API_KEY}` };

  // 1. Create the profile.
  const profileResponse = await fetch(`${MINERVA}/clm/v1/profiles`, {
    method: "POST",
    headers: { ...auth, "Content-Type": "application/json" },
    body: JSON.stringify({
      name: input.name,
      kind: "individual",
      email: input.email,
    }),
  });
  const { result } = await profileResponse.json();

  // 2. Create the IDV session. Keep the key stable so retries adopt the same
  // session; use a fresh key when you intentionally start a new attempt.
  const sessionResponse = await fetch(`${MINERVA}/idv/v1/sessions`, {
    method: "POST",
    headers: { ...auth, "Content-Type": "application/json" },
    body: JSON.stringify({
      profile_id: result.profile.id,
      workflow: "liveness_and_id",
      idempotency_key: `verify-${result.profile.id}`,
    }),
  });
  const session = await sessionResponse.json();

  // 3. Send the invite email to the customer.
  await fetch(`${MINERVA}/idv/v1/sessions/${session.data.id}/invite`, {
    method: "POST",
    headers: { ...auth, "Content-Type": "application/json" },
    body: JSON.stringify({ delivery: "email" }),
  });

  return session.data.id;
}

export async function handleMinervaWebhook(request: Request) {
  // 1. Validate the key on every delivery before reading the body.
  if (
    request.headers.get("x-webhook-key") !== process.env.MINERVA_WEBHOOK_KEY
  ) {
    return new Response("unauthorized", { status: 401 });
  }

  const { event } = await request.json();

  // 2. Deliveries are at-least-once and can arrive out of order, so process
  // every event idempotently.
  if (event.kind === "idv") {
    // `sessionId` identifies the session; `externalId` (when present) is your
    // own reference for the customer.
    const { sessionId, profileId, externalId, reviewStatus } = event.meta;
    const firstDelivery = await recordEventOnce(
      sessionId,
      event.value,
      event.meta.occurredAt,
    );
    if (firstDelivery) {
      await updateVerificationState(profileId, externalId, reviewStatus);
    }
  }

  if (
    event.kind === "onboarding" &&
    event.value === "profile_onboarding.completed"
  ) {
    await finishOnboarding(event.meta.profileId, event.meta.outcome);
  }

  // 3. Acknowledge quickly, and keep the response body small.
  return new Response(null, { status: 204 });
}

​

Errors and limits

• 400: returned as idv_profile_id_required or idv_profile_id_invalid when profile_id is missing or malformed on session create.
• 400: returned as idv_profile_not_found when the profile does not exist in the calling workspace.
• 400: returned as schema_validation_failed when the request body fails schema validation.
• 401: returned as missing_authentication when the request carries no credentials, or as unauthorized when the key is rejected. Responses never reveal whether an object exists.
• 403: returned as idv_direct_invite_forbidden when delivery: "none" is requested without an application principal.
• 404: returned as idv_session_not_found when the session does not exist in the calling workspace.
• 409: returned as idv_state_conflict when the session is not in a state that allows the action, for example canceling while the assessment runs, or a new invite uses a different Idempotency-Key while a send is still in flight.
• 409: returned as idv_session_idempotency_conflict when an idempotency key was reused for a materially different create.
• 409: returned as idv_invite_conflict when the invite state changed before the request completed; retry the request.
• 409: returned as idv_review_terminal when a review decision was submitted for a session that is already accepted or rejected.
• 409: returned as idv_review_invalid_transition when the review decision is not admissible from the session’s current review state.
• 409: returned as idv_session_unavailable when the session cannot be changed right now. It applies to capture calls (acquire, consent, artifact reservation and upload, step answers, skip, document type, submit) and to cancel and review. No change was made; re-read the session before you retry the request.
• 409: returned as idv_session_consent_required by capture calls (acquire, artifact reservation and upload, step answers, skip, document type, submit) when the session has no recorded consent. The consent call itself never returns it. There are two causes:
  • The customer has not recorded consent yet. Record consent, then retry the call.
  • The session has no privacy contact, because it was created from a preset workflow, from inline steps, or with no active default workflow to apply. Consent cannot be recorded for such a session, and the consent call returns 409 idv_state_conflict. Create a new session with a workflow_id whose workflow sets privacy_contact_email.
• 422: returned as idv_profile_email_missing when an email invite was requested but the linked profile has no email address.
• 502: returned as invite_delivery_failed or invite_delivery_retrying when the email provider could not confirm delivery. The invite stays valid; retry the invite call.
• 503: returned as idv_profile_lookup_unavailable when the profiles service was unavailable and the request failed closed.
• 503: returned as idv_direct_invite_unavailable when no secure public verify base is available for a direct link.

• The capture token (session_token) lives 15 minutes by default.
• Email invites live 72 hours by default; direct links at most 15 minutes.
• The sessions list returns 50 records per page by default; the workflow and theme lists return 20. Every list endpoint caps at 100 (larger values are clamped).
• Each workspace can keep up to 10 destinations by default. Enterprise customers can request more.

​

Security

• Keep application API keys server-side. The hosted verification page authenticates the customer with its own capture or invite credential, so your client apps never need a key.
• Validate x-webhook-key on every delivery before processing the body, and acknowledge quickly with a small 2xx response.
• Read verification results only through the audited GET /sessions/{sessionId}/data endpoint, and store what you need under your own data-protection policy. Document images and OCR text are sensitive personal data.
• Never surface review states, flags, or analyst details to the customer; the customer-facing flow deliberately does not expose them.
• Use a separate application per environment, and rotate or deactivate keys when integrations change.

​

Related documentation

• API Keys: create an application key and configure webhooks from the Developers page.
• Webhooks: the delivery contract, payload shapes, and retry schedule.
• Screening Integration Guide: interpret screening results alongside identity verification.
• Profiles: the customer record an IDV session is tied to.