Domain Availability API

https://domain-availability.whoisxmlapi.com/api/documentation/
Admin
The Domain Availability API allows users to check the registration status of domain names to...
Tokens:5,157
Snippets:25
Trust Score:9.9
Update:8 months ago
Show doc for...
Tokens:
Raw
### WHOIS API POST Request Example

Source: https://domain-availability.whoisxmlapi.com/api/documentation/oauth

This example demonstrates how to make a POST request to the WHOIS API using cURL to check the availability of a domain name. It includes setting the content type, authorization header with an access token, and the request body containing the domain name.

```APIDOC
## POST /whoisserver/WhoisService

### Description
This endpoint allows you to check the availability and retrieve WHOIS information for a specified domain name using a POST request.

### Method
POST

### Endpoint
`https://www.whoisxmlapi.com/whoisserver/WhoisService`

### Parameters
#### Query Parameters
None

#### Request Body
- **domainName** (string) - Required - The domain name for which to retrieve WHOIS information.

### Request Example
```json
{
    "domainName": "google.com"
}
```

### Response
#### Success Response (200)
- **domainInfo** (object) - Contains detailed information about the domain.
- **createdDate** (string) - The date the domain was created.
- **updatedDate** (string) - The date the domain was last updated.
- **expiresDate** (string) - The date the domain expires.
- **registrant** (object) - Information about the domain registrant.
- **nameServers** (array) - A list of name servers for the domain.

#### Response Example
```json
{
  "domainName": "google.com",
  "domainNameAscii": "google.com",
  "createdDate": "1997-09-15T04:00:00.0Z",
  "updatedDate": "2021-09-14T00:00:00.0Z",
  "expiresDate": "2028-09-13T04:00:00.0Z",
  "registrant": {
    "organization": "Google LLC",
    "state": "California",
    "country": "US"
  },
  "nameServers": {
    "hostNames": [
      "ns1.google.com",
      "ns2.google.com",
      "ns3.google.com",
      "ns4.google.com"
    ]
  }
}
```
```

--------------------------------

### WHOIS API GET Request with Access Token using cURL

Source: https://domain-availability.whoisxmlapi.com/api/documentation/oauth

This example shows how to make a WHOIS API GET request using an access token for authentication. The access token, obtained previously, is passed in the Authorization header with the Bearer scheme. This replaces the need for a traditional API key parameter.

```bash
curl --location 'https://www.whoisxmlapi.com/whoisserver/WhoisService?domainName=google.com' \
--header 'Authorization: Bearer %accessToken%'
```

--------------------------------

### WHOIS API GET Request with Access Token

Source: https://domain-availability.whoisxmlapi.com/api/documentation/oauth

Example of how to make a WHOIS API GET request using an access token obtained via Server-to-Server OAuth for authentication.

```APIDOC
## GET /whoisserver/WhoisService

### Description
Example cURL request to the WHOIS API using an access token for authentication. The `Authorization` header should contain the obtained `accessToken`.

### Method
GET

### Endpoint
`https://www.whoisxmlapi.com/whoisserver/WhoisService?domainName=google.com`

### Parameters
#### Query Parameters
- **domainName** (string) - Required - The domain name to query.

#### Headers
- **Authorization** (string) - Required - The access token obtained from the OAuth token endpoint. Authentication scheme: Bearer.

### Request Example
```bash
curl --location 'https://www.whoisxmlapi.com/whoisserver/WhoisService?domainName=google.com' \
--header 'Authorization: Bearer %accessToken%'
```
```

--------------------------------

### Account Balance Information

Source: https://domain-availability.whoisxmlapi.com/api/documentation/account-balance-information

Retrieve your account balance information using either a GET or POST request to the specified endpoint. Ensure you include your API key for authentication.

```APIDOC
## GET /user-service/account-balance

### Description
Retrieves the account balance information for the authenticated user.

### Method
GET

### Endpoint
`https://user.whoisxmlapi.com/user-service/account-balance`

