vouch Docs

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.

Using AI or LLMs with Vouch?

For best results add https://docs.getvouch.io/llms.txt to your model’s context.

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 with your customerId and apiKey:

import { Vouch } from "@getvouch/sdk";
const vouch = new Vouch({
  customerId: "1be03be8-5014-413c-835a-feddf4020da2",
  apiKey: "your-api-key",
});

Generate web verification URL with vouch

Use the vouch SDK to create a verification URL and redirect the user:

Constructor Parameters

customerId

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

apiKey

Your API key for authenticating with the vouch API. This is sent as a Bearer token in the Authorization header when creating proof requests.

getDataSourceUrl Parameters

datasourceId

The UUID of the data source to use for this verification. Available data sources and their respective datasourceIds are listed in available data sources section and in the vouch catalog.

redirectBackUrl

After the Web Verification 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.

The requestId is returned from getDataSourceUrl alongside the verificationUrl, so you can use it to identify the request when the user is redirected back.

An optional UUIDv4 that will be used as the proof request identifier. When provided, the server uses this value as the requestId instead of generating one. This is useful when you want to know the requestId before the request is created — for example, to build the redirectBackUrl with the requestId already embedded.

If omitted, the server generates a requestId automatically and returns it in the response.

webhookUrl

This is an optional parameter. If provided, vouch will send a POST request to this URL with the generated Web Verification 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 matches the webhook payload.

You must verify the webhook using your webhook secret and validate and process all outputs. See Verifying webproofs for the required steps.

inputs

The inputs parameter is a string that holds verification request parameters. Examples include a link to a tweet or a required minimum bank balance. Input values must be JSON-serializable types: string, number, boolean, null, arrays, or objects. Convert unsupported types (like bigint) to strings before serializing.

You must serialize your inputs as JSON and then encode the result as base64. The next section explains how to do this.

metadata

An optional free-form string (up to 256 characters) that you can attach to a proof request. Whatever you pass in is returned unchanged in the webhook payload, so you can use it to link a verification back to your own records.

Return Value

getDataSourceUrl returns a Promise that resolves to an object with:

verificationUrl: The URL to redirect the user to for starting the verification flow.
requestId: The unique ID of the created proof request. This is either the requestId you provided, or one generated by the server if you didn't pass one.

First steps