Check domain availability

​

Checks availability of specific domain names via Server-Sent Events (SSE).

Use this endpoint when you have specific FQDNs to check, such as domains from a user's cart or watchlist.

Request format: {"domains": ["example.com", "test.net"]}

The response is a Server-Sent Events stream. Each event's event: field names its type and its data: line is a JSON object. SSE payloads cannot be expressed as OpenAPI response schemas, so the per-event shapes are given here:

  • check: one event per domain checked, shaped as the DomainCheck schema (the 200 response schema below).
  • complete: terminal event with aggregate counts. Shape:
{"object":"domain_check_complete","total_checked":2,"available_count":1,"time_taken_ms":125}

Domains already in your inventory. A check event carries an optional inventory object when the domain is already held by the organization the request is scoped to. Use it to link the row to GET /domains/{id} rather than offering the name for sale.

inventory is independent of available; the two answer different questions. A domain you hold normally reads available: false, but a name whose registration lapsed and dropped reads available: true while still carrying the entry recording that you held it. Read both fields before deciding what to render.

inventory.kind says what the entry is:

Kind Meaning
managed Registered through us; renewable and manageable here
external Tracked in your inventory but registered elsewhere
backorder Not held; a watch you placed on a name somebody else holds

Domains you transferred away, deleted, or stopped backordering are history and never carry an inventory entry. Neither does any result for a request with no organization in scope.

Permissions
Key type Accepted Permission required Notes
Org API key yes domain:read inventory reflects the key's organization
Personal API key yes domain:read X-Org-ID is not required; without it results carry no inventory
Error Codes
Code HTTP Description
authorize.unauthenticated 401 No valid API key credentials
authorize.forbidden 403 Missing domain:read permission
request.decode_failed 400 Failed to decode request body
request.validation_failed 400 Request validation failed
domains.empty 400 Domains array is empty
domains.exceeds_max 400 Domains array exceeds 100
domain.invalid 400 Domain format is invalid
domain.tld_unknown 400 Domain has unknown TLD
domain.tld_disabled 400 Domain has disabled TLD
domain.currency.unsupported 422 Currency is valid ISO 4217 but not supported by the platform
domain.check.rate_limited 429 Per-tier rate limit exceeded — Retry-After header carries the wait
domain.check.stream_error 500 Streaming not supported

Body·

required
application/json

Domain check request with FQDNs

Request body for checking availability of specific domain names

  • domains
    Type: array of string 1…100
    required

    Domains is an array of full domain names (FQDNs) to check. Each domain must include a TLD that is configured and enabled. Minimum 1, maximum 100 domains.

  • currency
    Type: string

    Currency optionally selects the ISO 4217 currency the priced results are returned in. When omitted, the currency is resolved from the caller's active org (billing currency) or the platform default for visitors. A valid code outside the platform's supported set is rejected with 422.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/domains/check
curl https://api.nametrust.com/domains/check \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "domains": [
    "example.com",
    "test.net"
  ],
  "currency": "EUR"
}'

{
  "object": "domain_check",
  "max_period": 10,
  "reason": "already_registered",
  "inventory": {
    "object": "domain_check_inventory",
    "id": "dom_01h455vb4pex5vsknk084sn02q",
    "kind": "managed",
    "status": "active",
    "expires_at": "2027-03-12T00:00:00Z"
  },
  "checked_at": "2024-01-20T15:30:00Z",
  "domain": "example.com",
  "label": "example",
  "tld": "com",
  "available": true,
  "premium": false,
  "price": {
    "object": "domain_price",
    "original_transfer_amount": 1499,
    "promo": false,
    "class": "standard",
    "currency": "USD",
    "register_amount": 1299,
    "renew_amount": 1299,
    "transfer_amount": 1299,
    "icann_fee_amount": 18,
    "original_register_amount": 1499,
    "original_renew_amount": 1499
  },
  "period_unit": "y",
  "min_period": 1
}

SSE stream of check results