### Request Body Examples

Source: https://www.usercheck.com/docs/gates/decision-endpoint

Provide either an email or a domain. An optional IP address can be included for additional intelligence.

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

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

--------------------------------

### Install UserCheck Laravel Package

Source: https://www.usercheck.com/docs/integrations/laravel

Install the package using Composer. This command adds the UserCheck package to your project's dependencies.

```bash
composer require usercheck/usercheck-laravel
```

--------------------------------

### GET /blocklist

Source: https://www.usercheck.com/docs/api/blocklist-endpoint

Get a paginated list of all domains in your account's blocklist for the current environment.

```APIDOC
## GET /blocklist

### Description
Get a paginated list of all domains in your account's blocklist for the current environment.

### Method
GET

### Endpoint
/blocklist

### Parameters
#### Query Parameters
- **per_page** (integer) - Optional - Number of results per page (min: 1, max: 100, default: 25)

### Request Example
curl -X GET "https://api.usercheck.com/blocklist" \
  -H "Authorization: Bearer YOUR_API_KEY"

### Response
#### Success Response (200)
- **data** (array) - List of blocklisted domains
- **links** (object) - Pagination links
- **meta** (object) - Pagination metadata

#### Response Example
{
  "data": [
    {
      "domain": "example.com",
      "created_at": "2025-01-27T23:32:12+00:00"
    }
  ],
  "links": {
    "first": "https://api.usercheck.com/blocklist?page=1",
    "last": "https://api.usercheck.com/blocklist?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "per_page": 25,
    "to": 1,
    "total": 1
  }
}
```

--------------------------------

### Add Domain Success Response (200)

Source: https://www.usercheck.com/docs/api/blocklist-endpoint

Example of a successful response after adding a single domain to the blocklist.

```json
{
  "domain": "example.com",
  "created_at": "2024-01-28T12:00:00+00:00"
}
```

--------------------------------

### Migrate Manual Logic to Gate Decision (Python)

Source: https://www.usercheck.com/docs/gates/migrate-from-email-domain

Before: Making a GET request to the /email endpoint and manually checking signals. After: Making a POST request to the Gate's Decision endpoint and checking the returned decision action.

```python
response = requests.get(
    f"https://api.usercheck.com/email/{email}",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
data = response.json()

if data.get("disposable"):
    raise SignUpError("Disposable emails are not allowed.")

if data.get("relay_domain"):
    raise SignUpError("Please use your real email address to register.")

normalized_email = data.get("normalized_email", email)

# Proceed with signup
```

```python
response = requests.post(
    f"https://api.usercheck.com/v0/gates/{GATE_ID}/decisions",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={"email": email},
)
data = response.json()
decision = data.get("decision", {})

if decision.get("action") == "block":
    message = decision.get("matched_rule", {}).get("message")
    raise SignUpError(message)

if decision.get("action") == "challenge":
    tagAccountAsHighRisk()

normalized_email = data.get("signals", {}).get("email", {}).get("normalized", email)

# Proceed with signup
```

--------------------------------

### Bulk Add Domains Success Response (200)

Source: https://www.usercheck.com/docs/api/blocklist-endpoint

Example of a successful response after a bulk domain addition request, detailing succeeded and failed additions.

```json
{
  "succeeded": 2,
  "failed": 1,
  "success": [
    {
      "domain": "example1.com",
      "created_at": "2024-01-28T12:00:00+00:00"
    },
    {
      "domain": "example2.com",
      "created_at": "2024-01-28T12:00:00+00:00"
    }
  ],
  "errors": [
    {
      "domain": "example3.com",
      "error": "The domain has already been blocklisted for this environment."
    }
  ]
}
```

--------------------------------

### Retrieve Domain Information via GET

Source: https://www.usercheck.com/docs/api/domain-endpoint

Use this endpoint to fetch domain details by providing the domain name in the URL path.

```text
GET /domain/{domain}
```

--------------------------------

### Example Decision Response

Source: https://www.usercheck.com/docs/gates/decision-endpoint

The response contains the input, the resulting decision action, and detailed signals for email, domain, and IP.

```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"
  }
}
```

--------------------------------

