Skip to main content

​
Get Your API Credentials

1

Sign up for Vouch

Create a free account at vouch.expert
2

Create a project

Projects help you organize different applications and environments
3

Get your API keys

Each project comes with 4 API keys:
  • Client Test - For development in the browser
  • Client Live - For production in the browser
  • Server Test - For development on the server
  • Server Live - For production on the server
Never use Server keys in client-side code - they can validate any email without domain restrictions!

​
Installation

Choose your platform:
  • JavaScript/React
  • Node.js
  • Next.js
  • iOS
  • Android
npm install @vouch/js
# or for React
npm install @vouch/react

​
Basic Usage

  • JavaScript
  • React
  • Node.js
  • Next.js (Server)
  • iOS
  • Android
import { Vouch } from '@vouch/js';

// Initialize with your client key
const vouch = new Vouch(
  'your-project-id',
  'your-client-api-key'
);

// Validate an email (includes automatic device fingerprinting)
const result = await vouch.validate('[email protected]');

if (!result.success) {
  console.log('Validation failed:', result.error);
} else if (result.data) {
  const { checks, deviceData } = result.data;

  if (!checks.syntax?.pass || !checks.disposable?.pass) {
    console.log('Email blocked:', result.data.signals);
  } else {
    console.log('Email is valid!');
  }
}

​
Understanding the Response

Every validation returns a result with: 
{
  "success": true,
  "statusCode": 200,
  "data": {
    "checks": {
      "syntax": { "pass": true, "latency": 2 },
      "disposable": { "pass": true, "latency": 15 },
      "mx": { "pass": true, "latency": 45 },
      "smtp": { "pass": true, "latency": 120 }
    },
    "deviceData": {
      "isKnownDevice": false,
      "isNewEmail": true,
      "emailsUsed": 1,
      "previousSignups": 0,
      "firstSeen": 1699564800000,
      "lastSeen": 1699564800000
    },
    "ipData": {
      "ip": "192.168.1.1",
      "isVPN": false,
      "isFraud": false
    },
    "signals": ["new_device", "valid_email"]
  }
}

​
Key Fields

  • success - Whether the validation completed successfully
  • data.checks - Individual validation results (syntax, disposable, mx, smtp, etc.)
  • data.deviceData - Device fingerprint information
  • data.ipData - IP reputation data
  • data.signals - Array of signal identifiers detected

​
Handling Results

Check individual validations based on your requirements: 
if (result.success && result.data) {
  const { checks } = result.data;

  // Critical checks - block if failed
  if (!checks.syntax?.pass || !checks.disposable?.pass) {
    // Block signup
  }

  // Warning checks - flag for review
  if (!checks.deviceFingerprint?.pass || result.data.deviceData.emailsUsed > 5) {
    // Flag for manual review
  }
}

​
Individual Signals

Each validation check returns:
  • valid - Whether the check passed
  • action - The configured action for this check type

​
Client vs Server Keys

Client Keys

Use in browsers/mobile apps
  • Restricted to allowed domains
  • Lower rate limits (1,000/hour)
  • Safe to expose publicly
  • Includes device fingerprinting

Server Keys

Use on your backend
  • No domain restrictions
  • Higher rate limits (5,000/hour)
  • Must be kept secret
  • Can override IP/User-Agent
Server keys are blocked from browsers. If you try to use a server key in client-side code, you’ll get a 401 error.

​
Test vs Live Keys

Each environment has separate keys:
  • Test keys - Use during development, doesn’t count against quota
  • Live keys - Use in production, counts against your subscription

​
Next Steps

Learn How It Works

Understand Vouch’s validation strategy

Explore Validation Types

Deep dive into each validation check

API Reference

Complete API documentation

Best Practices

Production deployment tips