Verify Group SDK

Official TypeScript/JavaScript SDK for Verify Group Platform APIs.

The SDK exposes a single VerifyGroupSDK client with 49 domain services, typed request/response models, shared error classes, and helper utilities.

Installation

npm install @verify-group/sdk
# or
bun add @verify-group/sdk
# or
yarn add @verify-group/sdk
# or
pnpm add @verify-group/sdk

Quick Start

import { VerifyGroupSDK } from '@verify-group/sdk';

const sdk = new VerifyGroupSDK({
  apiKey: process.env.VG_API_KEY,
  baseUrl: 'https://gateway.verify-group.io',
  clientApp: 'vg-cheque-web',
});

const login = await sdk.auth.login({
  email: '[email protected]',
  password: 'StrongPass123!',
});

await sdk.setAccessToken(login.accessToken);
await sdk.setRefreshToken(login.refreshToken);

const me = await sdk.users.me();
console.log('Logged in user:', me.data.email);

Configuration

VerifyGroupSDK accepts SDKConfig from src/core/types.ts.

const sdk = new VerifyGroupSDK({
  apiKey: process.env.VG_API_KEY,
  baseUrl: 'https://gateway.verify-group.io',
  timeout: 30_000,
  debug: false,
  clientApp: 'vg-cheque-web',
  retry: {
    maxRetries: 3,
    retryDelay: 1000,
    retryableStatuses: [408, 429, 500, 502, 503, 504],
  },
  headers: {
    'X-Correlation-Id': 'req-123',
  },
});

Important:

• There is no environment config property.
• Use baseUrl to target dev/uat/prod gateways.

Core Patterns

Token Management

await sdk.setAccessToken('access-token');
await sdk.setRefreshToken('refresh-token');

const token = await sdk.getAccessToken();
console.log(token);

await sdk.clearTokens();

SDK Events

const onRequest = (event: unknown) => console.log('HTTP request:', event);
sdk.on('http.request', onRequest);

// ...run calls

sdk.off('http.request', onRequest);

Runtime Config Updates

sdk.updateConfig({
  timeout: 15_000,
  debug: true,
  headers: { 'X-Debug-Mode': '1' },
});

Service Catalog (49)

| Service | Description | | ---------------- | --------------------------------------------------------------------- | | auth | Login, registration, MFA, OAuth, SAML, sessions | | users | User CRUD, profile, roles, password, preferences | | organizations | Org management, members, invites, settings | | teams | Team CRUD, membership, roles | | participants | KYC subject management, sanctions, digital footprint | | kyc | KYC verifications, asset checks, document verification | | documents | Document upload, OCR, vehicle/KRA/insurance verification | | claims | Insurance claims (motor, property, life, health), fraud investigation | | evidence | Evidence upload and management for claims | | billing | Subscriptions, invoices, transactions, payments | | payments | M-PESA STK Push, offline payments, subscription plans | | paymentPlans | Instalment plan management, reminders | | invoices | Invoice CRUD, send notice, record payment | | tokens | Token allocation, consumption, balance, analytics | | registry | Debt registry, DPA-compliant search, credit scoring | | banking | Bank/branch lookup, bank account management | | cheques | Cheque verification, DPA search, debtor portal | | disputes | Dispute management and debtor portal | | notifications | Send, bulk send, mark as read, unread counts | | messaging | In-app messaging between users | | communications | Email, SMS, and voice call delivery | | analytics | Event tracking, page views, conversions, metrics | | audit | Immutable audit logs, compliance reports | | admin | Platform administration (users, orgs, KYC, billing) | | accessControl | Permission checks, role catalog, authorization testing | | approvals | Maker-checker workflows for sensitive operations | | consent | GDPR/CCPA consent management | | identity | Decentralized identifiers (DID), verifiable credentials | | mfa | MFA setup (TOTP, SMS, email), verification | | verification | Identity and document verification sessions | | forensics | Document/voice forensics, fraud scoring, network analysis | | developers | Developer registration, API key management | | oauthApps | OAuth 2.0 application management | | settings | User preferences and organization settings | | content | CMS content creation, publishing, slug-based retrieval | | onboarding | Step-by-step user/org onboarding flows | | betaTesting | Beta tester invitations, feedback, resolution | | invitations | Organization member invitation lifecycle | | voice | Voice call initiation, biometrics, Q&A | | search | Cross-domain search with export | | reports | Async report generation and download | | batch | Bulk job processing | | membership | Membership plan management | | dashboard | Platform statistics and verification performance | | health | Kubernetes-style liveness/readiness/startup probes | | files | Polymorphic file attachment, metadata, signed URLs | | docusign | Electronic signature envelopes and recipient views | | public | Public-facing forms (contact, demo request, newsletter) | | customChecks | Custom multi-step verification check definitions |

Common Workflows

Organization Setup

const countries = sdk.helpers.getCountries();
const industries = sdk.helpers.getIndustries();
const businessTypes = sdk.helpers.getBusinessTypes();

const org = await sdk.organizations.create({
  name: 'Acme Corporation',
  slug: 'acme-corp',
  registrationNo: 'CPR/2010/245678',
  countryOfRegistration: countries.find((c) => c.code === 'KE')?.code,
  industry: industries.includes('manufacturing') ? 'manufacturing' : industries[0],
  type: businessTypes.includes('ltd') ? 'ltd' : businessTypes[0],
  tier: 'enterprise',
});

