SDKs & Libraries

Official SDKs for integrating YeboVerify into your applications. All source lives under the omegathesecond GitHub org.

Available SDKs

Platform	Repository	Use case
Flutter	`yeboverify-flutter`	iOS + Android via Flutter
Kotlin	`yeboverify-kotlin`	Native Android
Swift	`yeboverify-swift`	Native iOS
React Native	`yeboverify-react-native`	iOS + Android via React Native
React	`yeboverify-react`	React web apps + embeddable widgets
Node	`yeboverify-node`	Server-side integration

Don't see your stack? The REST API is documented in full at API Reference — every SDK is just a thin wrapper. If you're on Python, Go, PHP, Ruby, .NET, or anything else, the API works fine via direct HTTP. Open an issue on any SDK repo if you'd like a first-party SDK for your platform.

Mobile (Flutter / Kotlin / Swift / React Native)

These SDKs handle the camera capture + liveness flow on-device, then submit to YeboVerify's API. They're designed for the hosted-flow pattern — your backend creates a session, you hand the token to the SDK, and the SDK takes care of the user-facing capture UI.

See Mobile Integration for the full per-platform integration walkthrough.

Flutter

yaml

# pubspec.yaml
dependencies:
  yeboverify_flutter:
    git:
      url: https://github.com/omegathesecond/yeboverify-flutter.git

dart

import 'package:yeboverify_flutter/yeboverify_flutter.dart';

YeboVerifyButton(
  apiKey: 'yv_live_YOUR_API_KEY',
  externalRef: currentUser.id,
  onSuccess: (result) => print('Verified: ${result.names}'),
)

Kotlin (Android)

Add via JitPack or Gradle source dependency. See the Kotlin SDK README for the current installation snippet.

Swift (iOS)

Add via Swift Package Manager:

https://github.com/omegathesecond/yeboverify-swift

See the Swift SDK README for usage.

React Native

bash

npm install github:omegathesecond/yeboverify-react-native

See the React Native SDK README for usage.

Web (React)

A single drop-in <YeboVerifyWidget /> component for browser-based ID + selfie capture. See Embeddable Widgets for the full prop reference, liveness behavior, and why it deliberately has no KYB support.

bash

npm install github:omegathesecond/yeboverify-react

Not published to npm yet — installs from GitHub, but its package.json name is @yeboverify/react, so it imports exactly as shown below.

jsx

import { YeboVerifyWidget } from '@yeboverify/react';

<YeboVerifyWidget
  apiKey="yvk_your_api_key"
  externalRef={user.id}
  onSubmit={(verificationId) => console.log('Submitted:', verificationId)}
  onResult={(result) => { if (result.decision === 'approved') unlockAccess(); }}
  onError={(err) => toast.error(err.message)}
/>

YeboVerifyWidget is the only export — there is no useYeboVerify hook and no separate modal component.

Server (Node)

For your backend — creating sessions, fetching verification results, verifying webhook signatures.

bash

npm install @yeboverify/node

javascript

import { YeboVerifyClient } from '@yeboverify/node';

const yv = new YeboVerifyClient({
  apiKey: process.env.YEBOVERIFY_API_KEY,  // yv_live_... or yv_test_...
});

// Create a hosted-flow session
const session = await yv.sessions.create({
  externalRef: 'user_123',
  callback: 'https://yourapp.com/verify-complete',
});
console.log(session.verifyUrl);
// https://verify.yeboverify.com?session=...

// Get a verification by ID
const verification = await yv.verifications.get('vrf_abc123');

// List verifications
const list = await yv.verifications.list({ externalRef: 'user_123', limit: 10 });

// Verify a webhook signature against the raw request body
const isValid = yv.webhooks.verifySignature(rawBody, signatureHeader, webhookSecret);

Authentication

API key formats

Key prefix	Where to use	Notes
`yv_live_…`	Production backends	Full access. Billable. Calls real verification providers. Never ship to a client bundle.
`yv_test_…`	Integration testing / CI / local dev	Sandbox mode — see below. Never ship to a client bundle either.

Every business is issued both a live key and a test key at signup (POST /v1/signup returns apiKey + testApiKey); you can mint additional named keys of either kind from the console or POST /v1/account/api-keys (pass "isTest": true for a sandbox key).

Server-only secrets

API keys grant full access to your YeboVerify account. Never expose them in client-side code, mobile binaries, or public repositories. For client-side widgets, use a short-lived session token issued by your backend via POST /v1/sessions/create instead.

Sandbox mode (`yv_test_` keys)

A yv_test_ key hits the same API host as your live key (api.yeboverify.com) — there is no separate "test infrastructure" to point at. What changes is behavior:

