Vouch widget

What is the Vouch widget?

Vouch widget is a Vouch-hosted page that lists the data sources you allow and lets the user pick one. Use it when several sources prove the same fact and you want the user to choose the one they hold, instead of creating a request for a single data source.

For example, a "Verification of address" widget might offer Revolut, NatWest, Experian, and Binance as options. The user selects whichever provider they already have an account with, and the rest of the flow is handled automatically.

The widget is not a separate verification channel. Once the user picks a source, they verify in the Vouch browser extension or the Vouch mobile apps, depending on their device.

How it works

1. You create a widget in your Vouch dashboard: first, choose the data source format, then pick the countries that you want to support and for each country select the available data sources.
2. You generate a link to the widget using the Vouch SDK and redirect the user to it (or open it in a new tab).
3. The user picks a data source from the widget and completes the verification flow.
4. After verification, the user is redirected back to your redirectBackUrl, and if configured, a webhook is sent to your webhookUrl with the verification.

Integrating the widget

To integrate the widget, generate a URL with the Vouch SDK and redirect the user to it. No iframe is needed.

Install the SDK

npm install @getvouch/sdk

yarn add @getvouch/sdk

pnpm add @getvouch/sdk

bun add @getvouch/sdk

Generate the widget URL

Use vouch.getWidgetUrl() to create a link to your widget, then redirect the user.

You can find your Customer ID and API key in the API Keys section of your organization settings.

import {Vouch} from "@getvouch/sdk";

const vouch = new Vouch({
    customerId: "YOUR_CUSTOMER_ID",
    apiKey: "YOUR_API_KEY",
});

const { verificationUrl, requestId } = await vouch.getWidgetUrl({
    widgetId: "YOUR_WIDGET_ID",
    redirectBackUrl: "https://your-site.com/verification-complete",
    webhookUrl: "https://your-site.com/api/webhook", // optional
    metadata: "user:12345", // optional, up to 256 characters
});

// Redirect the user to the widget
window.location.href = verificationUrl;

Widget parameters

Return value

getWidgetUrl returns a Promise that resolves to an object with:

• verificationUrl: The URL to redirect the user to for displaying the widget.
• requestId: The unique ID of the verification request, generated by the server. Use it to correlate webhook responses.

Customizing colors and logo

The widget uses your organization's branding — logo, colors, and so on — from the Appearance section of your organization settings. Those settings apply to the whole Vouch-hosted flow, not only the widget, so there are no per-widget style parameters. See Customize your appearance.

For more details on the full verification flow and webhook handling, see First steps and Verifying webproofs.