await sdk.teams.create({
  organizationId: org.data.id,
  name: 'Engineering',
  slug: 'engineering',
  type: 'DEPARTMENT',
});

KYC Verification

const created = await sdk.kyc.createVerification({
  participantId: '550e8400-e29b-41d4-a716-446655440001',
  type: 'individual',
  scenario: 'identity',
  payload: {
    identifierType: 'national_id',
    identifierNumber: '12345678',
    consent: true,
  },
});

const status = await sdk.kyc.getVerificationStatus(created.data.id);
console.log(status.data.status);

Beta Testing Program

// Admin invite
const invite = await sdk.betaTesting.inviteBetaTester({
  email: '[email protected]',
  name: 'QA Tester',
  tokensToAllocate: 100,
});

console.log(invite.data.betaTesterId);

// Beta tester feedback
await sdk.betaTesting.submitFeedback({
  category: 'BUG',
  priority: 'HIGH',
  title: 'Login button disabled after retry',
  description: 'Button remains disabled after first failed attempt.',
});

// Admin reporting
const stats = await sdk.betaTesting.getFeedbackStats();
console.log('Pending feedback:', stats.data.pendingCount);

Payment Plans

const defaultedPlans = await sdk.paymentPlans.list({
  organizationId: 'organization-uuid',
  status: 'DEFAULTED',
});

for (const plan of defaultedPlans) {
  console.log(`${plan.referenceNumber}: ${plan.status}`);
  console.log(`Defaulted at: ${plan.defaultedAt}`);
  console.log(`Missed installments: ${plan.defaultedMissedInstallments}`);
}

const plan = await sdk.paymentPlans.getById('payment-plan-uuid');
console.log(`Paid installments: ${plan.installmentsPaid}/${plan.installmentCount}`);

const installments = await sdk.paymentPlans.getInstallments(plan.id);
const missed = installments.filter(
  (installment) => installment.status === 'OVERDUE' || installment.status === 'DEFAULTED'
);

missed.forEach((installment) => {
  console.log(`Installment ${installment.installmentNumber}`);
  console.log(`Days overdue: ${installment.daysOverdue}`);
  console.log(`Overdue at: ${installment.overdueAt}`);
  console.log(`Defaulted at: ${installment.defaultedAt}`);
});

const preview = await sdk.paymentPlans.previewReminderStage({
  installmentId: 'installment-uuid',
});
console.log('Stage matches:', preview.matches);

await sdk.paymentPlans.pausePlanReminders({
  paymentPlanId: 'payment-plan-uuid',
  reason: 'Debtor requested temporary pause',
});

await sdk.paymentPlans.resumePlanReminders({
  paymentPlanId: 'payment-plan-uuid',
});

const queueRun = await sdk.paymentPlans.runReminderQueue();
console.log('Reminders sent:', queueRun.execution.sent);

const reminderHealth = await sdk.paymentPlans.getReminderHealth();
console.log('Reminder health:', reminderHealth.status);

Error Handling

import {
  SDKError,
  AuthenticationError,
  AuthorizationError,
  ValidationError,
  NetworkError,
} from '@verify-group/sdk';

try {
  await sdk.auth.login({ email: '[email protected]', password: 'bad-pass' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid credentials');
  } else if (error instanceof AuthorizationError) {
    console.error('Not allowed for this action');
  } else if (error instanceof ValidationError) {
    console.error('Invalid request payload');
  } else if (error instanceof NetworkError) {
    console.error('Network issue, retry later');
  } else if (error instanceof SDKError) {
    console.error(error.code, error.message, error.statusCode);
  }
}

Examples

See examples/ for runnable examples:

| File | Description | | ---------------------------------- | -------------------------------------------------------- | | authentication.example.ts | Login, registration, MFA, OTP, password flows | | basic-usage.ts | Minimal SDK setup, login, get current user | | advanced-features-usage.ts | Query utilities, retry, search export, debounce | | access-control-usage.ts | Permission checks, authorization testing | | banking-usage.ts | Bank/branch lookup, bank accounts | | beta-testing-usage.ts | Admin invite testers, submit feedback, reporting | | billing-usage.ts | Subscriptions, invoices, transactions | | claims-usage.ts | General claims, motor insurance claims, voice interviews | | dashboard-stats-usage.ts | Dashboard statistics, verification performance | | debounce-usage.ts | Debounce utility for search inputs | | environment-usage.ts | Multi-environment SDK configuration | | gateway-proxy-usage.ts | All requests via a single gateway baseUrl | | kyc-asset-verification.ts | Vehicle plate verification with polling | | notifications-usage.ts | Send notifications, mark as read, unread counts | | registry-usage.ts | Debt registry search, entries, debtor profiles | | settings-usage.ts | User preferences and organization settings | | tokens-usage.ts | Token allocation, consumption, balance, analytics | | react-login-form.tsx | React login form with validation | | react.example.tsx | React context provider, useAuth hook | | react-native-register-screen.tsx | React Native registration screen |

Documentation

📚 View Full Documentation

Quick Links

• Getting Started - Your first steps with the SDK
• API Reference - Complete TypeDoc API documentation
• All API Versions - Browse different SDK versions
• Installation Guide - Setup instructions
• Usage Examples - Common patterns
• Architecture - SDK design and structure

Local Documentation

• Docs index
• Getting started
• Usage examples
• Architecture

License

MIT