### Example Webhook Payload Structure

Source: https://www.usercheck.com/docs/webhooks/events

This is an example of the JSON payload sent to your webhook endpoint when an event occurs. It includes the event type, timestamp, and event-specific data.

```json
{
  "event": "domain.flagged.disposable",
  "created_at": "2025-03-26T14:30:25+00:00",
  "data": {
    "domain": "example.com"
  }
}
```

--------------------------------

### GET /status

Source: https://www.usercheck.com/docs/api/status-endpoint

Retrieves account details, plan information, and current API usage for the billing period.

```APIDOC
## GET /status

### Description
Check your account details, plan information, and current API usage.

### Method
GET

### Endpoint
/status

### Request Example
```bash
curl -X GET "https://api.usercheck.com/status" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **status** (string) - Status of the request. Returns `"success"` on a successful request.
- **account.plan.name** (string) - The name of your current plan (e.g., "Pro 1.5M").
- **account.plan.credits** (integer) - Total number of credits included in your plan per billing period.
- **account.plan.rate_limit** (integer) - Maximum number of requests per second allowed by your plan.
- **account.user.name** (string) - The name of the account holder.
- **account.user.email** (string) - The email address of the account holder.
- **usage.limit** (integer) - Total usage limit for the current billing period.
- **usage.current** (integer) - Number of credits used so far in the current billing period.
- **usage.remaining** (integer) - Number of credits remaining in the current billing period.
- **usage.reset_at** (string) - ISO 8601 timestamp indicating when the usage counter resets for the next billing period.

#### Response Example
```json
{
  "status": "success",
  "account": {
    "plan": {
      "name": "Pro 200K",
      "credits": 200000,
      "rate_limit": 15
    },
    "user": {
      "name": "Jane Doe",
      "email": "jane@example.com"
    }
  },
  "usage": {
    "limit": 200000,
    "current": 48320,
    "remaining": 151680,
    "reset_at": "2026-04-01T00:00:00.000000Z"
  }
}
```

### Error Responses
#### Unauthorized (401)
```json
{
  "status": 401,
  "error": "Unauthorized"
}
```

#### Rate Limit Exceeded (429)
```json
{
  "status": 429,
  "error": "Too many requests"
}
```
```

--------------------------------

### GET /blocklist/{domain}

Source: https://www.usercheck.com/docs/api/blocklist-endpoint

Check if a specific domain exists in your account's blocklist for the current environment.

```APIDOC
## GET /blocklist/{domain}

### Description
Check if a specific domain exists in your account's blocklist for the current environment.

### Method
GET

### Endpoint
/blocklist/{domain}

### Parameters
#### Path Parameters
- **domain** (string) - Required - The domain to check (e.g., example.com)

### Request Example
curl -X GET "https://api.usercheck.com/blocklist/example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

### Response
#### Success Response (200)
- **domain** (string) - The domain checked
- **created_at** (string) - Timestamp of creation

#### Response Example
{
  "domain": "example.com",
  "created_at": "2024-01-28T12:00:00+00:00"
}
```

--------------------------------

### Remove Domain Success Response (200)

Source: https://www.usercheck.com/docs/api/blocklist-endpoint

Example of a successful response after removing a domain from the blocklist.

```json
{
  "message": "Domain removed from blocklist successfully"
}
```

--------------------------------

### Blocklist API Success Response (200)

Source: https://www.usercheck.com/docs/api/blocklist-endpoint

Example of a successful response when listing blocklisted domains, including data, pagination links, and metadata.

```json
{
  "data": [
    {
      "domain": "example.com",
      "created_at": "2025-01-27T23:32:12+00:00"
    }
  ],
  "links": {
    "first": "https://api.usercheck.com/blocklist?page=1",
    "last": "https://api.usercheck.com/blocklist?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": null,
        "label": "« Previous",
        "active": false
      },
      {
        "url": "https://api.usercheck.com/blocklist?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": null,
        "label": "Next »",
        "active": false
      }
    ],
    "path": "https://api.usercheck.com/blocklist",
    "per_page": 25,
    "to": 1,
    "total": 1
  }
}
```

--------------------------------

### Check Email Validity

Source: https://www.usercheck.com/docs/api/introduction

Example request to verify an email address using cURL.

```bash
curl -X GET "https://api.usercheck.com/email/octocat@github.com" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Add Domain Error Response (422)

