API reference

WHOIS

WHOIS: Look up domain registration; List TLD coverage. Published endpoints, request parameters, JSON responses and authentication.

Release 1.0.0 · This reference describes the release shown here. Console shows the current published configuration.

Read the quickstart ↗Authentication ↗Explore API ↗

Technical limits

ⓘ

Timeout: 3 s
Request body: 1 MiB
Response body: 1 MiB

Look up domain registration

GET/whois/v1/domains/{domain}

Retrieve authoritative registration data for a normalized domain. Registered and conclusively unregistered domains both return a successful response. Optional registry fields may be omitted. Inspect quality.warnings for missing or redacted data.

1 Credit per successfully queried domainHow billing works ↗

Parameters

Parameter	Location	Type	Required	Description
`domain`	path	`string`	Yes	Domain name in Unicode or Punycode; no URL scheme or path

Success response200

JSON model

{
  "code": 0,
  "data": {
    "domain": {
      "input": "example.com",
      "queried": "example.com",
      "unicode": "example.com"
    },
    "quality": {
      "completeness": "partial",
      "support_level": "standard",
      "warnings": [
        "CONTACT_REDACTED"
      ]
    },
    "record": {
      "contacts": [
        {
          "address": {
            "country": "US",
            "locality": "Example City",
            "postal_code": "12345",
            "region": "Example Region",
            "street": [
              "123 Example Street"
            ]
          },
          "emails": [
            "[email protected]"
          ],
          "handle": "contact-example",
          "name": "Example Contact",
          "organization": "Example Organization",
          "phones": [
            "+1.2025550100"
          ],
          "roles": [
            "registrant"
          ]
        }
      ],
      "dates": {
        "expires_at": "2027-01-01T00:00:00Z",
        "registered_at": "2020-01-01T00:00:00Z",
        "updated_at": "2026-10-20T00:00:00Z"
      },
      "handle": "EXAMPLE-123",
      "nameservers": [
        {
          "ldh_name": "ns1.example.test",
          "unicode_name": "ns1.example.test"
        }
      ],
      "notices": [
        {
          "description": [
            "Example registry terms apply."
          ],
          "links": [
            "https://registry.example.test/terms"
          ],
          "title": "Terms of use"
        }
      ],
      "redactions": [
        {
          "field": "contacts.emails",
          "reason": "Contact details withheld by registry policy"
        }
      ],
      "registrar": {
        "handle": "registrar-example",
        "iana_id": "9999",
        "name": "Example Registrar"
      },
      "secure_dns": {
        "delegation_signed": true
      },
      "statuses": [
        "active"
      ]
    },
    "registration": {
      "registered": true
    },
    "source": {
      "cache_expires_at": "2026-10-21T08:00:00Z",
      "cache_hit": false,
      "fetched_at": "2026-10-20T08:00:00Z",
      "parser_version": "rdap-v1",
      "protocol": "rdap",
      "server": "https://rdap.example.test",
      "source_version": "2026-10-20"
    }
  },
  "error": ""
}

Illustrative JSON shape generated from the published schema. Field values are examples, not live results.

Fields inside data

