---
title: Decision Endpoint
description: Request a decision from a Gate to allow, block, or challenge a user action.
---

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

### Endpoint

```bash
POST /v0/gates/{gate_id}/decisions
```

### Authentication

Include your API key in the `Authorization` header:

```bash
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.

```json
{
  "email": "octocat@github.com",
  "ip": "1.1.1.1" // optional
}
```

or

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

### Example response

```json
{
  "input": {
    "email": "octocat@github.com",
    "ip": "1.1.1.1"
  },
  "decision": {
    "action": "allow",
    "matched_rule": {
      "id": "01k1hxqrn2f7xfreq20y0p012d",
      "name": "Allow professional email providers",
      "message": null
    }
  },
  "signals": {
    "email": {
      "address": "octocat@github.com",
      "normalized": "octocat@github.com",
      "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