OpenAPI 3.1 Specification

CheckSignup API Reference

Comprehensive reference for all CheckSignup public REST endpoints and response parameters.

Docs / API Reference

POST/validate

Inspect an email address for syntax validity, disposable domain presence, MX records, typo suggestions, and canonical alias mapping.

Request Headers

Header	Type	Description
Authorization	string (required)	Bearer token (e.g. `Bearer cs_live_...`)
X-API-Key	string (optional)	Custom header alternative to Authorization Bearer.
Idempotency-Key	string (optional)	Unique identifier for deduplication (24-hour cache).

Sample cURL Command

BASH / CURL

curl -X POST https://api.checksignup.com/validate \
  -H "Authorization: Bearer cs_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "alex.test+promo@sharklasers.com"}'

Request Body (JSON)

JSON REQUEST BODY

{
  "email": "alex.test+promo@sharklasers.com",
  "check_mx": true,
  "suggest_typo": true
}

Response Payload (200 OK)

JSON RESPONSE BODY

{
  "email": "alex.test+promo@sharklasers.com",
  "normalized": "alex.test@sharklasers.com",
  "domain": {
    "name": "sharklasers.com",
    "created_at": null,
    "age_days": null
  },
  "mx": [
    {
      "exchange": "mail.sharklasers.com",
      "preference": 10
    }
  ],
  "valid": {
    "syntax": true,
    "mx": true
  },
  "flags": {
    "disposable": true,
    "free": false,
    "forwarding": false,
    "role": false
  },
  "typo_suggestion": null,
  "risk_score": 90,
  "action": "block",
  "reason": "disposable_domain",
  "degraded": false
}

Response Codes

200 OK: Validation completed successfully.
400 Bad Request: Malformed request payload.
401 Unauthorized: Missing or invalid API key.
402 Payment Required: Monthly credit quota exhausted.
429 Too Many Requests: Rate limit exceeded for your tier.

GET/health

Public health check endpoint returning edge engine status and operational uptime.

200 OK — HEALTH JSON

{
  "status": "ok",
  "service": "checksignup-scout",
  "version": "1.0.0",
  "timestamp": "2026-09-04T05:30:00.000Z"
}