Name	Type	Required	Description
`domain`	`object`	No	Input and normalized domain names.
`domain.input`	`string`	No	Original input domain.
`domain.queried`	`string`	No	Normalized registrable domain sent to the authoritative service.
`domain.unicode`	`string`	No	Unicode form of the queried domain.
`quality`	`object`	No	Record completeness and stable warning codes.
`quality.completeness`	`string`	No	Completeness of the publicly available registration record. Values: `["complete","partial","minimal"]`
`quality.support_level`	`string`	No	Support tier used for this successful lookup. Values: `["standard","verified"]`
`quality.warnings`	`string[]`	No	Stable warning codes for unavailable or redacted information.
`record`	`object`	No	Public registration details. Individual fields may be omitted.
`record.contacts`	`object[]`	No	Public contact records. Private or unavailable fields are omitted.
`record.contacts[].address`	`object`	No	Public postal address; omitted when unavailable.
`record.contacts[].address.country`	`string`	No	Published country code; omitted when unavailable.
`record.contacts[].address.locality`	`string`	No	City or locality; omitted when unavailable.
`record.contacts[].address.postal_code`	`string`	No	Postal code; omitted when unavailable.
`record.contacts[].address.region`	`string`	No	State or region; omitted when unavailable.
`record.contacts[].address.street`	`string[]`	No	Published street address lines.
`record.contacts[].emails`	`string[]`	No	Public email addresses. An empty array can indicate redaction.
`record.contacts[].handle`	`string`	No	Contact handle; omitted when unavailable.
`record.contacts[].name`	`string`	No	Public contact name; omitted when unavailable or redacted.
`record.contacts[].organization`	`string`	No	Public organization name; omitted when unavailable.
`record.contacts[].phones`	`string[]`	No	Public phone numbers. May be empty.
`record.contacts[].roles`	`string[]`	No	Roles assigned to this public contact.
`record.dates`	`object`	No	Published lifecycle dates; omitted when unavailable.
`record.dates.expires_at`	`string`	No	Expiration timestamp when published.
`record.dates.registered_at`	`string`	No	Registration timestamp when published.
`record.dates.updated_at`	`string`	No	Last update timestamp when published.
`record.handle`	`string`	No	Registry handle; omitted when not published.
`record.nameservers`	`object[]`	No	Published authoritative nameservers. May be empty.
`record.nameservers[].ldh_name`	`string`	No	ASCII nameserver hostname.
`record.nameservers[].unicode_name`	`string`	No	Unicode nameserver hostname; omitted when unavailable.
`record.notices`	`object[]`	No	Registry notices and remarks.
`record.notices[].description`	`string[]`	No	Notice text from the authoritative service.
`record.notices[].links`	`string[]`	No	Links accompanying the notice.
`record.notices[].title`	`string`	No	Published notice title.
`record.redactions`	`object[]`	No	Redaction notices provided by the authoritative service.
`record.redactions[].field`	`string`	No	Affected response field when identified.
`record.redactions[].reason`	`string`	No	Published reason for redacting registration data.
`record.registrar`	`object`	No	Registrar details; omitted when not published.
`record.registrar.handle`	`string`	No	Registrar handle; omitted when unavailable.
`record.registrar.iana_id`	`string`	No	IANA registrar identifier; omitted when unavailable.
`record.registrar.name`	`string`	No	Published registrar name.
`record.secure_dns`	`object`	No	DNSSEC information; omitted when not published.
`record.secure_dns.delegation_signed`	`boolean`	No	Whether the registry reports a signed DNS delegation.
`record.statuses`	`string[]`	No	Published domain statuses. An empty array means none were published.
`registration`	`object`	No	Authoritative registration conclusion.
`registration.registered`	`boolean`	No	Whether the authoritative service confirms the domain is registered.
`source`	`object`	No	Authoritative source and cache freshness.
`source.cache_expires_at`	`string`	No	UTC timestamp when this cached result expires.
`source.cache_hit`	`boolean`	No	Whether this response was served from cache.
`source.fetched_at`	`string`	No	UTC timestamp when the source was fetched.
`source.parser_version`	`string`	No	Normalization parser version.
`source.protocol`	`string`	No	Protocol used to retrieve registration data. Values: `["rdap","whois"]`
`source.server`	`string`	No	Public authoritative server used for the lookup.
`source.source_version`	`string`	No	Published source configuration version.

List TLD coverage

GET/whois/v1/tlds

Check supported TLDs, lookup protocols and current availability before requesting a lookup. This endpoint does not trigger an upstream lookup.

FreeHow billing works ↗

Parameters

This operation has no published parameters.

Success response200

JSON model

{
  "code": 0,
  "data": {
    "generated_at": "2026-10-20T08:00:00Z",
    "items": [
      {
        "availability": "available",
        "last_verified_at": "2026-10-20T08:00:00Z",
        "protocols": [
          "rdap"
        ],
        "support_level": "standard",
        "tld": "com",
        "unicode_tld": "com",
        "unsupported_reason": "No supported authoritative lookup service"
      }
    ],
    "source_version": "2026-10-20"
  },
  "error": ""
}

Illustrative JSON shape generated from the published schema. Field values are examples, not live results.

Fields inside data

