VerifyGrid API

The VerifyGrid API is a single POST endpoint that accepts an email address, phone number, or IP address and returns validation signals. The type is auto-detected, or you can specify it explicitly. Each lookup consumes one credit from the API key used; lookups that fail on our side are not charged.

1. 1. Create an API key

   Open the dashboard and click “New key” to generate a key. Copy it — you won't be able to see it later if you lose it.

2. 2. Send your first request

   POST to the validate endpoint with your key and a value to validate.

3. 3. Read the result

   The response includes a valid flag and type-specific signals you can route on.

Authenticate every request with your API key. Pass it in the request body as api_key, or as the x-api-key header. Sign in to the dashboard to create keys, and verify a mobile number there to unlock 100 free trial credits.

x-api-key: YOUR_API_KEY

POST https://verifygrid95.base44.app/functions/validate

Request body parameters:

{
  "value": "+44 20 7946 0958",
  "api_key": "YOUR_API_KEY"
}

A successful response returns the detected type, the echoed value, a result object, and credits_remaining. Every result includes valid, fraud_score and risk_reasons, plus decision (allow, review, or block, from your rules) and decision_reasons. The other fields vary by type. A field is left out when no data is available for it.

fraud_score is a 0–100 risk score (lower is safer) built from the signals in the result, such as a disposable domain, a VoIP line, or a VPN. Each signal that adds to the score is listed in risk_reasons.

Email

Checks the address syntax and looks up the domain’s mail servers live over DNS. We don’t connect to mail servers to probe individual mailboxes.

Phone

Validated against Google’s libphonenumber numbering-plan data. Where live carrier data is available, the carrier name and the number’s current line type come from a carrier lookup.

IP

IPv4 and IPv6. Private and reserved addresses are recognized locally; public addresses get a live lookup.

{
  "type": "email",
  "value": "sarah.chen@gmial.com",
  "result": {
    "valid": false,
    "deliverability": "low",
    "mx_found": false,
    "is_disposable": true,
    "is_role_account": false,
    "is_free_provider": false,
    "domain": "gmial.com",
    "did_you_mean": "sarah.chen@gmail.com",
    "fraud_score": 100,
    "risk_reasons": [
      "domain DNS is failing",
      "disposable email domain",
      "possible typo of gmail.com"
    ]
  },
  "credits_remaining": 99
}

Send values instead of value to validate up to 100 items in one request. Each item can be a different type. Results come back in the same order. The key must hold enough credits for the whole batch up front; any item that fails on our side is refunded.

{
  "values": ["sarah.chen@techcorp.io", "+44 20 7946 0958", "203.0.113.42"],
  "api_key": "YOUR_API_KEY"
}

{
  "results": [
    { "type": "email", "value": "sarah.chen@techcorp.io", "result": { "valid": true, ... } },
    { "type": "phone", "value": "+44 20 7946 0958", "result": { "valid": true, ... } },
    { "value": "203.0.113.42", "error": "lookup temporarily unavailable; no credit was charged" }
  ],
  "credits_used": 2,
  "credits_remaining": 97
}

Check a whole signup in one call. Send any of email, phone, and ip (plus an optional country for phone numbers without a + code) and get back one decision. It costs 1 credit per field you send; a check that fails on our side is refunded and the decision is made from the others.

POST https://verifygrid95.base44.app/functions/signup-check

{
  "email": "support@mailinator.com",
  "phone": "+44 20 7946 0958",
  "ip": "185.220.101.1",
  "api_key": "YOUR_API_KEY"
}

Every result carries a decision from your account’s rules, which you edit under Rules in the dashboard. The defaults are: block invalid values, block at a risk score of 70 or more, review at 30 or more, allow the rest. Rules are applied in this order:

1. Block list match: block. Entries can be emails, domains (subdomains included), IPs or CIDR ranges, and phone numbers.
2. Allow list match: allow, skipping everything below.
3. Otherwise the strictest of: signal actions (set any signal, such as disposable_email, voip_phone, vpn, or tor, to review or block), the allowed countries rule, and your review / block thresholds.

cURL

curl -X POST https://verifygrid95.base44.app/functions/validate \
  -H "Content-Type: application/json" \
  -d '{
    "value": "sarah.chen@techcorp.io",
    "api_key": "YOUR_API_KEY"
  }'

JavaScript (fetch)

const res = await fetch("https://verifygrid95.base44.app/functions/validate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    value: "203.0.113.42",
    api_key: process.env.VERIFYGRID_KEY
  })
});
const data = await res.json();
console.log(data.result);

Python

import requests, os

resp = requests.post("https://verifygrid95.base44.app/functions/validate", json={
    "value": "+44 7700 900123",
    "api_key": os.environ["VERIFYGRID_KEY"]
})
print(resp.json()["result"])

No code needed: open List cleaning in the dashboard, upload a CSV of up to 25,000 rows, pick the column to check, and download the same file with these columns added to every row: vg_status, vg_risk_score, vg_risk_level, vg_action (allow, review, or block), vg_reasons, and type-specific fields such as vg_disposable or vg_line_type. Each distinct value costs one credit; duplicates and empty cells are free. The file is read in your browser and only the chosen column is sent.

API keys are managed in the dashboard — there is no REST endpoint for creating or revoking keys. Create separate keys per environment, keep them in a secrets manager, and revoke any key that may be exposed.