Decision Endpoint - Documentation

Use the Decision API to evaluate a Gate in real time.

Endpoint

POST /v0/gates/{gate_id}/decisions

Authentication

Include your API key in the Authorization header:

Authorization: Bearer <YOUR_API_KEY>

Request body

Either email or domain is required. If both are provided it will return 400 both_email_and_domain_provided. You can optionally include an ip field for additional IP-based intelligence.

{
  "email": "[email protected]",
  "ip": "1.1.1.1" // optional
}

{
  "domain": "github.com",
  "ip": "1.1.1.1" // optional
}

Example response

{
  "input": {
    "email": "[email protected]",
    "ip": "1.1.1.1"
  },
  "decision": {
    "action": "allow",
    "matched_rule": {
      "id": "01k1hxqrn2f7xfreq20y0p012d",
      "name": "Allow professional email providers",
      "message": null
    }
  },
  "signals": {
    "email": {
      "address": "[email protected]",
      "normalized": "[email protected]",
      "domain": "github.com",
      "local_part": "octocat",
      "local_part_length": 7,
      "subaddress": null,
      "disposable": false,
      "role_account": false
    },
    "domain": {
      "name": "github.com",
      "domain_authority": 96,
      "tld": "com",
      "sld": "github",
      "subdomain": null,
      "age_days": 6712,
      "mx": true,
      "mx_records": [
          { "hostname": "aspmx.l.google.com", "priority": 1 },
          { "hostname": "alt1.aspmx.l.google.com", "priority": 5 },
          { "hostname": "alt2.aspmx.l.google.com", "priority": 5 },
          { "hostname": "alt3.aspmx.l.google.com", "priority": 10 },
          { "hostname": "alt4.aspmx.l.google.com", "priority": 10 }
      ],
      "mx_providers": [
          { "slug": "google", "type": "mailbox", "grade": "professional" }
      ],
      "disposable": false,
      "public_domain": false,
      "relay_domain": false,
      "spam": false,
      "blocklisted": false
    },
    "ip": {
      "address": "1.1.1.1",
      "abuse": {
        "detected": false
      },
      "anonymity": {
        "proxy": {
          "detected": false
        },
        "relay": {
          "detected": false
        },
        "tor": {
          "detected": false
        },
        "vpn": {
          "detected": false
        }
      },
      "geo": {
        "city": "Hong Kong",
        "country": "Hong Kong",
        "country_code": "HK",
        "continent": "Asia",
        "continent_code": "AS"
      },
      "hosting": {
        "detected": true
      },
      "network": {
        "asn": 	13335,
        "aso": "Cloudflare, Inc.",
        "domain": "cloudflare.com",
        "type": "hosting"
      }
    }
  },
  "meta": {
    "version": "0.1",
    "request_id": "01K1SKM0ZDCEEES5QA9N3M5EPX",
    "duration_ms": 52.62,
    "created_at": "2025-08-04T03:57:18+00:00"
  }
}

Error responses

400 missing_input: Neither email nor domain provided
400 invalid_email: The email format is invalid
400 invalid_domain: The domain format is invalid
401 unauthorized: Invalid or missing API key
403 pro_only: Your account is not a Pro plan customer
404 gate_not_found: Unknown gate_id
429 rate_limit_exceeded: Too many requests