Source: https://www.usercheck.com/docs/api/blocklist-endpoint

Example of an error response when attempting to add a domain that is already blocklisted.

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "domain": ["The domain has already been blocklisted for this environment."]
  }
}
```

--------------------------------

### Request Domain Details with cURL

Source: https://www.usercheck.com/docs/api/domain-endpoint

Perform a GET request to the domain endpoint using an API key for authentication.

```bash
curl -X GET "https://api.usercheck.com/domain/github.com" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### GET /email/{email}

Source: https://www.usercheck.com/docs/api/email-endpoint

Checks if an email address is disposable and retrieves additional details about the email and its domain.

```APIDOC
## GET /email/{email}

### Description
Checks if an email address is disposable and retrieves additional details about the email and its domain.

### Method
GET

### Endpoint
/email/{email}

### Parameters
#### Path Parameters
- **email** (string) - Required - The email address to check (e.g., octocat@github.com)

### Request Example
```bash
curl -X GET "https://api.usercheck.com/email/octocat@github.com" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **status** (integer) - The HTTP status code.
- **email** (string) - The original email address.
- **normalized_email** (string) - The normalized email address.
- **domain** (string) - The domain of the email address.
- **domain_authority** (integer) - The authority score of the domain.
- **tld_trust** (integer) - The trust score of the top-level domain.
- **domain_age_in_days** (integer) - The age of the domain in days.
- **mx** (boolean) - Indicates if Mail Exchanger (MX) records are present.
- **mx_records** (array) - A list of MX records for the domain.
- **mx_providers** (array) - Information about the MX record providers.
- **disposable** (boolean) - Indicates if the email address is disposable.
- **public_domain** (boolean) - Indicates if the domain is public.
- **relay_domain** (boolean) - Indicates if the domain is a relay domain.
- **alias** (boolean) - Indicates if the email is an alias.
- **role_account** (boolean) - Indicates if the email is a role account.
- **spam** (boolean) - Indicates if the email is associated with spam.
- **did_you_mean** (string) - Suggestion for a similar email address if applicable.
- **blocklisted** (boolean) - Indicates if the email address is blocklisted.

#### Response Example
```json
{
  "status": 200,
  "email": "octocat@github.com",
  "normalized_email": "octocat@github.com",
  "domain": "github.com",
  "domain_authority": 96,
  "tld_trust": 1,
  "domain_age_in_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,
  "alias": false,
  "role_account": false,
  "spam": false,
  "did_you_mean": null,
  "blocklisted": false
}
```
```

--------------------------------

### GET /domain/{domain}

Source: https://www.usercheck.com/docs/api/domain-endpoint

Check if a domain is used for disposable email addresses and retrieve detailed domain metadata.

```APIDOC
## GET /domain/{domain}

### Description
Check if a domain is used for disposable email addresses and get additional domain details.

### Method
GET

### Endpoint
/domain/{domain}

### Parameters
#### Path Parameters
- **domain** (string) - Required - The domain to check (e.g., github.com)

### Request Example
curl -X GET "https://api.usercheck.com/domain/github.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

### Response
#### Success Response (200)
- **status** (integer) - HTTP status code
- **domain** (string) - The normalized domain name
- **domain_authority** (integer|null) - 0-100 score of domain credibility (Pro Plan)
- **tld_trust** (integer|null) - 1-5 score of TLD registration strictness (Pro Plan)
- **domain_age_in_days** (integer|null) - Days since registration
- **mx** (boolean) - Whether domain has valid MX records
- **mx_records** (array) - List of MX records
- **mx_providers** (array) - Third-party MX services
- **disposable** (boolean) - Whether domain is a disposable email provider
- **disposable_provider** (string) - Provider domain if disposable (Pro Plan)
- **public_domain** (boolean) - Whether domain is a public email service
- **relay_domain** (boolean) - Whether domain is an email forwarding service
- **did_you_mean** (string|null) - Suggested correction for typos
- **blocklisted** (boolean) - Whether domain is on custom blocklist (Pro Plan)
- **spam** (boolean) - Whether domain is associated with spam activity