### Parameters
#### Query Parameters
- **apiKey** (string) - Required - Your personal API key.
- **productId** (string) - Optional - The ID of the product to check balance for.
- **outputFormat** (string) - Optional - The desired output format. Acceptable values: JSON, XML. Defaults to JSON.

### Request Example
`GET https://user.whoisxmlapi.com/user-service/account-balance?apiKey=API_KEY`

### Response
#### Success Response (200)
- **balance** (number) - The current account balance.
- **currency** (string) - The currency of the balance.

#### Response Example
```json
{
  "balance": 150.75,
  "currency": "USD"
}
```

## POST /user-service/account-balance

### Description
Retrieves the account balance information for the authenticated user using a POST request.

### Method
POST

### Endpoint
`https://user.whoisxmlapi.com/user-service/account-balance`

### Parameters
#### Request Body
- **apiKey** (string) - Required - Your personal API key.
- **productId** (string) - Optional - The ID of the product to check balance for.
- **outputFormat** (string) - Optional - The desired output format. Acceptable values: JSON, XML. Defaults to JSON.

### Request Example
```json
{
  "apiKey": "API_KEY",
  "productId": "WHOIS_API"
}
```

### Response
#### Success Response (200)
- **balance** (number) - The current account balance.
- **currency** (string) - The currency of the balance.

