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

These repositories are private

The SDK repos are not public and none of the packages are published to npm, pub.dev, Maven Central or the Swift Package Index. The install commands below only work once your GitHub account has been granted access — until then a clone or npm install fails to authenticate, and the repo links above return 404 (GitHub hides private repos as 404). Ask us to add your GitHub username and we'll grant it.

Installing from github: runs the package's build during install, so you need a working toolchain (Node + npm) on the installing machine — including in CI and in any Docker build stage that runs npm install.

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

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

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

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.

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.

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.

npm install github:omegathesecond/yeboverify-node

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.

curl -X POST https://api.yeboverify.com/v1/verify \
  -H "X-API-Key: yv_test_YOUR_TEST_KEY" \
  -F "idFront=@any-placeholder.jpg" \
  -F "selfie=@any-placeholder.jpg" \
  -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

# .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:

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:

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:

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: support@yeboverify.com
• Issues: open an issue on the relevant SDK's GitHub repo