#### Response Example
{
  "status": 200,
  "domain": "github.com",
  "domain_authority": 96,
  "tld_trust": 1,
  "domain_age_in_days": 6712,
  "mx": true,
  "mx_records": [
      { "hostname": "aspmx.l.google.com", "priority": 1 }
  ],
  "mx_providers": [
      { "slug": "google", "type": "mailbox", "grade": "professional" }
  ],
  "disposable": false,
  "public_domain": false,
  "relay_domain": false,
  "spam": false,
  "did_you_mean": null,
  "blocklisted": false
}
```

--------------------------------

### Verify Webhook Signature in Node.js

Source: https://www.usercheck.com/docs/webhooks/security

Implement webhook signature verification in Node.js using the `crypto` module and Express. Ensure your webhook secret is kept secure. This example uses `crypto.timingSafeEqual` for constant-time comparison to prevent timing attacks.

```javascript
const crypto = require('crypto');
const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
    const payload = req.body;
    const signature = req.headers['x-usercheck-signature'] || '';
    const secret = 'your_webhook_secret';

    function generateSignature(payload, secret) {
        const payloadString = JSON.stringify(payload);
        return crypto.createHmac('sha256', secret)
                     .update(payloadString)
                     .digest('hex');
    }

    function verifySignature(payload, signature, secret) {
        const expectedSignature = generateSignature(payload, secret);
        return crypto.timingSafeEqual(
            Buffer.from(expectedSignature, 'hex'),
            Buffer.from(signature, 'hex')
        );
    }

    try {
        if (verifySignature(payload, signature, secret)) {
            // Process the webhook
            const { event, data } = payload;
            const { domain } = data;
            
            switch (event) {
                case 'domain.flagged.disposable':
                    // Handle disposable domain flagging
                    break;
                case 'domain.flagged.relay':
                    // Handle relay domain flagging
                    break;
                case 'domain.flagged.spam':
                    // Handle spam domain flagging
                    break;
            }
            
            res.status(200).json({ status: 'success' });
        } else {
            res.status(401).json({ status: 'error', message: 'Invalid signature' });
        }
    } catch (error) {
        res.status(400).json({ status: 'error', message: 'Verification failed' });
    }
});

```

--------------------------------

### Verify Webhook Signature in PHP

Source: https://www.usercheck.com/docs/webhooks/security

Implement webhook signature verification in PHP using HMAC SHA-256. Ensure your webhook secret is kept secure and never shared. This example uses `hash_equals` for constant-time comparison to prevent timing attacks.

```php
<?php
// Get the payload and signature from the webhook request
$payload = json_decode(file_get_contents('php://input'), true);
$signature = $_SERVER['HTTP_X_USERCHECK_SIGNATURE'] ?? '';
$secret = 'your_webhook_secret';

// Generate the expected signature
function generateSignature(array $payload, string $secret): string {
    $payloadJson = json_encode($payload);
    return hash_hmac('sha256', $payloadJson, $secret);
}

// Verify using constant-time comparison
function verifySignature(array $payload, string $signature, string $secret): bool {
    $expectedSignature = generateSignature($payload, $secret);
    return hash_equals($expectedSignature, $signature);
}

// Check if the signature is valid
if (verifySignature($payload, $signature, $secret)) {
    // Process the webhook
    $event = $payload['event'];
    $domain = $payload['data']['domain'];
    
    switch ($event) {
        case 'domain.flagged.disposable':
            // Handle disposable domain flagging
            break;
        case 'domain.flagged.relay':
            // Handle relay domain flagging
            break;
        case 'domain.flagged.spam':
            // Handle spam domain flagging
            break;
    }
    
    http_response_code(200);
    echo json_encode(['status' => 'success']);
} else {
    // Invalid signature
    http_response_code(401);
    echo json_encode(['status' => 'error', 'message' => 'Invalid signature']);
}
?>
```

--------------------------------

### Running Tests

Source: https://www.usercheck.com/docs/integrations/laravel

Execute the project's tests using Composer to ensure the package is functioning correctly.

```bash
composer test
```

--------------------------------

### POST /blocklist/bulk

Source: https://www.usercheck.com/docs/api/blocklist-endpoint

Add multiple domains to your account's blocklist in a single request.

```APIDOC
## POST /blocklist/bulk

