Blocklist Endpoint

The blocklist endpoints allow you to manage a custom list of domains that should be treated as blocked for your account. This feature requires a Pro account.

List Blocklisted Domains

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

Endpoint

GET /blocklist

Query Parameters

Parameter	Type	Required	Description
per_page	integer	No	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"

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": "« 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
  }
}

Add Domain to 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 (200)

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

Error Response (422) - Domain Already Blocklisted

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

Bulk Add Domains to 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 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)

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

Remove Domain from 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": "Unauthorized"
}

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 given data was invalid.",
  "errors": {
    "domain": ["The domain is invalid."]
  }
}

For bulk operations:

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

Environment Handling

The blocklist is environment-specific. Domains blocklisted in your test environment will not affect your production environment and vice versa. The environment is determined by the API key used in the request.