#### Response Example
```json
{
  "balance": 150.75,
  "currency": "USD"
}
```
```

--------------------------------

### Get Account Balance Information via API

Source: https://domain-availability.whoisxmlapi.com/api/documentation/account-balance-information

Retrieve your account balance using the WhoisXML API. This can be done via GET or POST requests to the specified endpoints. The apiKey is required, while productId and outputFormat are optional.

```HTTP
GET https://user.whoisxmlapi.com/user-service/account-balance?apiKey=API_KEY
```

```HTTP
POST https://user.whoisxmlapi.com/user-service/account-balance
```

--------------------------------

### Generate New API Key - WhoisXML API

Source: https://domain-availability.whoisxmlapi.com/api/documentation/generate-new-api-key

This section describes how to generate a new API key using the WhoisXML API. It specifies the GET endpoint, required parameters like 'currentApiKey', and optional parameters such as 'outputFormat'. The response includes the generated 'apiKey'.

```HTTP
GET https://user.whoisxmlapi.com/user-service/api-key/generate?currentApiKey=API_KEY
```

```JSON
{
   "apiKey": "at_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
```

```XML
<xml>
    <apiKey>at_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx</apiKey>
</xml>
```

--------------------------------

### Domain Availability API Output Formats (JSON and XML)

Source: https://domain-availability.whoisxmlapi.com/api/documentation/output-format

Demonstrates the output formats for the Domain Availability API. It shows how domain availability and name are represented in both JSON and XML, allowing developers to choose the most suitable format for their applications.

```json
{
   "DomainInfo": {
      "domainAvailability": "UNAVAILABLE",
      "domainName": "google.com"
   }
}
```

```xml
<xml>
  <DomainInfo>
    <domainAvailability>UNAVAILABLE</domainAvailability>
    <domainName>google.com</domainName>
  </DomainInfo>
</xml>
```

--------------------------------

### Domain Availability Lookup

Source: https://domain-availability.whoisxmlapi.com/api/documentation/making-requests

This endpoint allows you to check if a domain name is available for registration. You can specify the output format and the mode of checking (DNS only or DNS and WHOIS).

```APIDOC
## GET /api/v1

### Description
Checks whether a domain name is available for registration quickly and accurately.

### Method
GET

### Endpoint
`https://domain-availability.whoisxmlapi.com/api/v1`

### Parameters
#### Query Parameters
- **apiKey** (string) - Required - Your personal API key obtained from the My products page.
- **domainName** (string) - Required - The target domain name to check (e.g., google.com).
- **mode** (string) - Optional - Specifies the checking mode. Accepts `DNS_AND_WHOIS` (slower, more accurate) or `DNS_ONLY` (faster, default). Default: `DNS_ONLY`.
- **credits** (string) - Optional - Specifies which credits to use. Accepts `DA` (Domain Availability API credits) or `WHOIS` (WHOIS API credits). Default: `WHOIS`.
- **rdap** (integer) - Optional - Specifies the protocol for domain existence check. `0` for Auto protocol (default), `1` for RDAP protocol, `2` for WHOIS protocol. Note: RDAP is not supported for all TLDs and is only available for domains.
- **outputFormat** (string) - Optional - Specifies the response output format. Accepts `JSON` (default) or `XML`.

### Request Example
```json
{
  "example": "GET https://domain-availability.whoisxmlapi.com/api/v1?apiKey=YOUR_API_KEY&domainName=example.com&mode=DNS_AND_WHOIS&outputFormat=JSON"
}
```

### Response
#### Success Response (200)
- **domainName** (string) - The requested domain name.
- **isAvailable** (boolean) - Indicates if the domain is available for registration.
- **status** (string) - The status of the domain availability check.

#### Response Example
```json
{
  "domainName": "example.com",
  "isAvailable": true,
  "status": "available"
}
```
```

--------------------------------

### Error Codes

Source: https://domain-availability.whoisxmlapi.com/api/documentation/error-codes

This section details the various error codes returned by the Domain Availability API, along with their meanings and potential causes.

```APIDOC
## Error Codes

### Description
This section details the various error codes returned by the Domain Availability API, along with their meanings and potential causes.

### Error Codes List

- **400 Bad Request**
  - **Description**: Some required fields are missing from the request's body or have invalid values.

- **401 Unauthorized**
  - **Description**: The required _'apiKey'_ field value is missing or invalid.

- **403 Forbidden**
  - **Description**: Access restricted. Check credits balance or enter the correct API key.

- **408 Request Timeout**
  - **Description**: The request has timed out. Try your call again later. This error may also appear if the API cannot connect to the target domain name or IP address to retrieve data.

- **410 Gone**
  - **Description**: The requested API version is no longer available. Update to the latest version of the API.

- **422 Unprocessable Entity**
  - **Description**: Input correct request parameters or search term.

- **429 Too Many Requests**
  - **Description**: Too Many Requests. Try your call again later.

- **5XX**
  - **Description**: Internal server error, please contact our support team.
```

--------------------------------

### Generate New API Key

Source: https://domain-availability.whoisxmlapi.com/api/documentation/generate-new-api-key

This endpoint allows users to generate a new API key for accessing WhoisXML API services. It requires the current API key for authentication and supports optional output format specification.

```APIDOC
## GET /user-service/api-key/generate

### Description
Generates a new API key for the user. Remember to re-login to the website to reflect the newly generated API key.

### Method
GET

### Endpoint
`https://user.whoisxmlapi.com/user-service/api-key/generate`

### Parameters
#### Query Parameters
- **currentApiKey** (string) - Required - Your personal API key obtained from the My products page.
- **outputFormat** (string) - Optional - Specifies the response output format. Acceptable values: `JSON`, `XML`. Defaults to `JSON`.

### Request Example
```
GET https://user.whoisxmlapi.com/user-service/api-key/generate?currentApiKey=YOUR_API_KEY&outputFormat=JSON
```

### Response
#### Success Response (200)
- **apiKey** (string) - The newly generated API key.

#### Response Example
```json
{
   "apiKey": "at_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
```
```xml
<apiKey>at_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx</apiKey>
```

### Error Codes
- **400 Bad Request**: The API key entered does not exist or is no longer active.
- **422 Unprocessable Entity**: Input correct request parameters.
```

--------------------------------

### Generate Access Token

Source: https://domain-availability.whoisxmlapi.com/api/documentation/oauth

Use the `accessToken` grant type to generate an access token for authenticating API requests. The token has a configurable lifetime and is used in place of a standard API key.

```APIDOC
## POST /oauth/token

### Description
Generates a server-to-server OAuth access token for authenticating with WhoisXML APIs. The access token replaces the standard `apiKey` parameter for API requests.

### Method
POST

### Endpoint
`https://main.whoisxmlapi.com/oauth/token`

### Parameters
#### Headers
- **Authorization** (string) - Required - Base64 encoded API key. Authentication scheme: Bearer.

#### Request Body
- **grantType** (string) - Required - The grant type to generate an access token. Acceptable values: `access_token`.
- **expiresIn** (integer) - Optional - The lifetime of the access token in seconds. Acceptable values: `1800`, `3600`, `7200`, `10800`. Default: `3600`.
- **outputFormat** (string) - Optional - Response output format. Acceptable values: `JSON`, `XML`. Default: `JSON`.

### Request Example
```json
{
    "grantType": "access_token",
    "expiresIn": 7200
}
```

### Response
#### Success Response (200)
- **accessToken** (string) - The generated access token.
- **expiresIn** (integer) - The lifetime of the access token in seconds.

#### Response Example
```json
{
    "accessToken": "G2OIE2AKRCVDYFUJCV5PXXXXXXXXXXXX",
    "expiresIn": 3600
}
```

### Errors
#### Unauthorized (401)
```json
{
    "code": 401,
    "messages": "Access restricted. Check the credits balance or enter the correct API key."
}
```

#### Unprocessable Entity (422)
```json
{
    "code": 422,
    "messages": {
        "grantType": [
            "The selected grant type is invalid."
        ]
    }
}
```
```

--------------------------------

### Domain Availability API

Source: https://domain-availability.whoisxmlapi.com/api/documentation/output-format

This API endpoint checks the registration state of a domain name. It supports both JSON and XML output formats.

```APIDOC
## GET /api/domain-availability

### Description
Checks the registration state (AVAILABLE/UNAVAILABLE) of a given domain name.

### Method
GET

### Endpoint
/api/domain-availability

### Query Parameters
- **domainName** (string) - Required - The domain name to check.
- **outputFormat** (string) - Optional - Specifies the output format, either 'JSON' or 'XML'. Defaults to JSON.

### Request Example
```
GET /api/domain-availability?domainName=example.com&outputFormat=JSON
```

### Response
#### Success Response (200)
- **domainAvailability** (string) - The registration state of the domain name (AVAILABLE or UNAVAILABLE).
- **domainName** (string) - The requested domain name.

#### Response Example (JSON)
```json
{
   "DomainInfo": {
      "domainAvailability": "UNAVAILABLE",
      "domainName": "google.com"
   }
}
```

#### Response Example (XML)
```xml
<DomainInfo>
  <domainAvailability>UNAVAILABLE</domainAvailability>
  <domainName>google.com</domainName>
</DomainInfo>
```

### Error Codes
- **400 Bad Request**: Invalid or missing parameters.
- **401 Unauthorized**: Invalid API key.
- **404 Not Found**: Endpoint not found.
- **500 Internal Server Error**: Server-side error.
```

--------------------------------

### Generate Access Token using cURL

Source: https://domain-availability.whoisxmlapi.com/api/documentation/oauth

This snippet demonstrates how to generate an access token for WhoisXML API using cURL. It requires a Base64 encoded API key in the Authorization header and specifies the grant type and optional expiration time. The response includes the access token and its expiration.

```bash
curl --location 'https://main.whoisxmlapi.com/oauth/token' \
--header 'Authorization: Bearer %base64_encoded_API_key%' \
--header 'Content-Type: application/json' \
--data '{
    "grantType": "access_token",
    "expiresIn": 7200
}'
```

--------------------------------

### cURL WHOIS API POST Request with Access Token

Source: https://domain-availability.whoisxmlapi.com/api/documentation/oauth

This snippet shows how to send a POST request to the WHOIS API using cURL. It includes setting the content type to JSON, providing an authorization token, and sending the domain name in the request body. Ensure you replace '%accessToken%' with your actual API key.

```shell
curl --location 'https://www.whoisxmlapi.com/whoisserver/WhoisService' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer %accessToken%' \
    --data '{
        "domainName": "google.com"
    }'
```
Tokens:
Raw