Why API-First Video KYC Matters
For developers building financial applications in India, integrating Video KYC is no longer optional -- it is a core product requirement. Whether you are building a lending app, a neo-banking platform, an insurance onboarding flow, or a brokerage account opening system, your users need to complete identity verification before they can transact. The question is not whether to integrate Video KYC, but how to do it in a way that is fast to implement, reliable in production, and seamless for your end users.
An API-first approach to Video KYC means your application treats the verification process as a service that can be called programmatically, rather than redirecting users to a separate portal or requiring manual coordination. Your backend creates a verification session via API, your frontend renders the video experience through an embedded SDK or WebView, and your system receives real-time status updates through webhooks. The entire flow is orchestrated by your application code, giving you full control over the user experience.
This architectural approach offers significant advantages. Your development team can integrate Video KYC into your existing onboarding flow without building a separate interface. You can customize the user experience to match your brand. You can programmatically handle edge cases like session timeouts, network failures, and verification rejections. And you can scale your verification capacity independently of your application infrastructure.
Architecture Overview: REST API + WebSocket + WebView
A modern Video KYC integration typically involves three communication layers. The first is the REST API, which handles session lifecycle management: creating sessions, retrieving session status, fetching verification results, and downloading audit artifacts like recordings and reports. REST APIs use standard HTTPS with JSON payloads and are authenticated using API keys or OAuth2 tokens.
The second layer is WebSocket communication, which provides real-time bidirectional messaging during an active video session. WebSockets are used for signaling in the WebRTC video call, transmitting real-time events (customer joined, document shown, liveness check passed), and enabling the agent dashboard to display live session status. WebSocket connections are established when a session begins and terminated when it ends.
The third layer is the WebView SDK, which renders the actual video experience in the customer's browser or mobile app. The SDK handles camera and microphone permissions, WebRTC peer connection setup, video rendering, UI for document capture and liveness challenges, and graceful handling of network interruptions. On mobile, this SDK is loaded inside a WebView component (WKWebView on iOS, Android WebView on Android), while on desktop browsers it runs directly in the browser tab.
Session Creation and Link Generation
The integration begins with your backend creating a verification session via the REST API. Your server sends a POST request to the session creation endpoint with the customer's basic details -- name, mobile number, email, and the type of verification required. The API returns a unique session ID, a short-lived session token, and a customer-facing URL that loads the Video KYC experience.
The session token is critical for security. It is a signed JWT (JSON Web Token) that encodes the session ID, creation timestamp, expiry time (typically 30 minutes), and the permissions granted for this session. The token is passed to the frontend SDK and is validated by the Video KYC platform when the customer joins the session. This ensures that only authorized sessions can access the video infrastructure and that expired or tampered tokens are rejected.
You have two options for presenting the Video KYC experience to the customer. The first is to send the customer-facing URL directly via SMS or email -- the customer clicks the link and joins the session in their mobile browser. The second is to embed the experience within your application by loading the URL in a WebView or iframe and passing the session token programmatically. The embedded approach provides a more seamless user experience since the customer never leaves your app, while the link-based approach is simpler to implement and does not require SDK integration.
WebView SDK Integration for iOS and Android
For native mobile applications, embedding the Video KYC experience requires careful WebView configuration. On iOS, you use WKWebView with specific settings: JavaScript must be enabled, the WebView must be configured to allow inline media playback (allowsInlineMediaPlayback = true), and you must handle the camera and microphone permission prompts by implementing the WKUIDelegate methods. The Info.plist must include NSCameraUsageDescription and NSMicrophoneUsageDescription entries with appropriate user-facing descriptions.
On Android, the WebView requires similar configuration. Enable JavaScript via WebSettings, set setMediaPlaybackRequiresUserGesture to false, and override the onPermissionRequest method in WebChromeClient to grant camera and microphone permissions when the Video KYC page requests them. Your AndroidManifest.xml must declare CAMERA, RECORD_AUDIO, and INTERNET permissions. For Android 9 and above, you must also set usesCleartextTraffic to false (enforcing HTTPS) and handle the permission runtime request flow before loading the WebView.
A common integration pitfall is handling the WebView lifecycle correctly. When the user navigates away from the WebView (presses the home button, receives a phone call, or switches apps), the WebRTC session may be interrupted. Your app should detect this state change and display a reconnection prompt when the user returns. The Video KYC platform should support session resumption within a configurable grace period (typically 60 to 120 seconds) so that the customer does not have to restart the entire verification process.
Webhook Callbacks for Status Updates
Rather than polling the API for session status changes, your backend should register webhook endpoints that receive real-time notifications as the verification progresses. The Video KYC platform sends HTTP POST requests to your registered webhook URL for key events: session.created (session is ready for the customer to join), session.started (customer and agent are connected), session.completed (verification finished successfully), session.rejected (verification failed or was declined by the agent), and session.expired (session timed out without completion).
Each webhook payload includes the session ID, event type, timestamp, and event-specific data. For the session.completed event, the payload includes the verification result (approved or needs review), the face-match confidence score, liveness detection result, and links to download the session recording and verification report. Your backend should validate the webhook signature (typically an HMAC-SHA256 hash of the payload using your webhook secret) to ensure the request is genuinely from the Video KYC platform and has not been tampered with.
Webhook reliability is essential for production integrations. Your endpoint should return a 200 status code within 5 seconds to acknowledge receipt. If the platform does not receive a 200 response, it will retry the webhook delivery using exponential backoff -- typically at 1 minute, 5 minutes, 30 minutes, and 2 hours. Your backend should be idempotent, meaning it handles duplicate webhook deliveries gracefully without processing the same event twice. Use the event ID included in each webhook payload as a deduplication key.
Error Handling and Retry Logic
Robust error handling separates production-grade integrations from prototype-quality code. The Video KYC API returns standard HTTP status codes: 400 for invalid request parameters, 401 for authentication failures, 403 for insufficient permissions, 404 for non-existent sessions, 429 for rate limit exceeded, and 500 for server-side errors. Your integration should handle each of these distinctly.
For transient errors (429 and 500), implement retry logic with exponential backoff. Start with a 1-second delay, double it on each retry, and cap at 5 retries with a maximum delay of 32 seconds. Include jitter (a small random delay added to each retry interval) to prevent thundering herd problems when multiple clients retry simultaneously. For 400 errors, log the specific validation failure from the response body and surface a meaningful error message to your user or operations team -- these errors indicate a bug in your request construction and should not be retried.
On the frontend, handle network failures gracefully. If the WebView loses connectivity during a video session, display a clear reconnection indicator rather than an opaque error screen. Implement a heartbeat mechanism that checks connectivity every 5 seconds during an active session and triggers an automatic reconnection attempt when connectivity is restored. For complete session failures (agent disconnects, platform outage), provide the customer with an option to reschedule rather than forcing them to restart the onboarding flow from the beginning.
BASEKYC API Overview
BASEKYC provides a comprehensive API platform designed for developer productivity. Our REST API follows OpenAPI 3.0 specification with full Swagger documentation, making it easy to explore endpoints and generate client libraries in any language. Authentication uses API key pairs (a public key for frontend SDK initialization and a secret key for backend API calls), with optional OAuth2 support for enterprise deployments.
Our WebView SDK is a lightweight JavaScript bundle (under 50KB gzipped) that handles the entire customer-side video experience. It includes built-in camera permission handling, adaptive video quality based on network conditions, automatic reconnection on network interruption, and a customizable UI that can be themed to match your brand colors and typography. The SDK supports all modern browsers (Chrome, Safari, Firefox, Edge) and works seamlessly in native WebView containers on iOS 14+ and Android 8+.
BASEKYC's webhook system delivers events with guaranteed at-least-once delivery and includes a webhook dashboard where you can view delivery history, inspect payloads, and manually retry failed deliveries. We also provide a sandbox environment with test credentials, simulated agent responses, and mock webhook events so you can build and test your integration end-to-end without conducting real verification sessions.
For teams that need to move fast, our quickstart integration takes under two hours. Create an account, generate API keys, call the session creation endpoint from your backend, load the returned URL in a WebView or browser, and register a webhook to receive the verification result. From first API call to production-ready integration, BASEKYC is designed to minimize the engineering effort required to add compliant Video KYC to your application.