### Description
Add multiple domains to your account's blocklist in a single request.

### Method
POST

### Endpoint
/blocklist/bulk

### Parameters
#### Request Body
- **domains** (array) - Required - Array of domains to add (max 1,000 domains)

### Request Example
curl -X POST "https://api.usercheck.com/blocklist/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": [
      "example1.com",
      "example2.com",
      "example3.com"
    ]
  }'

### Response
#### Success Response (200)
- **succeeded** (integer) - Count of successful additions
- **failed** (integer) - Count of failed additions
- **success** (array) - List of successfully added domains
- **errors** (array) - List of errors for failed domains

#### Response Example
{
  "succeeded": 2,
  "failed": 1,
  "success": [
    {
      "domain": "example1.com",
      "created_at": "2024-01-28T12:00:00+00:00"
    }
  ],
  "errors": [
    {
      "domain": "example3.com",
      "error": "The domain has already been blocklisted for this environment."
    }
  ]
}
```

--------------------------------

### Authenticate with API Key via Query Parameter

Source: https://www.usercheck.com/docs/api/authentication

Pass the API key as a query parameter. This method is not recommended due to security risks.

```bash
curl -X GET "https://api.usercheck.com/email/test@example.com?key=YOUR_API_KEY"
```

--------------------------------

### Configure UserCheck API Key

Source: https://www.usercheck.com/docs/integrations/laravel

Add your UserCheck API key to the .env file for authentication. Obtain your API key from app.usercheck.com.

```dotenv
USERCHECK_API_KEY=your_api_key_here
```

--------------------------------

### POST /blocklist

Source: https://www.usercheck.com/docs/api/blocklist-endpoint

Add a new domain to your account's blocklist.

```APIDOC
## POST /blocklist

### Description
Add a new domain to your account's blocklist.

### Method
POST

### Endpoint
/blocklist

### Parameters
#### Request Body
- **domain** (string) - Required - The domain to add to the blocklist (e.g., example.com)

### Request Example
curl -X POST "https://api.usercheck.com/blocklist" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

### Response
#### Success Response (200)
- **domain** (string) - The added domain
- **created_at** (string) - Timestamp of creation

#### Response Example
{
  "domain": "example.com",
  "created_at": "2024-01-28T12:00:00+00:00"
}
```

--------------------------------

### Authenticate with API Key via Header

Source: https://www.usercheck.com/docs/api/authentication

Include the API key in the Authorization header for all requests. This is the recommended method for security.

```bash
curl -X GET "https://api.usercheck.com/email/test@example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Bulk Add Domains to Blocklist

Source: https://www.usercheck.com/docs/api/blocklist-endpoint

Add multiple domains to your blocklist in a single request, with a maximum of 1,000 domains per request. Duplicate domains within the same request are automatically handled.

```bash
curl -X POST "https://api.usercheck.com/blocklist/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": [
      "example1.com",
      "example2.com",
      "example3.com"
    ]
  }'
```

--------------------------------

### Check Current Credit Usage

Source: https://www.usercheck.com/docs/get-started/credits

Use the Status endpoint to retrieve your current credit usage, including your plan's limit, current consumption, and remaining credits for the billing period. Ensure you include your API key in the Authorization header.

```bash
curl -X GET "https://api.usercheck.com/status" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Domain Not Found (404) Error

Source: https://www.usercheck.com/docs/api/blocklist-endpoint

Indicates that the specified domain was not found in the blocklist.

```json
{
  "message": "Domain not found in blocklist"
}
```

--------------------------------

### Add Domain to Blocklist

Source: https://www.usercheck.com/docs/api/blocklist-endpoint

Add a single domain to your account's blocklist. The domain must be provided in the request body as a JSON string.

```bash
curl -X POST "https://api.usercheck.com/blocklist" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'
```

--------------------------------

### Check if Domain is Blocklisted

Source: https://www.usercheck.com/docs/api/blocklist-endpoint

Verify if a specific domain is present in your account's blocklist. The domain to check is included as a path parameter.

```bash
curl -X GET "https://api.usercheck.com/blocklist/example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### List Blocklisted Domains

