ReachCheck API

Check whether a server IP is reachable from real residential connections, by country, state and network provider. Every request carries your key in the X-API-Key header.

Base URL

https://ip.builtforyou.dev/api/v1

Auth header

X-API-Key: rc_your_key_here

Keys are issued by the operator. Countries available now: GB, US, CA.

Start a check

POST /api/v1/checks
Content-Type: application/json
X-API-Key: rc_your_key_here

{
  "ip": "203.0.113.10",
  "port": 8080,
  "protocol": "http",          // tcp | http | https
  "country": "GB",
  "states": ["gb-sct", "gb-eng"],   // optional; omit for whole country
  "providers": [5089, 2856],        // optional ASN list; omit = busiest networks
  "top_providers": 3,                // used when providers omitted
  "webhook_url": "https://you.example.com/hook"  // optional, called when done
}

Returns 202 with an id and a poll URL:

{ "id": "chk_1a2b3c4d", "status": "queued", "poll": "https://ip.builtforyou.dev/api/v1/checks/chk_1a2b3c4d" }

Get the result

GET /api/v1/checks/chk_1a2b3c4d
GET /api/v1/checks/chk_1a2b3c4d?wait=30   // long-poll up to 30s for it to finish

{
  "id": "chk_1a2b3c4d",
  "status": "done",
  "message": "reachable from 5 of 6 lines",
  "ip": "203.0.113.10", "port": 8080, "protocol": "http", "country": "GB",
  "tested_as": "203-0-113-10.ip.example.com",
  "summary": { "total": 6, "reachable": 5, "not_reachable": 1, "reachable_percent": 83 },
  "results": [
    { "state_name": "Scotland", "provider": "Virgin Media", "provider_asn": 5089,
      "reachable": true, "stage": "http", "latency_ms": 412, "http_status": 200,
      "feedback": "Reached port 8080 from Virgin Media in Scotland in 412 ms, HTTP 200" },
    { "state_name": "England", "provider": "Sky Broadband", "provider_asn": 5607,
      "reachable": false, "stage": "connect", "error": "timed out after 15s",
      "feedback": "Not reached from Sky Broadband in England: timed out after 15s" }
  ]
}

While status is queued, dns or running, poll again. Final status is done or failed.

Helpers

GET /api/v1/me          # your plan and usage this month
GET /api/v1/countries   # countries you can test
GET /api/v1/states?country=GB
GET /api/v1/providers?country=GB&state=gb-sct   # ASNs with the most lines

Errors

JSON body with an error string. 401 bad key, 402 monthly limit reached, 403 account paused, 429 too fast, 400 bad input.

curl example

curl -s https://ip.builtforyou.dev/api/v1/checks \
  -H "X-API-Key: rc_your_key_here" -H "Content-Type: application/json" \
  -d '{"ip":"203.0.113.10","port":443,"protocol":"https","country":"GB","top_providers":3}'