Name	Type	Required	Description
`generated_at`	`string`	No	UTC timestamp of the loaded coverage snapshot.
`items`	`object[]`	No	Supported and unsupported TLD capabilities.
`items[].availability`	`string`	No	Current operational availability. Values: `["available","degraded","disabled"]`
`items[].last_verified_at`	`string \| null`	No	UTC timestamp of the latest verification; null before verification.
`items[].protocols`	`string[]`	No	Configured authoritative lookup protocols.
`items[].support_level`	`string`	No	Current supported lookup tier for this TLD. Values: `["standard","verified","unsupported"]`
`items[].tld`	`string`	No	ASCII top-level domain.
`items[].unicode_tld`	`string`	No	Unicode top-level domain.
`items[].unsupported_reason`	`string`	No	Reason this TLD is unsupported; omitted when supported.
`source_version`	`string`	No	Published source configuration version.

Create a batch lookup

POST/whois/v1/batches

Submit up to 10000 domain inputs. HTTP 202 means the job was accepted; it does not mean processing is complete. 1. Save data.job_id from this response. 2. Poll GET /whois/v1/batches/{job_id}; the create response supplies Retry-After: 3 seconds. 3. Read GET /whois/v1/batches/{job_id}/results. Continue with next_cursor while has_more is true. Use POST /whois/v1/batches/{job_id}:cancel to stop new work. Terminal job results are retained for 7 days.

1 Credit per successfully queried domainHow billing works ↗

HTTP 202 reserves Credits. Successful units are charged when the job settles; unused reserved Credits are released.

Parameters

This operation has no published parameters.

Request body

JSON model

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

Illustrative JSON shape generated from the published schema. Field values are examples, not live results.

Request fields

Name	Type	Required	Description
`domains`	`string[]`	Yes	From 1 to 10000 domain inputs. Repeated normalized domains share processing.

Success response202

JSON model

{
  "code": 0,
  "data": {
    "active_item_count": 0,
    "completed_item_count": 0,
    "expires_at": "2026-10-27T08:00:00Z",
    "failed_item_count": 0,
    "input_count": 2,
    "job_id": "job_0123456789abcdef0123456789abcdef",
    "processing_item_count": 2,
    "progress": 0,
    "results_url": "/whois/v1/batches/job_0123456789abcdef0123456789abcdef/results",
    "status": "queued",
    "success_item_count": 0,
    "unique_item_count": 2,
    "valid_input_count": 2
  },
  "error": ""
}

Illustrative JSON shape generated from the published schema. Field values are examples, not live results.

Fields inside data

Name	Type	Required	Description
`active_item_count`	`integer`	No	Number of items currently being executed.
`completed_item_count`	`integer`	No	Number of unique items that have reached a terminal state.
`expires_at`	`string`	No	UTC expiry timestamp; present after the job becomes terminal.
`failed_item_count`	`integer`	No	Number of items that failed.
`input_count`	`integer`	No	Number of submitted input entries.
`job_id`	`string`	No	Batch identifier used by status and result endpoints.
`processing_item_count`	`integer`	No	Unique items not yet completed; includes queued work.
`progress`	`integer`	No	Completed unique items as a percentage from 0 to 100.
`results_url`	`string`	No	Relative Gateway path for paginated batch results.
`status`	`string`	No	Current job lifecycle status.
`success_item_count`	`integer`	No	Number of items with a conclusive registration result.
`unique_item_count`	`integer`	No	Number of unique normalized domains to process.
`valid_input_count`	`integer`	No	Number of valid input entries before deduplication.

Get batch progress

GET/whois/v1/batches/{job_id}

Use job_id from the create response to inspect job progress. Stop polling after completion, cancellation, failure or expiry. Read results using data.results_url. Polling and reading results are free; only successful domain lookups are charged when the batch settles.

FreeHow billing works ↗

Parameters

Parameter	Location	Type	Required	Description
`job_id`	path	`string`	Yes	Batch job identifier

Success response200

JSON model