Never bills. A test-mode verification never writes a usage record and never counts against your plan's monthly quota.
Never calls a paid provider. OCR (Gemini), face/liveness matching (Rekognition), and AML/sanctions screening are all skipped — the decision is simulated instead.
No real ID or selfie required. Since nothing is actually inspected, any placeholder image bytes satisfy the upload — you never need to submit a real photo to integrate.
Fully separate from live data. Test verifications never appear in a live key's GET /v1/verifications, GET /v1/verifications/:id, review queue, or CSV export, and vice versa — a test key can't read or review a live verification either. The operator console shows a persistent "TEST MODE" banner whenever a sandbox key is signed in.

Forced outcomes via simulate. Pass a simulate field (multipart field on POST /v1/verify, POST /v1/verify/id-document, POST /v1/verify/selfie-match; JSON field on POST /v1/sessions/create, which carries it through to whatever the end user submits in that hosted session) set to one of:

`simulate` value	Result
`approved` (default if omitted)	`APPROVED`, high confidence
`rejected`	`REJECTED` — simulated low face-match score
`needs_review`	`NEEDS_REVIEW` — exercise your manual-review handling
`liveness_spoofed`	`REJECTED` — simulated anti-spoofing/liveness failure
`expired_document`	`REJECTED` — simulated expired ID

simulate is rejected with a 400 if sent alongside a live key — it only ever applies to sandbox verifications.

bash

curl -X POST https://api.yeboverify.com/v1/verify \
  -H "X-API-Key: yv_test_YOUR_TEST_KEY" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "externalRef=test-user-1" \
  -F "simulate=needs_review"

The response and the verification.completed webhook that follows use the exact same shape as a live verification, so you can build and test your entire integration — including your rejection and manual-review handling — before ever switching to apiKey / going live.

Recommended environment setup

bash

# .env (server)
YEBOVERIFY_API_URL=https://api.yeboverify.com
YEBOVERIFY_API_KEY=yv_live_xxx
YEBOVERIFY_WEBHOOK_SECRET=whsec_xxx

For local dev / CI / integration tests, swap to your sandbox key on the SAME host — there is no separate dev API key format:

bash

YEBOVERIFY_API_URL=https://api.yeboverify.com
YEBOVERIFY_API_KEY=yv_test_xxx

(dev-api.yeboverify.com is a separate pre-production deployment of the API itself, used to test upcoming API changes — unrelated to yv_test_ sandbox keys, which work against production api.yeboverify.com.)

Error handling

The Node SDK throws typed errors. Catch the specific class to handle each path:

javascript

import {
  YeboVerifyError,
  AuthenticationError,
  ValidationError,
  RateLimitError,
  NotFoundError,
} from '@yeboverify/node';

try {
  await yv.sessions.create({ externalRef: 'user_123' });
} catch (err) {
  if (err instanceof AuthenticationError) {
    // Bad API key — rotate via dashboard
  } else if (err instanceof ValidationError) {
    // Bad input — check err.errors for per-field details
  } else if (err instanceof RateLimitError) {
    // Slow down — retry after err.retryAfter seconds
  } else if (err instanceof NotFoundError) {
    // verificationId / session doesn't exist
  } else if (err instanceof YeboVerifyError) {
    // Generic API error — err.code matches /error-codes
  } else {
    // Network / unknown
  }
}

See Error Codes for the full list of error.code values returned by the API.

TypeScript

The Node + React SDKs ship full type definitions. Webhook payloads can be discriminated on the event field:

typescript

import type { WebhookEvent } from '@yeboverify/node';

function handle(event: WebhookEvent) {
  switch (event.event) {
    case 'verification.submitted':
      // event has verificationId, externalRef, timestamp
      break;
    case 'verification.completed':
      // event also has decision, confidence, faceScore, extractedData
      break;
    case 'verification.deleted':
      // event has verificationId, externalRef, timestamp
      break;
  }
}

Resources

API Reference: /api-reference — REST endpoints
Webhooks: /webhooks — event catalog + signature verification
Examples: /examples — full integration code samples
Embeddable Widgets: /widgets — drop-in browser UI
Mobile Integration: /mobile-integration — Flutter / Kotlin / Swift / React Native
White Label: /white-label — branding the hosted flow
GitHub: github.com/omegathesecond — all SDK repos

Support

Email: [email protected]
Issues: open an issue on the relevant SDK's GitHub repo

SDKs & Libraries ​

Available SDKs ​

Mobile (Flutter / Kotlin / Swift / React Native) ​

Flutter ​

Kotlin (Android) ​

Swift (iOS) ​

React Native ​

Web (React) ​

Server (Node) ​

Authentication ​

API key formats ​

Sandbox mode (yv_test_ keys) ​

Recommended environment setup ​

Error handling ​

TypeScript ​

Resources ​

Support ​

SDKs & Libraries

Available SDKs

Mobile (Flutter / Kotlin / Swift / React Native)

Flutter

Kotlin (Android)

Swift (iOS)

React Native

Web (React)

Server (Node)

Authentication

API key formats

Sandbox mode (`yv_test_` keys)

Recommended environment setup

Error handling

TypeScript

Resources

Support