Hosted sessions

A hosted session is the easiest way to collect documents. You create the request server-side, then ask Certivant for a session URL and hand it to the applicant. Certivant handles document upload, camera capture, liveness, OCR feedback, and retries — you just wait for the webhook.

When to use a session

Most integrations use sessions. Document-upload via API is escape hatch for special cases.

Generate a session URL

POST /api/v1/kyc/requests/:id/session-url    Scope: kyc:write

The request must be in PENDING_UPLOAD state.

Request body

{
  "expiresInHours": 72,
  "redirectUrl": "https://yourapp.example.com/onboarding/complete"
}

Response

{
  "sessionUrl": "https://app.certivant.com/s/01HZ7K8Y...",
  "expiresAt": "2026-05-30T10:00:00.000Z"
}

The URL contains a one-time-use signed token. After it expires (or after the applicant submits), it's invalidated. Generate a fresh one if the applicant needs another attempt.

The applicant flow

graph LR
  A[You email the session URL] --> B[Applicant clicks]
  B --> C[Welcome screen with your branding]
  C --> D[Capture front of ID]
  D --> E[Capture back of ID]
  E --> F[Capture selfie + liveness]
  F --> G[Confirm details extracted from ID]
  G --> H[Submit]
  H --> I[Thank-you page]
  I --> J{redirectUrl set?}
  J -->|yes| K[Redirect to your URL]
  J -->|no| L[Stay on Certivant page]
  H -.->|automatically| M[POST /submit fires]
  M -.->|webhook| N[kyc.request.processing]

The applicant does not need an account to use the session URL — Certivant doesn't issue them a login. They click, complete the flow, and leave. All state lives on the request, not on a user record.

Branding and white-label

The hosted UI picks up your organization's white-label settings — logo, brand colour, support email, custom domain if you configured one. Configure these once at Settings → White-label in the dashboard; every session inherits them.

Custom domains

By default the hosted session and form URLs live on the shared Certivant host (app.certivant.com/s/…). If you want them on your own domain (verify.yourcompany.com instead), set up a custom domain at Settings → White-label → Custom domain. This only moves the applicant-facing links — the API host and your /api/v1/kyc base path are unchanged, and your organization is still identified by your API key.

Mobile vs desktop

The session is responsive and works on phones, tablets, and desktops. Document capture uses the device camera on mobile; on desktop, Certivant prompts the applicant to switch to their phone via a QR code so liveness and document scanning use the better camera. This is automatic — your integration doesn't need to detect anything.

What happens after submit

When the applicant clicks Submit on the hosted page:

1. Certivant calls POST /requests/:id/submit internally on behalf of the applicant.
2. The request moves to PROCESSING.
3. The first webhook fires: kyc.request.processing.
4. Processing finishes (usually within seconds). A second webhook fires: kyc.request.approved, kyc.request.rejected, or kyc.request.escalated.
5. If you provided redirectUrl, the applicant is sent there. Otherwise they see a thank-you page.

Your backend should wait for the webhook — do not poll the request endpoint to detect completion. See Webhooks.

Reusing a session URL after rejection

If the request is rejected and you call POST /requests/:id/resubmit, the existing session URL is not reactivated. Generate a new one:

# 1. Reset the rejected request
curl -X POST https://app.certivant.com/api/v1/kyc/requests/req_.../resubmit \
  -H "Authorization: Bearer ck_live_..."

# 2. Generate a fresh session URL
curl -X POST https://app.certivant.com/api/v1/kyc/requests/req_.../session-url \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{"expiresInHours": 24}'

Then email the new URL to the applicant. Tip: use the same externalRef so your database row stays correlated.

Forms as an alternative

If you need to collect structured data (not just documents) — answers to compliance questionnaires, source-of-funds details, additional KYB fields — use Forms instead of (or in addition to) the session. Forms live in the dashboard at KYC → Forms, and each form has a public submission URL: https://app.certivant.com/forms/:slug.

Forms automatically create a KYC request on submission, attach the form responses as metadata, and trigger the same webhooks. See the tenant docs at Forms for setup. Developers don't usually interact with forms via API — the dashboard form builder is the intended interface.

Errors

• 400 BAD_REQUEST — request is not in PENDING_UPLOAD. You can only generate session URLs for requests waiting on documents.
• 400 VALIDATION_ERROR — expiresInHours outside the 1–168 range, or redirectUrl is not a valid URL.

Security notes

• The session URL contains a signed token — anyone with the URL can complete the verification. Treat it like a password reset link: send it directly to the applicant via a channel only they can access.
• Use short expiresInHours (24 or 48) for high-risk flows. Use longer expiry only when the applicant is expected to have time to gather documents.
• After a session expires unused, the underlying request stays in PENDING_UPLOAD. Generate a fresh URL or contact the applicant to resend.