{
  "code": 0,
  "data": {
    "active_item_count": 0,
    "completed_item_count": 0,
    "expires_at": "2026-10-27T08:00:00Z",
    "failed_item_count": 0,
    "input_count": 2,
    "job_id": "job_0123456789abcdef0123456789abcdef",
    "processing_item_count": 2,
    "progress": 0,
    "results_url": "/whois/v1/batches/job_0123456789abcdef0123456789abcdef/results",
    "status": "queued",
    "success_item_count": 0,
    "unique_item_count": 2,
    "valid_input_count": 2
  },
  "error": ""
}

Illustrative JSON shape generated from the published schema. Field values are examples, not live results.

Fields inside data

Name	Type	Required	Description
`active_item_count`	`integer`	No	Number of items currently being executed.
`completed_item_count`	`integer`	No	Number of unique items that have reached a terminal state.
`expires_at`	`string`	No	UTC expiry timestamp; present after the job becomes terminal.
`failed_item_count`	`integer`	No	Number of items that failed.
`input_count`	`integer`	No	Number of submitted input entries.
`job_id`	`string`	No	Batch identifier used by status and result endpoints.
`processing_item_count`	`integer`	No	Unique items not yet completed; includes queued work.
`progress`	`integer`	No	Completed unique items as a percentage from 0 to 100.
`results_url`	`string`	No	Relative Gateway path for paginated batch results.
`status`	`string`	No	Current job lifecycle status.
`success_item_count`	`integer`	No	Number of items with a conclusive registration result.
`unique_item_count`	`integer`	No	Number of unique normalized domains to process.
`valid_input_count`	`integer`	No	Number of valid input entries before deduplication.

Read batch results

GET/whois/v1/batches/{job_id}/results

Read results in original input order. When has_more is true, send next_cursor unchanged as the cursor query parameter. A successful page request does not mean every item succeeded. Inspect each item status, state and error_code.

FreeHow billing works ↗

Parameters

Parameter	Location	Type	Required	Description
`job_id`	path	`string`	Yes	Batch job identifier
`cursor`	query	`string`	No	Opaque next_cursor from the previous result page
`limit`	query	`integer`	No	Page size from 1 to 500

Success response200

JSON model

{
  "code": 0,
  "data": {
    "has_more": false,
    "next_cursor": "<NEXT_CURSOR>",
    "results": [
      {
        "error_code": 0,
        "input_domain": "example.com",
        "normalized_domain": "example.com",
        "position": 0,
        "positions": [
          0
        ],
        "result": {
          "domain": {
            "input": "example.com",
            "queried": "example.com",
            "unicode": "example.com"
          },
          "quality": {
            "completeness": "partial",
            "support_level": "standard",
            "warnings": [
              "CONTACT_REDACTED"
            ]
          },
          "record": {
            "contacts": [
              {
                "address": {
                  "country": "US",
                  "locality": "Example City",
                  "postal_code": "12345",
                  "region": "Example Region",
                  "street": [
                    "123 Example Street"
                  ]
                },
                "emails": [
                  "[email protected]"
                ],
                "handle": "contact-example",
                "name": "Example Contact",
                "organization": "Example Organization",
                "phones": [
                  "+1.2025550100"
                ],
                "roles": [
                  "registrant"
                ]
              }
            ],
            "dates": {
              "expires_at": "2027-01-01T00:00:00Z",
              "registered_at": "2020-01-01T00:00:00Z",
              "updated_at": "2026-10-20T00:00:00Z"
            },
            "handle": "EXAMPLE-123",
            "nameservers": [
              {
                "ldh_name": "ns1.example.test",
                "unicode_name": "ns1.example.test"
              }
            ],
            "notices": [
              {
                "description": [
                  "Example registry terms apply."
                ],
                "links": [
                  "https://registry.example.test/terms"
                ],
                "title": "Terms of use"
              }
            ],
            "redactions": [
              {
                "field": "contacts.emails",
                "reason": "Contact details withheld by registry policy"
              }
            ],
            "registrar": {
              "handle": "registrar-example",
              "iana_id": "9999",
              "name": "Example Registrar"
            },
            "secure_dns": {
              "delegation_signed": true
            },
            "statuses": [
              "active"
            ]
          },
          "registration": {
            "registered": true
          },
          "source": {
            "cache_expires_at": "2026-10-21T08:00:00Z",
            "cache_hit": false,
            "fetched_at": "2026-10-20T08:00:00Z",
            "parser_version": "rdap-v1",
            "protocol": "rdap",
            "server": "https://rdap.example.test",
            "source_version": "2026-10-20"
          }
        },
        "state": "registered",
        "status": "succeeded"
      }
    ]
  },
  "error": ""
}