Source: https://www.usercheck.com/docs/api/blocklist-endpoint

Retrieve a paginated list of all domains currently in your account's blocklist. Specify the number of results per page using the `per_page` query parameter.

```bash
curl -X GET "https://api.usercheck.com/blocklist" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Publishing Language Files

Source: https://www.usercheck.com/docs/integrations/laravel

Publish the package's language files to customize error messages. This makes translation files available for editing.

```bash
php artisan vendor:publish --provider="UserCheck\Laravel\UserCheckProvider" --tag="lang"
```

--------------------------------

### Set Base URL

Source: https://www.usercheck.com/docs/api/introduction

The root endpoint for all API requests.

```text
https://api.usercheck.com
```

--------------------------------

### Authenticate with JavaScript fetch

Source: https://www.usercheck.com/docs/api/authentication

Use the fetch API to include the Authorization header in your request.

```javascript
const response = await fetch('https://api.usercheck.com/email/test@example.com', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
```

--------------------------------

### Using UserCheck Facade for Validation

Source: https://www.usercheck.com/docs/integrations/laravel

Utilize the UserCheck Facade to programmatically validate emails or domains. This provides direct access to validation methods.

```php
use UserCheck\Laravel\Facades\UserCheck;

$result = UserCheck::validateEmail('test@example.com');
$result = UserCheck::validateDomain('example.com');
```

--------------------------------

### Implement Gate Decision Endpoint

Source: https://www.usercheck.com/docs/gates/quickstart

Use this cURL request to send user data to the UserCheck decision endpoint for evaluation against your configured rules.

```bash
curl -X POST "https://api.usercheck.com/v0/gates/{gate_id}/decisions" \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "ip": "1.1.1.1"}'
```

--------------------------------

### Authenticate with PHP cURL

Source: https://www.usercheck.com/docs/api/authentication

Set the Authorization header in the cURL options array.

```php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.usercheck.com/email/test@example.com');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);
```

--------------------------------

### Validation Failed (422) Error - Bulk Domains

Source: https://www.usercheck.com/docs/api/blocklist-endpoint

Returned for invalid data during bulk operations, specifically when the 'domains' field is missing or invalid.

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "domains": ["The domains field is required."]
  }
}
```

--------------------------------

### Pro Account Required (403) Error

Source: https://www.usercheck.com/docs/api/blocklist-endpoint

Returned when a Pro account is necessary for the requested feature.

```json
{
  "message": "This feature requires a Pro account"
}
```

--------------------------------

### Webhook Events

Source: https://www.usercheck.com/docs/webhooks/events

This section lists the available webhook events and the conditions under which they are triggered.

```APIDOC
## Webhook Events

This section lists the available webhook events and the conditions under which they are triggered.

### Available Events

- **`domain.flagged.disposable`**: Triggers when a new domain is flagged as disposable.
- **`domain.flagged.relay`**: Triggers when a new domain is flagged as a relay domain.
- **`domain.flagged.spam`**: Triggers when a new domain is flagged as a spam domain.
- **`domain.unflagged.disposable`**: Triggers when a domain changes from `disposable: true` to `disposable: false`.
- **`domain.unflagged.relay`**: Triggers when a relay domain is no longer flagged.
- **`domain.unflagged.spam`**: Triggers when a spam domain is no longer flagged.
- **`blocklist.domain.created`**: Triggers when a new domain is added to your account's blocklist.
- **`blocklist.domain.deleted`**: Triggers when a domain is removed from your account's blocklist.
```

--------------------------------

### Rule Evaluation Model

Source: https://www.usercheck.com/docs/gates/rules-conditions

Explains the logic by which rules are evaluated and a final decision is made.

