API Reference

Everything you need to integrate VerifyWall into your application.

Authentication

All API requests require a Bearer token in the Authorization header. Generate an API key from your dashboard under Settings → API Keys.

Authorization: Bearer vw_live_your_api_key_here

Keep your API keys secure. Do not expose them in client-side code or public repositories. If a key is compromised, revoke it immediately from your dashboard.

Base URL

All API endpoints are served from:

https://api.verifywall.com/v1

All requests must be made over HTTPS. HTTP requests will be rejected.

POST/v1/verify

Assess the risk of an email and/or IP address combination. At least one of email or ip is required.

Parameters

Parameter	Type	Required	Description
email	string	Conditional	A valid RFC 5321 email address. Nullable. At least one of email or ip required.
ip	string	Conditional	A valid IPv4 or IPv6 address. Nullable. At least one of email or ip required.

Example Request

curl -X POST https://api.verifywall.com/v1/verify \
  -H "Authorization: Bearer vw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "ip": "203.0.113.42"
  }'

Example Response

{
  "data": {
    "id": "a1b2c3...",
    "type": "verifications",
    "attributes": {
      "risk_score": 72,
      "risk_level": "high",
      "reasons": [
        {
          "factor": "disposable_email",
          "score": 25,
          "details": {}
        }
      ],
      "email": "[email protected]",
      "ip": "203.0.113.42",
      "checks": [
        {
          "check": "disposable_email",
          "matched": true,
          "score": 25,
          "details": {}
        }
      ],
      "warnings": []
    }
  }
}

GET/v1/check

Check the risk level of a single subject. The type (email, IP, or domain) is auto-detected from the input.

Query Parameters

Parameter	Type	Required	Description
q	string	Yes	The subject to check. Max 254 characters. Auto-detected as email, IP address, or domain.

Example Request

curl "https://api.verifywall.com/v1/[email protected]" \
  -H "Authorization: Bearer vw_live_..."

Example Response

{
  "data": {
    "id": "a1b2c3...",
    "type": "checks",
    "attributes": {
      "subject": "[email protected]",
      "subject_type": "email",
      "risk_level": "medium",
      "risk_score": 45,
      "reasons": ["free_email"],
      "details": {
        "is_disposable": false,
        "is_free_provider": true,
        "domain_age_days": null,
        "has_mx_records": true,
        "is_custom_blacklisted": false
      }
    },
    "meta": {
      "cached": false
    }
  }
}

POST/v1/check/batch

Check multiple subjects in a single request. Requires the Sentinel plan. Duplicates are automatically deduplicated.

Parameters

Parameter	Type	Required	Description
subjects	array	Yes	Array of 1–50 subjects (emails, IPs, or domains). Each max 254 characters.

Example Request

curl -X POST https://api.verifywall.com/v1/check/batch \
  -H "Authorization: Bearer vw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "subjects": [
      "[email protected]",
      "192.168.1.100",
      "example.com"
    ]
  }'

Example Response

{
  "data": [
    {
      "id": "a1b2c3...",
      "type": "checks",
      "attributes": {
        "subject": "[email protected]",
        "subject_type": "email",
        "risk_level": "high",
        "risk_score": 87,
        "reasons": ["disposable_email"],
        "details": {
          "is_disposable": true,
          "is_free_provider": false,
          "domain_age_days": 3,
          "has_mx_records": true,
          "is_custom_blacklisted": false
        }
      },
      "meta": {
        "cached": false
      }
    },
    {
      "id": "d4e5f6...",
      "type": "checks",
      "attributes": {
        "subject": "192.168.1.100",
        "subject_type": "ip",
        "risk_level": "low",
        "risk_score": 12,
        "reasons": [],
        "details": {
          "is_vpn": false,
          "is_proxy": false,
          "is_tor": false,
          "is_datacenter": false,
          "country_code": "DE",
          "is_custom_blacklisted": false
        }
      },
      "meta": {
        "cached": true
      }
    }
  ],
  "meta": {
    "batch_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
  }
}

GET/v1/status

Returns your current API status, plan information, and usage statistics for the current billing period.

Parameters

This endpoint takes no parameters.

Example Request

curl "https://api.verifywall.com/v1/status" \
  -H "Authorization: Bearer vw_live_..."

Example Response

{
  "data": {
    "id": "usr_...",
    "type": "statuses",
    "attributes": {
      "status": "operational",
      "plan": "sentinel"
    }
  }
}

Rate Limits

API requests are rate-limited per minute based on your plan. Exceeding the limit returns a 429 response with a Retry-After header.

Plan	Rate Limit	Batch Check
Starter	60 requests/min	Not available
Sentinel	300 requests/min	Up to 50 subjects per request

Error Codes

All errors follow the JSON:API error format with an errors array.

{
  "errors": [
    {
      "status": "422",
      "title": "Validation Error",
      "detail": "The q field is required.",
      "source": {
        "parameter": "q"
      }
    }
  ]
}

Status	Type	Description
401	Unauthenticated	Missing or invalid API key. Include a valid Bearer token in the Authorization header.
422	Validation Error	The request failed validation. Check each error’s source.pointer (body) or source.parameter (query) for the offending field.
404	Not Found	The requested resource or endpoint does not exist.
429	Rate Limit Exceeded	Too many requests. Back off and retry after the duration indicated by the Retry-After header.
402	Payment Required	Payment is past due or monthly API quota exceeded. Update your payment method or upgrade your plan.
403	Forbidden	Your plan does not include access to this feature. Batch check requires the Sentinel plan.

Risk Scoring

Every check returns a risk_score (0–100) and a risk_level classification. The score is calculated by combining multiple signals based on the subject type.

Risk Levels

Level	Score Range	Recommended Action
none	0–9	Allow — no risk signals detected.
low	10–39	Allow — minor signals, likely legitimate.
medium	40–74	Review — consider additional verification (e.g., CAPTCHA, email confirmation).
high	75–100	Block — strong fraud signals detected.

Scoring Signals

Signals checked depend on the subject type:

Email

Disposable email provider
Free email provider
Domain age
MX record presence
Custom blacklist match

IP Address

VPN detection
Proxy detection
Tor exit node
Datacenter IP
Custom blacklist match

Domain

Disposable domain
Domain age
Registrar reputation
Custom blacklist match