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 API Keys.

Authorization: Bearer vw_sk_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://verifywall.com/api/v1

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

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://verifywall.com/api/v1/[email protected]" \
  -H "Authorization: Bearer vw_sk_..."

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://verifywall.com/api/v1/check/batch \
  -H "Authorization: Bearer vw_sk_..." \
  -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://verifywall.com/api/v1/status" \
  -H "Authorization: Bearer vw_sk_..."

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

MCP (Model Context Protocol)

VerifyWall exposes an MCP server so AI assistants like Claude, Cursor, and other MCP-compatible clients can call VerifyWall directly to check subjects for fraud risk.

Server URL

https://verifywall.com/mcp

Authentication

The MCP server uses the same Bearer token as the REST API. Pass your API key in the Authorization header.

Rate Limits

MCP requests are rate-limited by your plan and share the same per-token bucket as the REST API. See Rate Limits for the per-minute allowance on each plan.

Available Tool

Tool	Parameter	Description
check-subject-tool	subject	Assess the fraud risk of an email address, IP address, or domain name. The subject type is auto-detected.

Client Configuration

Add the following configuration to your MCP client to connect to VerifyWall:

{
  "mcpServers": {
    "verifywall": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://verifywall.com/mcp",
        "--header",
        "Authorization: Bearer vw_sk_your_api_key_here"
      ]
    }
  }
}