```APIDOC
## Rule Evaluation Model

### Description
Explains the process of evaluating rules and determining the final decision.

### Process
1. Rules are processed **top → bottom**.
2. For each rule, conditions are evaluated using the rule’s `match` mode (`all` or `any`).
3. If the rule **matches**:
   * Its `action` becomes the **current decision**.
   * If `stop: true`, evaluation ends and this action is **final**.
4. If multiple rules match and none had `stop: true`, the **last matching rule** wins.
```

--------------------------------

### Authentication Header

Source: https://www.usercheck.com/docs/gates/decision-endpoint

Include the API key in the Authorization header for all requests.

```http
Authorization: Bearer <YOUR_API_KEY>
```

--------------------------------

### POST /v0/gates/{gate_id}/decisions

Source: https://www.usercheck.com/docs/gates/decision-endpoint

Request a decision from a Gate to allow, block, or challenge a user action. Requires authentication via an API key in the Authorization header.

```APIDOC
## POST /v0/gates/{gate_id}/decisions

### Description
Request a decision from a Gate to allow, block, or challenge a user action.

### Method
POST

### Endpoint
/v0/gates/{gate_id}/decisions

### Parameters
#### Path Parameters
- **gate_id** (string) - Required - The ID of the Gate to evaluate.

#### Query Parameters
None

#### Request Body
- **email** (string) - Required (if domain is not provided) - The email address to evaluate.
- **domain** (string) - Required (if email is not provided) - The domain to evaluate.
- **ip** (string) - Optional - The IP address for additional intelligence.

### Request Example
```json
{
  "email": "octocat@github.com",
  "ip": "1.1.1.1"
}
```

### Response
#### Success Response (200)
- **input** (object) - The input provided for the decision request.
- **decision** (object) - The decision made by the Gate, including action and matched rule.
- **signals** (object) - Detailed signals related to the input (email, domain, IP).
- **meta** (object) - Metadata about the request, including version, request ID, and duration.

#### Response Example
```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
- `400 both_email_and_domain_provided`: Both `email` and `domain` were provided
- `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
```

--------------------------------

### Verify and Handle Webhooks in Python

Source: https://www.usercheck.com/docs/webhooks/security

Uses HMAC-SHA256 to verify the X-UserCheck-Signature header before processing event payloads. Ensure the secret matches the one configured in your UserCheck dashboard.

```python
import json
import hmac
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook_handler():
    payload = request.json
    signature = request.headers.get('X-UserCheck-Signature', '')
    secret = 'your_webhook_secret'

    def generate_signature(payload, secret):
        payload_json = json.dumps(payload)
        return hmac.new(
            secret.encode('utf-8'),
            payload_json.encode('utf-8'),
            hashlib.sha256
        ).hexdigest()

    def verify_signature(payload, signature, secret):
        expected_signature = generate_signature(payload, secret)
        return hmac.compare_digest(expected_signature, signature)

    if verify_signature(payload, signature, secret):
        # Process the webhook
        event = payload['event']
        domain = payload['data']['domain']
        
        if event == 'domain.flagged.disposable':
            # Handle disposable domain flagging
            pass
        elif event == 'domain.flagged.relay':
            # Handle relay domain flagging
            pass
        elif event == 'domain.flagged.spam':
            # Handle spam domain flagging
            pass
        
        return jsonify({'status': 'success'}), 200
    else:
        return jsonify({'status': 'error', 'message': 'Invalid signature'}), 401

if __name__ == '__main__':
    app.run(debug=True)
```

--------------------------------

### DELETE /blocklist/{domain}

Source: https://www.usercheck.com/docs/api/blocklist-endpoint

Remove a domain from your account's blocklist for the current environment.

```APIDOC
## DELETE /blocklist/{domain}

### Description
Remove a domain from your account's blocklist for the current environment.

### Method
DELETE

### Endpoint
/blocklist/{domain}

### Parameters
#### Path Parameters
- **domain** (string) - Required - The domain to remove (e.g., example.com)

### Request Example
curl -X DELETE "https://api.usercheck.com/blocklist/example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

### Response
#### Success Response (200)
- **message** (string) - Success message

#### Response Example
{
  "message": "Domain removed from blocklist successfully"
}
```

--------------------------------

### Successful Status Response (200)

Source: https://www.usercheck.com/docs/api/status-endpoint

