Blocklist Endpoint - Documentation

The blocklist endpoints manage a custom list of domains treated as blocked for your account. A domain on the list returns blocklisted: true from the domain and email endpoints, and satisfies the domain.blocklisted condition in Gates. The list is scoped to one environment and requires a Pro account.

The blocklisted domain object

{
  "domain": "example.com",
  "created_at": "2025-01-27T23:32:12+00:00"
}

Field	Type	Description
`domain`	string	The blocklisted domain, in normalized form: lowercased, with internationalized names converted to their ASCII (punycode) representation. This is the form the domain and email endpoints match against.
`unicode_domain`	string	The domain in its readable unicode form, for example `online.移动` for `online.xn--6frz82g`. Only present when it differs from `domain`, so only for internationalized domains.
`created_at`	string	ISO 8601 timestamp of when the domain was added.

unicode_domain is omitted from the sample above because example.com is not an internationalized domain. It appears alongside domain only when the two differ.

Endpoints that return a single domain wrap it in a top-level data key. The bulk endpoint is the exception: it reports the domains it added unwrapped, inside its own success array.

List blocklisted domains

Get a paginated list of the domains in your account's blocklist for the key's environment, newest first.

Endpoint

GET /blocklist

Query parameters

Parameter	Type	Required	Description
`page`	integer	No	Page to return (default: 1)
`per_page`	integer	No	Results per page, clamped to 1–100 (default: 25)

Request example

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

Success response (200)

{
  "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": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://api.usercheck.com/blocklist?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "path": "https://api.usercheck.com/blocklist",
    "per_page": 25,
    "to": 1,
    "total": 1
  }
}

Add a domain to the blocklist

Add a new domain to your account's blocklist.

Endpoint

POST /blocklist

Request body

Field	Type	Required	Description
`domain`	string	Yes	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"}'

Success response (201)

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

Domain already blocklisted (422)

{
  "message": "The domain has already been blocklisted for this environment.",
  "errors": {
    "domain": ["The domain has already been blocklisted for this environment."]
  }
}

Bulk add domains to the blocklist

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

Endpoint

POST /blocklist/bulk

Request body

Field	Type	Required	Description
`domains`	array	Yes	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"
    ]
  }'

Success response (200)

{
  "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."
    }
  ]
}

Validation rules

Maximum 1,000 domains per request
Duplicate domains in the same request are automatically deduplicated
Each domain must be a valid domain format

Check if a domain is blocklisted

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

Endpoint

GET /blocklist/{domain}

Path parameters

Parameter	Type	Required	Description
`domain`	string	Yes	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"

Success response (200)

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

Remove a domain from the blocklist

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

Endpoint

DELETE /blocklist/{domain}

Path parameters

Parameter	Type	Required	Description
`domain`	string	Yes	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"

Success response (200)

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

Error responses

Unauthorized (401)

{
  "message": "API key is required"
}

message is "API key is required" when the request carried no API key, and "Invalid API key" when the key is not recognized.

Pro account required (403)

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

Domain not found (404)

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

Validation failed (422)

{
  "message": "The domain is invalid.",
  "errors": {
    "domain": ["The domain is invalid."]
  }
}

message carries the first error from errors, with (and N more errors) appended when there is more than one.

For bulk operations:

{
  "message": "The domains field is required.",
  "errors": {
    "domains": ["The domains field is required."]
  }
}

Environment handling

The blocklist is environment-specific. A domain blocklisted with a development key does not affect production traffic, and the reverse. The environment is determined by the API key used in the request, never by a parameter. See Environments.