1. Home
2. Reference documentation
3. Fastly API
4. Domain Management

Methods

The Domain Research API has two methods:

• Suggest, for retrieving domain search results
• Status, for checking domain availability, with two variants:
  • Precise: for domain registry-level availability (e.g. for new registrations)
  • Estimated: for DNS & aftermarket-level availability (which is not registry-level)

Request parameters must be URL-encoded UTF-8 strings in the query string.

API responses are in JSON (application/json). On success or failure, the server will respond with an appropriate HTTP response code (2XX, 4XX, 5XX).

Suggest method

Suggest usage and examples

The Suggest method performs a real-time query of the search terms against the known zone database, making recommendations, stemming, and applying Unicode folding, IDN normalization, registrar supported-zone restrictions, and other refinements.

The server responds with a JSON object containing search result(s), or an error.

Status method

Status usage and examples

The Status method checks the availability status of a single domain name. It accepts one argument: domain

The response will contain an object with keys: domain, offers, scope, status, tags, and zone.

The status value is a space-delimited list of status types for the given domain, in increasing order of precedence.

To prevent resource exhaustion, our platform limits API requests to a total runtime of 30 seconds. If an upstream provider fails to respond within this limit, requests to the status method will return a best-effort value, typically unknown or undelegated.

The Status method contains two variants: Precise and Estimated, with Precise being the default. However, some use-cases don’t require full, domain registry-level "precise" availability checks, but rather only need information from the DNS or domain aftermarkets. An "estimated" status check will return this information, at a less-expensive per-request cost than a "precise" check.

Precise use case: aftermarket availability

If an offers key is present in the status response, it will contain an array of "offers" from domain aftermarket vendors like Afternic from GoDaddy, Atom, and Sedo. This data is provided by these aftermarket services, and is not guaranteed to be 100% accurate. It may contain currency, price, and vendor values, if these values are present in the data we receive from these aftermarket services.

Estimate use case: Availability for registration

The most common use-case of the Status method is to determine if a domain is immediately registrable via registrars or resellers (e.g. not via an aftermarket purchase and transfer).

For this use-case, the inactive status means a domain is available for registration.

If you see the unknown status, this means the Domain Research service was unable to determine an authoritative status from its upstream sources. This is commonly due to a domain registry backend operator being offline due to scheduled maintenance. The third-party OpenSRS service maintains an up-to-date log of scheduled registry maintenance.

Status response values

status values are returned in a space-delimited list, in increasing order of priority.

The right-most value can be considered the most important value. E.g. the status for acmecoffee.shop is undelegated inactive.

• undelegated means this domain isn't present in the DNS
• inactive means it’s available for registration

These are the status values that the method can return. Note that items marked with an asterisk (*) are only returned with Precise checks.

Data objects

Offer object

An offer from a domain aftermarket vendor.

Domain status object

All attributes for a domain status.

Domain suggestion object

All attributes for a suggested domain.

Endpoints