This JSON object represents a successful response from the status endpoint, detailing account plan, user information, and current usage metrics.

```json
{
  "status": "success",
  "account": {
    "plan": {
      "name": "Pro 200K",
      "credits": 200000,
      "rate_limit": 15
    },
    "user": {
      "name": "Jane Doe",
      "email": "jane@example.com"
    }
  },
  "usage": {
    "limit": 200000,
    "current": 48320,
    "remaining": 151680,
    "reset_at": "2026-04-01T00:00:00.000000Z"
  }
}
```

--------------------------------

### Check Domain Action

Source: https://www.usercheck.com/docs/integrations/zapier

This action checks if a domain is disposable or suspicious, providing domain reputation information.

```APIDOC
## POST /zapier/actions/check_domain

### Description
Checks if a domain is disposable or suspicious.

### Method
POST

### Endpoint
/zapier/actions/check_domain

### Parameters
#### Request Body
- **domain** (string) - Required - The domain to check (e.g., `example.com`)

### Request Example
{
  "domain": "example.com"
}

### Response
#### Success Response (200)
- **disposable** (boolean) - Indicates if the domain is disposable.
- **mx** (boolean) - Indicates if the domain has MX records.
- **spam** (boolean) - Indicates if the domain is associated with spam.
- **blocklisted** (boolean) - Indicates if the domain is blocklisted.

#### Response Example
{
  "disposable": false,
  "mx": true,
  "spam": false,
  "blocklisted": false
}
```

--------------------------------

### Call Gate Decision Endpoint

Source: https://www.usercheck.com/docs/gates/migrate-from-email-domain

Replace /email or /domain calls with a POST request to your Gate's Decision endpoint. Specify the input type (email or domain) in the JSON payload.

```bash
curl -X POST "https://api.usercheck.com/v0/gates/{gate_id}/decisions" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "email": "user@example.com" }'
```

--------------------------------

### Authenticate with Python requests

Source: https://www.usercheck.com/docs/api/authentication

Pass the Authorization header using the headers dictionary in the requests library.

```python
import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('https://api.usercheck.com/email/test@example.com', headers=headers)
```

--------------------------------

### Customizing Validation Rule Options

Source: https://www.usercheck.com/docs/integrations/laravel

Customize the 'usercheck' rule with parameters to control validation behavior, such as blocking disposable or no-MX record domains.

```php
$request->validate([
    'email' => 'required|email|usercheck:domain_only,block_disposable,block_no_mx,block_spam',
]);
```

--------------------------------

### Webhook Request Headers

Source: https://www.usercheck.com/docs/webhooks/events

Lists the important headers included in webhook requests for verification and information.

```APIDOC
## Webhook Request Headers

When we send a webhook to your endpoint, the request includes several helpful headers:

| Header | Description |
|--------|-------------|
| `X-UserCheck-Signature` | HMAC SHA-256 signature for verification |
| `X-UserCheck-Event-Type` | The event type (e.g., `domain.flagged.disposable`) |
| `X-UserCheck-Delivery-ID` | Unique identifier for this delivery attempt |
| `X-UserCheck-Attempt` | Current attempt number |
```

--------------------------------

### Decision Endpoint URL

Source: https://www.usercheck.com/docs/gates/decision-endpoint

The base endpoint for requesting a decision from a specific gate.

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

--------------------------------

### Supported Email Fields

Source: https://www.usercheck.com/docs/gates/rules-conditions

Lists the fields related to email that can be used in rule conditions.

```APIDOC
## Supported Email Fields

### Description
Lists the fields related to email that can be used in rule conditions. All string comparisons are **case‑insensitive** unless noted.

### Fields
- **email.address** (string) - The full email address.
- **email.normalized** (string) - The normalized email address.
- **email.local_part** (string) - Local part of the email address. For example, `user` in `user@example.com`.
- **email.subaddress** (string) - Subaddress of the email address. For example, `newsletter` in `user+newsletter@example.com`.
- **email.disposable** (boolean) - Email is disposable while domain is not. For providers offering disposable aliases on legit domains (e.g. Gmail or Outlook).
- **email.role_account** (boolean) - Local part is a role account (`admin@`, `support@`).
```