Illustrative JSON shape generated from the published schema. Field values are examples, not live results.

Fields inside data

Name	Type	Required	Description
`has_more`	`boolean`	No	Whether another page is available.
`next_cursor`	`string`	No	Opaque cursor for the next page; omitted on the last page.
`results`	`object[]`	No	Results for this page in original input order.
`results[].error_code`	`integer`	No	Item error code; omitted when no error occurred.
`results[].input_domain`	`string`	No	Original submitted domain.
`results[].normalized_domain`	`string`	No	Normalized registrable domain; omitted for invalid input.
`results[].position`	`integer`	No	Original input position.
`results[].positions`	`integer[]`	No	Original positions grouped under the same normalized domain.
`results[].result`	`object`	No	WHOIS result when available; omitted otherwise.
`results[].result.domain`	`object`	No	Input and normalized domain names.
`results[].result.domain.input`	`string`	No	Original input domain.
`results[].result.domain.queried`	`string`	No	Normalized registrable domain sent to the authoritative service.
`results[].result.domain.unicode`	`string`	No	Unicode form of the queried domain.
`results[].result.quality`	`object`	No	Record completeness and stable warning codes.
`results[].result.quality.completeness`	`string`	No	Completeness of the publicly available registration record. Values: `["complete","partial","minimal"]`
`results[].result.quality.support_level`	`string`	No	Support tier used for this successful lookup. Values: `["standard","verified"]`
`results[].result.quality.warnings`	`string[]`	No	Stable warning codes for unavailable or redacted information.
`results[].result.record`	`object`	No	Public registration details. Individual fields may be omitted.
`results[].result.record.contacts`	`object[]`	No	Public contact records. Private or unavailable fields are omitted.
`results[].result.record.contacts[].address`	`object`	No	Public postal address; omitted when unavailable.
`results[].result.record.contacts[].address.country`	`string`	No	Published country code; omitted when unavailable.
`results[].result.record.contacts[].address.locality`	`string`	No	City or locality; omitted when unavailable.
`results[].result.record.contacts[].address.postal_code`	`string`	No	Postal code; omitted when unavailable.
`results[].result.record.contacts[].address.region`	`string`	No	State or region; omitted when unavailable.
`results[].result.record.contacts[].address.street`	`string[]`	No	Published street address lines.
`results[].result.record.contacts[].emails`	`string[]`	No	Public email addresses. An empty array can indicate redaction.
`results[].result.record.contacts[].handle`	`string`	No	Contact handle; omitted when unavailable.
`results[].result.record.contacts[].name`	`string`	No	Public contact name; omitted when unavailable or redacted.
`results[].result.record.contacts[].organization`	`string`	No	Public organization name; omitted when unavailable.
`results[].result.record.contacts[].phones`	`string[]`	No	Public phone numbers. May be empty.
`results[].result.record.contacts[].roles`	`string[]`	No	Roles assigned to this public contact.
`results[].result.record.dates`	`object`	No	Published lifecycle dates; omitted when unavailable.
`results[].result.record.dates.expires_at`	`string`	No	Expiration timestamp when published.
`results[].result.record.dates.registered_at`	`string`	No	Registration timestamp when published.
`results[].result.record.dates.updated_at`	`string`	No	Last update timestamp when published.
`results[].result.record.handle`	`string`	No	Registry handle; omitted when not published.
`results[].result.record.nameservers`	`object[]`	No	Published authoritative nameservers. May be empty.
`results[].result.record.nameservers[].ldh_name`	`string`	No	ASCII nameserver hostname.
`results[].result.record.nameservers[].unicode_name`	`string`	No	Unicode nameserver hostname; omitted when unavailable.
`results[].result.record.notices`	`object[]`	No	Registry notices and remarks.
`results[].result.record.notices[].description`	`string[]`	No	Notice text from the authoritative service.
`results[].result.record.notices[].links`	`string[]`	No	Links accompanying the notice.
`results[].result.record.notices[].title`	`string`	No	Published notice title.
`results[].result.record.redactions`	`object[]`	No	Redaction notices provided by the authoritative service.
`results[].result.record.redactions[].field`	`string`	No	Affected response field when identified.
`results[].result.record.redactions[].reason`	`string`	No	Published reason for redacting registration data.
`results[].result.record.registrar`	`object`	No	Registrar details; omitted when not published.
`results[].result.record.registrar.handle`	`string`	No	Registrar handle; omitted when unavailable.
`results[].result.record.registrar.iana_id`	`string`	No	IANA registrar identifier; omitted when unavailable.
`results[].result.record.registrar.name`	`string`	No	Published registrar name.
`results[].result.record.secure_dns`	`object`	No	DNSSEC information; omitted when not published.
`results[].result.record.secure_dns.delegation_signed`	`boolean`	No	Whether the registry reports a signed DNS delegation.
`results[].result.record.statuses`	`string[]`	No	Published domain statuses. An empty array means none were published.
`results[].result.registration`	`object`	No	Authoritative registration conclusion.
`results[].result.registration.registered`	`boolean`	No	Whether the authoritative service confirms the domain is registered.
`results[].result.source`	`object`	No	Authoritative source and cache freshness.
`results[].result.source.cache_expires_at`	`string`	No	UTC timestamp when this cached result expires.
`results[].result.source.cache_hit`	`boolean`	No	Whether this response was served from cache.
`results[].result.source.fetched_at`	`string`	No	UTC timestamp when the source was fetched.
`results[].result.source.parser_version`	`string`	No	Normalization parser version.
`results[].result.source.protocol`	`string`	No	Protocol used to retrieve registration data. Values: `["rdap","whois"]`
`results[].result.source.server`	`string`	No	Public authoritative server used for the lookup.
`results[].result.source.source_version`	`string`	No	Published source configuration version.
`results[].state`	`string`	No	Registration outcome; unknown when no conclusive result exists.
`results[].status`	`string`	No	Execution status of this item.

