First steps

Start a new vouch verification

The fundamental pattern for initiating a vouch verification involves using the vouch SDK to generate a secure URL and redirect the user.

Install the vouch SDK

Install the vouch SDK using your preferred package manager:

npm install @getvouch/sdk

yarn add @getvouch/sdk

pnpm add @getvouch/sdk

bun add @getvouch/sdk

Create vouch instance

Initialize the vouch SDK by creating a new instance:

import { Vouch } from "@getvouch/sdk";
const vouch = new Vouch();

Generate web proof URL with vouch

To generate a Web Proof, use the vouch SDK to create a verification URL and redirect the user:

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

// Initialize the Vouch SDK
const vouch = new Vouch();

// Generate the verification URL using the SDK
const verificationUrl = vouch.getStartUrl({
  datasourceId: "93826be6-6c7d-495a-9859-de5a1d17f30b", // example.com data source
  customerId: "1be03be8-5014-413c-835a-feddf4020da2",   // Your unique customer ID
  redirectBackUrl: `https://docs.getvouch.io/getting-started/first-steps`, // Return destination
  webhookUrl: `https://docs.getvouch.io/api/web-proof` // Proof delivery endpoint (optional)
});

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

Vouch URL Parameters

datasourceId

The UUID of the data source to use for this verification. Available data sources and their respective datasourceIds are listed in the resources documentation.

customerId

Your unique customerId is provided during account setup. Contact the vouch team to obtain your production customerId for live integrations.

redirectBackUrl

After the Web Proof is generated, the user will be redirected to this URL. This will usually be a page on your website where you can handle the response and display the result to the user.

You will likely want to use the requestId query parameter to identify the request and retrieve the Web Proof from your server. In this case, the requestId needs to be included manually to the redirectBackUrl in a way that suits your application needs.

webhookUrl

This is an optional parameter. If provided, vouch will send a POST request to this URL with the generated Web Proof once the verification process is complete.

Make sure your webhook handler is capable of processing POST requests. The requests will have a Content-Type of application/json, and the request body will match the WebProof structure.

inputs

The inputs parameter is a string containing proof request parameters, such as the link to a tweet, or the minimum required balance of your bank account, etc. The input values are primitive types [string, number, boolean, null, undefined, symbol, bigint] and must be serialized as JSON and then base64url encoded.