Shape of the API
Three hosts, two key types, one sandbox flag.
Most failed first integrations point the client at the wrong host or ship the wrong key. This is the whole map.
api.zyphe.com
API base URL
Every backend call, under /sdk/... Send x-api-key here.
verify.zyphe.com
Hosted verification UI and dashboard
Open the composed session URL here in a browser, iframe or WebView. Sandbox sessions use the /sandbox/flow/... path.
docs.zyphe.com
Documentation
Human and machine readable docs, including llms.txt and the OpenAPI reference. Never send API traffic here.
| Key | Where it runs | What it can do |
|---|---|---|
| zyphe_sk_ Secret key | Your backend, any language | Creates sessions, completes steps, reads results, KYB and AML helpers, Export API. |
| zyphe_pk_ Publishable key | The browser SDK in your page, with allowed origins set | Limited permissions; never a substitute for a secret key on a server. |
| none Mobile app binary | iOS, Android, React Native, Flutter | Ships no key. The app asks your backend for a session URL and opens it in a WebView. |
Sandbox and production share these hosts. The difference is sandbox=true on every API call and the /sandbox/flow/ path on the hosted UI. Details: environment setup, API keys.
Backend integration
Create a session, open the URL, verify the webhook.
The whole production path in three snippets, taken from the backend integration recipe. Any language that can send HTTPS works; the npm packages are optional.
1. Create a verification request
POST to the flow with your secret key. Provide at least one identity: an email, or an external ID or wallet credential. customData round-trips into the webhook so you can correlate the result with your own records.
curl -X POST "https://api.zyphe.com/sdk/flow/$ZYPHE_FLOW_ID/vr/create?sandbox=true" \
-H "x-api-key: $ZYPHE_SECRET_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "applicant@example.com",
"customData": { "externalUserId": "user_123", "plan": "pro" }
}'2. Compose the session URL
The response carries the verification request id, a session token and a short-lived access signature. Put them on the hosted UI URL and open it: redirect, iframe, or WebView. The browser SDK does this for you on the web.
# sandbox
https://verify.zyphe.com/sandbox/flow/<flowSlug>?zypheVr=<verificationRequest.id>&zypheToken=<zypheToken>&zypheAccessSig=<zypheAccessSig>&zypheEmail=<email>&zypheFullscreen=true
# production (sandbox=false on the create call)
https://verify.zyphe.com/flow/<flowSlug>?zypheVr=...&zypheToken=...&zypheAccessSig=...3. Or embed with the browser SDK
One function creates the session and mounts the iframe with camera permissions. Treat onSuccess as submission, never as approval; the decision arrives by webhook.
import { startVerificationSession } from '@zyphe-sdk/browser'
const result = await startVerificationSession({
containerElement: document.getElementById('kyc'),
flowParams: { email: 'user@example.com', flowId: 'your-flow-id', isSandbox: true },
opts: { apiKey: 'zyphe_pk_...' },
eventHandlers: {
onSuccess: (m) => console.log('completed step', m.flowStep),
onFailure: (m) => console.error(m.error),
},
})
if (result.error) showRetry(result.error)4. Verify and acknowledge the webhook
Endpoints belong to your organisation, subscribe to the events they handle and can be scoped to one flow or all. Signatures are HMAC-SHA256 over the raw body.
import { verifyWebhookSignatureHeader } from '@zyphe-sdk/node'
// Use the raw request body, before any JSON parsing.
const ok = verifyWebhookSignatureHeader(
process.env.ZYPHE_WEBHOOK_SECRET_HEX,
rawBody,
req.headers['x-signature'], // t=1234567890,v0=abcdef...
)
if (!ok) return res.status(401).end()
res.status(200).end() // acknowledge first, process asynchronously
queue.push(JSON.parse(rawBody)) // deliveries are retried: make handling idempotentFull recipe: backend API integration. Webhook contract: webhook integration, signature, statuses and codes.
SDKs
Packages for the two runtimes that need them, HTTP for everything else.
Published on npm and documented with their source of truth on docs.zyphe.com.
@zyphe-sdk/browser
Creates a session and embeds the hosted verification iframe in your web app, with camera permissions configured and success and failure events. Uses a publishable key. Non-throwing: returns { error, data }.
@zyphe-sdk/node
Server-side session creation, hosted URL construction, HMAC-SHA256 webhook signature verification, step-completion helpers and Export API helpers for result details and media.
@zyphe-sdk/core
The environment-agnostic package both of the above pass through. Usable on a React Native backend, never inside the app binary.
React Native guide
WebView plus permissions plus a backend sample, for Expo and bare React Native. There is no native iOS or Android SDK by design; the hosted flow ships capture and liveness improvements without an app store release.
OpenAPI reference
Every /sdk route with schemas: create verification request, next step, document selection, document processing, liveness challenge, flow results, KYB and AML helpers.
MCP server
Create and configure flows from an agent or IDE through the Model Context Protocol server, the same operations the dashboard exposes.
Mobile onboarding
Mobile is a WebView on the hosted flow, and that is a feature.
Identity verification APIs that support mobile onboarding usually mean a native capture SDK you must update every time the attack surface moves. Zyphe puts capture, liveness and anti-spoofing on the hosted UI and leaves your app with a URL to open.
- 1
Your backend creates the session
POST /sdk/flow/{flowId}/vr/create with the secret key. Return only the composed verify.zyphe.com URL to the app. The secret key never leaves your server.
- 2
Your app opens a WebView
WKWebView on iOS, WebView on Android, the WebView component in React Native or Flutter. Append zypheFullscreen=true so the flow fills the screen. Request camera permission, and microphone if the flow uses active liveness, before opening it.
- 3
The user completes capture on the hosted UI
Document-in-frame guidance, glare and blur feedback, active liveness challenges and anti-spoof logic all run on Zyphe-controlled UI and backend, so they update without a release.
- 4
Your backend receives the webhook
The webhook is the source of truth, not the WebView navigation callback. Document images are not in the webhook by default; fetch them through the Export API if your policy requires storing them, and read the security page before you do.
Guides: mobile integration, React Native, hosted UI vs direct API for the cases where you own capture.
Sandbox
Sandbox on sign-up, and what it does and does not cost.
Same hosts, one flag
Sandbox is not a separate base URL. It is sandbox=true on every API call, isSandbox on the npm helpers, and the /sandbox/flow/... path on the hosted UI. The three must agree or the API returns flow_not_found or verification_request_not_found.
Open on sign-up
Create an account, switch the dashboard to sandbox, build a flow from a template, run a verification on yourself and receive a webhook, with no contract and no production data. Endpoints registered in sandbox are separate from production ones.
What sandbox costs
Sandbox runs on people internal to your organisation, anyone on a team member's email domain, are recorded at zero credits. Runs on external addresses are billed like production from the same balance, and during a trial every sandbox event consumes trial credits.
Go-live is a checklist
Generate production keys, point a production webhook endpoint at production infrastructure and confirm signature verification, enable the products you need in billing, switch sandbox to false, and map statuses and failure reasons from the reference.
Reference: sandbox mode, sandbox and go-live checklist. Pricing for production volume is on the pricing page.
Beyond KYC
KYB and screening run in the same flow, on the same key.
KYB flows
A KYB flow collects business information and incorporation documents, captures beneficial owners and optionally directors, cross-checks the submission against the documents and the official register, and verifies each owner through a linked KYC flow. Ownership discovery can find the owners from the registers automatically within a per-verification credit budget. Results arrive on verification.kyb.completed, verification.kyb.failed and verification.kyb.review under data.kyb. Product page: KYB software.
Screening and agent modes
Company and owner screening runs PEP and sanctions checks before an operator approves the result. The KYB and AML agents can be disabled, set to suggest only, or allowed to moderate clean matches automatically, with anything partial, mismatched or vetoed by the deterministic guard held for a human. Product pages: KYC software, AML software.
What you store
Webhooks carry results, scores and your identifiers, not document images. Documents and biometrics are processed transiently and held encrypted in the user's own vault; your system keeps the verification result, logs and proofs. How that works, and the data residency position, is on the security and data handling page.
Developer questions, answered
The questions engineering teams ask before the first sandbox call.
Yes. Sign up, switch the dashboard to sandbox and generate keys from the API keys page. Sandbox uses the same API host with sandbox=true on each call and the /sandbox/flow path on the hosted UI. Verifying yourself or anyone on your company email domain costs no credits.
The public link needs no code: share a hosted flow URL and receive results in the dashboard or by webhook. The backend integration is one POST to create a session, a URL to open, and one webhook handler to verify and acknowledge. The go-live checklist in the docs covers keys, endpoints and status mapping.
@zyphe-sdk/browser for embedding the hosted flow in a web page, @zyphe-sdk/node for server-side session creation and webhook verification, @zyphe-sdk/core underneath both, a React Native guide built on WebView, an OpenAPI reference for any language over plain HTTP, and an MCP server for agent and IDE driven flow configuration.
No, by design. Mobile apps ask their own backend for a session URL and open it in a WebView with camera permission. Capture guidance, active liveness and anti-spoof logic stay on the hosted UI, so they improve without an app store release, and the secret key never ships in the binary.
Every delivery carries an X-Signature header of the form t=<timestamp>,v0=<hmac> computed with HMAC-SHA256 over the raw request body with the endpoint's signing secret. Verify it on the exact bytes received before parsing, reject stale timestamps, return 2xx promptly and make processing idempotent because failed deliveries are retried. @zyphe-sdk/node includes the verifier.
No. Webhooks carry statuses, scores, extracted fields and your customData. Full document media is available only through the Export API with a secret key, and only when enabled for your organisation. Most integrations never fetch images, which is the point: the record you keep is the result, not the passport.
Page reviewed against docs.zyphe.com on 2026-09-18. The docs win where they differ.
Book a demo
Run the first verification in the sandbox today.
Sign up, build a flow from a template, verify yourself at zero credits and receive the webhook. When it works end to end, the go-live checklist takes you to production. Or book a demo and we will walk the integration with your team.