Cancel a batch lookup

POST/whois/v1/batches/{job_id}:cancel

Stop scheduling new work for this job. Completed results remain available; in-flight work may finish. Repeated cancellation is safe.

FreeHow billing works ↗

Parameters

Parameter	Location	Type	Required	Description
`job_id`	path	`string`	Yes	Batch job identifier

Success response200

JSON model

{
  "code": 0,
  "data": {
    "active_item_count": 0,
    "completed_item_count": 0,
    "expires_at": "2026-10-27T08:00:00Z",
    "failed_item_count": 0,
    "input_count": 2,
    "job_id": "job_0123456789abcdef0123456789abcdef",
    "processing_item_count": 2,
    "progress": 0,
    "results_url": "/whois/v1/batches/job_0123456789abcdef0123456789abcdef/results",
    "status": "queued",
    "success_item_count": 0,
    "unique_item_count": 2,
    "valid_input_count": 2
  },
  "error": ""
}

Illustrative JSON shape generated from the published schema. Field values are examples, not live results.

Fields inside data

Name	Type	Required	Description
`active_item_count`	`integer`	No	Number of items currently being executed.
`completed_item_count`	`integer`	No	Number of unique items that have reached a terminal state.
`expires_at`	`string`	No	UTC expiry timestamp; present after the job becomes terminal.
`failed_item_count`	`integer`	No	Number of items that failed.
`input_count`	`integer`	No	Number of submitted input entries.
`job_id`	`string`	No	Batch identifier used by status and result endpoints.
`processing_item_count`	`integer`	No	Unique items not yet completed; includes queued work.
`progress`	`integer`	No	Completed unique items as a percentage from 0 to 100.
`results_url`	`string`	No	Relative Gateway path for paginated batch results.
`status`	`string`	No	Current job lifecycle status.
`success_item_count`	`integer`	No	Number of items with a conclusive registration result.
`unique_item_count`	`integer`	No	Number of unique normalized domains to process.
`valid_input_count`	`integer`	No	Number of valid input entries before deduplication.