CheckSignup Integration & API Guide

curl -X POST https://api.checksignup.com/validate \
  -H "Authorization: Bearer cs_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -d '{"email": "test.user+promo@gmail.com"}'

import fetch from 'node-fetch';

const response = await fetch('https://api.checksignup.com/validate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer cs_live_your_api_key_here',
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({ email: 'alex.test+promo@sharklasers.com' })
});

const data = await response.json();

// 3-State Policy Directive Handling: 'allow' | 'review' | 'block'
if(data.action === 'block') {
  // Reject disposable / invalid signup
  throw new Error(`Signup blocked: ${data.reason}`);
} else if(data.action === 'review') {
  // Apply friction (e.g. secondary email OTP or withhold trial credits)
  console.info('Secondary verification required:', data.reason);
} else {
  // Proceed with instant access
  console.log('Valid signup approved for:', data.normalized);
}

import requests
import uuid

resp = requests.post(
    'https://api.checksignup.com/validate',
    headers={
        'Authorization': 'Bearer cs_live_your_api_key_here',
        'Idempotency-Key': str(uuid.uuid4())
    },
    json={'email': 'alex.test+promo@sharklasers.com'}
)

data = resp.json()

# 3-State Policy Directive Handling: 'allow' | 'review' | 'block'
if data.get('action') == 'block':
    raise ValueError(f"Signup rejected: {data.get('reason')}")
elif data.get('action') == 'review':
    print(f"Apply review friction: {data.get('reason')}")
else:
    print(f"Signup approved for: {data.get('normalized')}")

{
  "email": "test.user+promo@gmail.com",
  "normalized": "testuser@gmail.com",
  "domain": {
    "name": "gmail.com",
    "created_at": null,
    "age_days": null
  },
  "mx": [
    {
      "exchange": "gmail-smtp-in.l.google.com",
      "preference": 5
    }
  ],
  "valid": {
    "syntax": true,
    "mx": true
  },
  "flags": {
    "disposable": false,
    "free": true,
    "forwarding": false,
    "role": false
  },
  "typo_suggestion": null,
  "risk_score": 10,
  "action": "allow",
  "reason": "free_email_provider",
  "degraded": false
}