Skip to main content

Hosted UI vs direct API

Zyphe supports two ways to collect document and biometric evidence:

  1. Hosted / WebView flow — Zyphe’s verification UI captures the user (recommended default).
  2. Direct API upload — your app captures images/video and your backend submits them to the step-completion APIs.

Both paths still use flows, verification requests, webhooks, and the same result model. They differ in who owns capture UX and which frontend-side protections you get for free.

Comparison​

Hosted UI / WebViewDirect API upload
User experienceZyphe screens (iframe, redirect, or mobile WebView)Your own camera / upload UI
Session creationBackend creates VR + opens session URLBackend creates VR, then calls step endpoints
Document capture aidsDocument-in-frame guidance, quality feedback in Zyphe UIYou implement framing, blur/glare UX, retries
Device / client signalsCollected by the hosted frontend where applicablePartially reduced or absent vs hosted path
LivenessFull hosted active liveness challenge UX out of the boxYou must implement challenge consumption and asset upload; see below
Engineering effortLow–mediumHigh
App release couplingLow (UI updates on Zyphe side)High (your capture code)
Best forAlmost all production KYC/KYB onboardingSpecialized pipelines, existing capture stacks, constrained environments

Liveness constraints​

The hosted flow walks the user through active liveness (challenge + capture) when the flow is configured for it.

If you complete liveness only through the API:

  1. Call liveness-challenge for the verification request.
  2. Inspect the returned mode (ACTIVE vs PASSIVE).
  3. Upload exactly the assets required (calibration image; for active, video + movement images).

Passive liveness (selfie-only, no head-movement challenge) is controlled by organization configuration and is not something every tenant can toggle alone. Active liveness via pure API is only viable if you fully implement the challenge protocol; most teams that need active liveness should use the hosted / WebView path instead of re-building the challenge UI.

Compliance-sensitive choice

If your policy requires active liveness and you are not prepared to implement the full challenge + multi-asset upload flow, do not choose pure API capture. Use Backend API integration + Mobile WebView or the Browser SDK.

Decision guide​

Choose hosted UI / WebView if…​

  • You want production KYC quickly with the least client code
  • You need active liveness and anti-spoof UX without building it yourself
  • You integrate mobile (there is no native SDK)
  • You want capture and flow improvements without app store releases
  • You are fine opening verify.zyphe.com in a WebView, iframe, or redirect

Choose direct API upload if…​

  • You already own a document-capture pipeline and accept re-validating quality yourself
  • You only need document checks (and understand liveness limitations above)
  • Your environment cannot embed a WebView but can send images from a secure backend
  • You have engineering capacity to call next-step, document selection, process document, and process liveness in order
  • You need zero mobile/web engineering and can send users a Zyphe URL

See also Choosing an integration method.

Direct API outline (advanced)​

High-level sequence when you own capture:

  1. POST /sdk/flow/{flowId}/vr/create?sandbox=… — create the verification request
  2. GET …/vr/next-step — discover the next step type
  3. Complete steps in order, for example:
    • document selection → process-dv-selection
    • document images → process-dv-document
    • liveness → liveness-challenge then process-dv-liveness
  4. Consume webhooks; export media via Export API if needed

Schemas and paths: OpenAPI. Node helpers: Complete verification steps.