Start a blocklist check

POST

/api/v1/blacklist/check

curl --request POST \
  --url https://app.hostrepute.com/api/v1/blacklist/check \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "host": "example.net", "data_source_group_uuid": "01a178db-d581-700d-9729-4f4abc8cee72", "callback_url": "https://hooks.example.com/hostrepute/scans" }'

Start checking a domain or IP against the blocklists in a check profile. The response comes back straight away with the check’s uuid and status; poll GET /api/v1/blacklist/status/{scan_uuid} until is_completed is true or status is failed, or pass a callback_url to be told when it ends. The domain or IP doesn’t have to be one your team monitors.

Costs 1 credit. Needs the blacklist:check ability.

Authorizations

• bearer

Request Body^required

Media typeapplication/json

object

host

required

The domain or IP address to check. A URL is accepted and its host name is used.

string

Example

example.net

data_source_group_uuid

The UUID of the check profile whose blocklists to use. Defaults to your team’s default check profile.

string

nullable

Example

01a178db-d581-700d-9729-4f4abc8cee72

callback_url

A public HTTPS URL that HostRepute sends a POST to when the check ends. The request carries the X-Webhook-Event (blacklist.scan.completed), X-Webhook-Timestamp and X-Webhook-Signature-V3 headers, signed with your team’s webhook secret. Read https://docs.hostrepute.com/developers/webhooks/

string

nullable

Example

https://hooks.example.com/hostrepute/scans

Responses

201

Media typeapplication/json

object

data

object

uuid

string

host

string

status

string

is_completed

boolean

callback_status

string

nullable

data_source_count

integer

completed_source_count

integer

listed_data_source_count

integer

failed_data_source_count

integer

progress_percent

integer

error_message

string

nullable

data_source_group

object

uuid

string

name

string

slug

string

description

string

is_default

boolean

deliverability_checks_enabled

boolean

deliverability_checks

Array<string>

created_at

string

updated_at

string

started_at

string

completed_at

string

nullable

created_at

string

Example

{
  "data": {
    "uuid": "01a178db-d833-70d2-8436-d39da22fcd8a",
    "host": "example.net",
    "status": "processing",
    "is_completed": false,
    "callback_status": null,
    "data_source_count": 4,
    "completed_source_count": 0,
    "listed_data_source_count": 0,
    "failed_data_source_count": 0,
    "progress_percent": 0,
    "error_message": null,
    "data_source_group": {
      "uuid": "01a178db-d581-700d-9729-4f4abc8cee72",
      "name": "Default",
      "slug": "default",
      "description": "All production domains",
      "is_default": true,
      "deliverability_checks_enabled": true,
      "deliverability_checks": [
        "mx_health",
        "spf_record",
        "spf_strict",
        "spf_lookup_limit",
        "dmarc_record",
        "dmarc_strict"
      ],
      "created_at": "2026-07-14T09:12:44.000000Z",
      "updated_at": "2026-09-02T14:05:31.000000Z"
    },
    "started_at": "2026-10-26T15:37:16.000000Z",
    "completed_at": null,
    "created_at": "2026-10-26T15:37:16.000000Z"
  }
}

402

Not enough credits

Media typeapplication/json

object

message

string

required_credits

integer

available_credits

integer

Example

{
  "message": "Insufficient credits.",
  "required_credits": 1,
  "available_credits": 0
}

422

Invalid input

Media typeapplication/json

object

message

string

errors

object

callback_url

Array<string>

Example

{
  "message": "The callback url must be a public HTTPS webhook URL.",
  "errors": {
    "callback_url": [
      "The callback url must be a public HTTPS webhook URL."
    ]
  }
}