---
title: "Check where hostnames point"
url: https://docs.corefinity.com/api/reference/domains/check-site-domains-dns
type: endpoint
last_updated: 2026-11-13
feature: domains
related:
  - https://docs.corefinity.com/guides/sites/go-live/add-a-domain.md
  - https://docs.corefinity.com/mcp/tools/corestack_domains_check_dns.md
---
# Check where hostnames point

Checks the public DNS of up to 10 hostnames and answers whether each points at the platform, with the records
to create. Nothing changes. The person needs the right to change the site.

```http
POST /api/corestack/sites/{site}/domains/check
```

- Scope: `read`
- Two-factor: required on your account (all)
- Rate limit: 20 a minute
- Try it in the console: on

## Path parameters

- `site` (integer, required): The id of a site row. A website's production site and each of its environments has its own id. Digits only.

## Body

- `hosts` (array of strings, required)

## Request

### curl

```bash
curl -X POST https://manage.corefinity.com/api/corestack/sites/1042/domains/check \
  -H "Authorization: Bearer $COREFINITY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "hosts": [
      "harbourandfinch.example.com",
      "www.harbourandfinch.example.com"
    ]
  }'
```

### PHP

```php
use Illuminate\Support\Facades\Http;

$response = Http::withToken(env('COREFINITY_TOKEN'))
    ->acceptJson()
    ->post('https://manage.corefinity.com/api/corestack/sites/1042/domains/check', [
        'hosts' => [
            'harbourandfinch.example.com',
            'www.harbourandfinch.example.com',
        ],
    ]);

$data = $response->json();
```

### Node

```javascript
const res = await fetch('https://manage.corefinity.com/api/corestack/sites/1042/domains/check', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.COREFINITY_TOKEN}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    hosts: [
      'harbourandfinch.example.com',
      'www.harbourandfinch.example.com',
    ],
  }),
});

// An answer with no body (204) has nothing to parse.
const text = await res.text();
const data = text && JSON.parse(text);
```

### Python

```python
import os
import requests

res = requests.post(
    "https://manage.corefinity.com/api/corestack/sites/1042/domains/check",
    headers={
        "Authorization": f"Bearer {os.environ['COREFINITY_TOKEN']}",
        "Accept": "application/json",
    },
    json={
        "hosts": [
            "harbourandfinch.example.com",
            "www.harbourandfinch.example.com",
        ],
    },
)

data = res.json() if res.content else None
```

## Responses

### 200 The state of each hostname.

```json
{
  "advice": null,
  "dns_plan": {
    "actions": [
      {
        "action": "keep",
        "existing": null,
        "host": "harbourandfinch.example.com",
        "reason": null,
        "record": {
          "content": "203.0.113.10",
          "name": "harbourandfinch.example.com",
          "proxied": true,
          "type": "A"
        }
      },
      {
        "action": "manual",
        "existing": null,
        "host": "shop.harbourandfinch.example.com",
        "reason": "Not in a connected Cloudflare zone. Add an A record to 203.0.113.10",
        "record": null
      }
    ],
    "can_apply": false,
    "requires_confirmation": false,
    "zone": null
  },
  "hosts": [
    {
      "cloudflare_zone": null,
      "dns_answers": [
        {
          "type": "A",
          "value": "203.0.113.10"
        }
      ],
      "dns_checked_at": "2026-11-06T09:16:05Z",
      "dns_detail": null,
      "dns_state": "points_here",
      "dns_state_since": "2026-11-01T10:14:03Z",
      "expected_ip": "203.0.113.10",
      "host": "harbourandfinch.example.com",
      "noindex": false,
      "ok": true,
      "problems": [],
      "redirects_to": null,
      "role": "primary",
      "tls": {
        "checked_at": "2026-11-06T09:14:41Z",
        "issuer": "Let's Encrypt",
        "not_after": "2026-12-08T05:41:17Z",
        "reason": null,
        "state": "ready"
      }
    },
    {
      "cloudflare_zone": null,
      "dns_answers": [
        {
          "type": "A",
          "value": "198.51.100.9"
        }
      ],
      "dns_checked_at": "2026-11-06T09:16:05Z",
      "dns_detail": "direct",
      "dns_state": "elsewhere",
      "dns_state_since": null,
      "expected_ip": "203.0.113.10",
      "host": "shop.harbourandfinch.example.com",
      "noindex": false,
      "ok": false,
      "problems": [
        "Points at 198.51.100.9. Update the A record to 203.0.113.10"
      ],
      "redirects_to": null,
      "role": "alias",
      "tls": {
        "checked_at": null,
        "issuer": null,
        "not_after": null,
        "reason": null,
        "state": "none"
      }
    }
  ],
  "ok": false,
  "ran_at": "2026-11-06T09:16:05Z"
}
```

### 401 No token, or a token that is not valid.

```json
{
  "message": "Unauthenticated."
}
```

### 403 The token lacks the scope (`scope_required`, with the `scope` to use), your company requires two-factor authentication and you have not set it up, or your account has no company that can use Managed Clusters, for example because the company was closed (`company_unavailable` or `company_not_enabled`, whichever the route checks first). For Managed Clusters routes; any other route uses `ForbiddenScopeOrTwoFactor`.

```json
{
  "code": "company_unavailable",
  "message": "Your company is unavailable.",
  "reason": "company_unavailable"
}
```

### 404 The id does not exist or is something you cannot see, or the feature is not on for your company (`feature_off`).

```json
{
  "code": "feature_off",
  "message": "Not found.",
  "reason": "feature_off"
}
```

### 409 The site is deleted (`deleted`) or still being created (`provisioning`).

```json
{
  "code": "deleted",
  "message": "This site is deleted and waiting to be purged. Restore it first.",
  "reason": "deleted"
}
```

### 422 A field is missing or wrong. `field` names the first one and `errors` lists every one.

```json
{
  "code": "invalid",
  "errors": {
    "enabled": [
      "The enabled field is required."
    ]
  },
  "field": "enabled",
  "message": "The enabled field is required.",
  "reason": "invalid"
}
```

### 429 Too many requests (`rate_limited`). Wait for the number of seconds in `Retry-After`, which `retry_after_seconds` repeats.

```json
{
  "code": "rate_limited",
  "message": "Too many requests. Try again in 60 seconds.",
  "reason": "rate_limited",
  "retry_after_seconds": 60
}
```

### 502 A check or a write outside the Control Panel could not run. Try again in a moment.

```json
{
  "message": "The DNS check could not run. Try again in a moment."
}
```

## If it is refused

| Status | Reason | What to do |
|---|---|---|
| 401 |  | Send a valid token as `Authorization: Bearer <token>`. |
| 403 | `company_unavailable` | Your company is unavailable. |
| 403 | `scope_required` | Use a token with the scope named in `scope`. |
| 403 | `two_factor_required` | Turn on two-factor on your account, then send again. |
| 404 | `feature_off` | This feature is not on for your organisation yet. |
| 409 | `deleted` | The site, environment or copy has been deleted, or is being deleted. Nothing can be changed on it. Restore a deleted site first if it can still be restored. |
| 409 | `provisioning` | The site is still being created. Try again in a few minutes. |
| 422 | `invalid` | Fix the field named in `field`; `errors` says why. |
| 429 | `rate_limited` | Wait for the seconds in `Retry-After`. |
| 502 |  | Read the message; it says what happened. |

## The same task elsewhere

- Guide: [Add a domain](https://docs.corefinity.com/guides/sites/go-live/add-a-domain.md)
- MCP tool: [`corestack_domains_check_dns`](https://docs.corefinity.com/mcp/tools/corestack_domains_check_dns.md)
