# Check name

`POST https://api.unique.domains/v1/names/{name}/check`

Reads one name live from its registry and a registrar, stores the answer and returns the keyed name resource.

Billed `Live=1` when the live read answered (200, `checked: true`) or when the registry was asked and did not conclude (202); `Live=0` when the answer came from storage (200, `checked: false`). Asking `value` or `history` answers 202 with the stored resource so far, `Retry-After: 30` and `Location`; the check never runs the appraisal (`POST /names/{name}/appraise` does). 2,000 live checks a UTC day for the whole API, 200 per consumer.

- Access: A member key (Founder or Investor) or a paid RapidAPI subscription to this API.
- Billing: One call, plus one live check when the live read runs.
- Formats: JSON
- API: Domain Check API

## Request

| Field | Type | Needs | Where | Description |
| --- | --- | --- | --- | --- |
| `name` | string | Required | Path | A full domain name on an ending the catalog holds, lowercased, IDN as punycode. A bare word, a subdomain, an e-mail address or an unknown ending answers 400 `validation_failed` with `reason` and `suggestion`. |
| `fields` | string | Optional | Query | Comma-separated top-level keys to keep; an unknown key answers 400 `unsupported_field`. |
| `blocks` | string[] | Optional | Body | Optional: the lanes to read. `prices` asks every registrar, `registry` forces the registry record. Default `["availability","registry","dns","prices"]`. |

## Sample request

```bash
curl -X POST "https://api.unique.domains/v1/names/get.plumbing/check" \
  -H "Authorization: Bearer YOUR_MEMBER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "blocks": [
      "availability",
      "registry"
    ]
  }'
```

## Response

| Field | Type | Description |
| --- | --- | --- |
| `id` | string \| null | `dom_<uuid>`; null when `tracked` is false. |
| `name` | string |  |
| `ending` | string |  |
| `tracked` | boolean | The catalog stores the name. |
| `status` | string | Where the name stands for a buyer. A list row's stored status reads here as: `resell` is `for_sale` (`at_auction` at a drop-catch venue), `premium` is `free_premium`. |
| `lifecycle` | string \| null |  |
| `drop` | object |  |
| `ownableNow` | boolean |  |
| `price` | object |  |
| `registry` | object |  |
| `parking` | string \| null | The parking or sale venue id. |
| `length` | integer \| null |  |
| `format` | string \| null |  |
| `shape` | string \| null |  |
| `word` | object \| null |  |
| `rating` | object |  |
| `verdict` | object \| null | Keyed. |
| `value` | object \| null | Keyed. |
| `comps` | object |  |
| `checked` | boolean | The live read answered. |

## Errors

| Code | Status | What it means |
| --- | --- | --- |
| [`validation_failed`](https://unique.domains/api/problems/validation_failed) | 400 | A value is not valid |
| [`keyed_only`](https://unique.domains/api/problems/keyed_only) | 403 | A paid subscription is required |
| [`rate_limited`](https://unique.domains/api/problems/rate_limited) | 429 | Too many requests |
| [`budget_spent`](https://unique.domains/api/problems/budget_spent) | 429 | Today's budget is spent |
| [`internal`](https://unique.domains/api/problems/internal) | 500 | Unexpected error |
| [`check_unavailable`](https://unique.domains/api/problems/check_unavailable) | 503 | The live check is unavailable |

## Example answer

200, application/json

```json
{
  "data": {
    "id": "dom_4efccac7-d9df-4c96-a076-3e0cc64220ec",
    "name": "get.plumbing",
    "ending": "plumbing",
    "tracked": true,
    "status": "for_sale",
    "lifecycle": "active",
    "drop": {
      "kind": "none"
    },
    "ownableNow": false,
    "price": {
      "kind": "aftermarket",
      "firstYear": null,
      "registrar": null,
      "renewal": null,
      "transfer": null,
      "isPromo": null,
      "renewalTrap": false,
      "regularPrice": null
    },
    "registry": {
      "createdAt": "2020-06-03T08:30:53.000Z",
      "updatedAt": "2026-08-12T04:41:40.000Z",
      "expiresAt": "2027-06-03T08:30:53.000Z",
      "registryUpdatedAt": "2026-10-22T13:39:28.000Z",
      "registrar": {
        "name": "GoDaddy.com, LLC",
        "ianaId": 146,
        "url": null
      }
    },
    "parking": "afternic",
    "length": 3,
    "format": null,
    "shape": "single",
    "word": {
      "id": "wrd_23922",
      "word": "get",
      "slug": "get"
    },
    "rating": {
      "band": "prime"
    },
    "comps": {
      "tier": "same_word",
      "count": 10,
      "medianUsd": 2677,
      "endingsSoldOn": 0
    },
    "verdict": {
      "rating": "good",
      "confidence": "medium"
    },
    "value": {
      "value": 4200,
      "upsidePercent": null,
      "liquidity": "medium"
    },
    "checked": true
  },
  "meta": {
    "asOf": "2026-11-05T08:00:00Z",
    "cursor": null,
    "limit": null
  },
  "links": {
    "self": "https://api.unique.domains/v1/names/get.plumbing/check",
    "next": null,
    "register": null,
    "product": null,
    "dataset": null
  }
}
```

API status: https://uniquedomains.instatus.com

Full reference: https://unique.domains/api