Search domain availability

Search for available domain suggestions by phrase. The response includes available domain proposals and their prices. Use this endpoint when you want provider-generated suggestions before placing a domain order.

Use the check domain availability endpoint when you already have a list of domains you want to purchase.

Request

Endpoint

GET https://api.woodpecker.co/rest/v2/domains/availability

Headers

x-api-key: {YOUR_API_KEY}

For details on how to authenticate your requests, please see the authentication guide.

Parameters

Parameter	Required	Type	Description
query	Yes	string	Phrase to search for, for example piedpiper.
provider	Yes	string	Provider that handles the search, for example MAILDOSO, GOOGLE, or MICROSOFT.

Request samples

Search by phrase

cURL

curl --request GET \
  --url "https://api.woodpecker.co/rest/v2/domains/availability?query=piedpiper&provider=MAILDOSO" \
  --header "x-api-key: {YOUR_API_KEY}"

Python

import requests

def search_domain_availability():
  url = "https://api.woodpecker.co/rest/v2/domains/availability"
  headers = {
    "x-api-key": "{YOUR_API_KEY}"
  }
  params = {"query": "piedpiper", "provider": "MAILDOSO"}

  response = requests.get(url, headers=headers, params=params)
  if response.status_code == 200:
    return response.json()
  else:
    raise Exception(f"GET request failed: {response.status_code}, {response.text}")

if __name__ == "__main__":
  try:
    data = search_domain_availability()
    print("GET response:", data)
  except Exception as e:
    print("Error:", e)

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class WoodpeckerApiClient {
  public static void main(String[] args) {
    try {
      String url = "https://api.woodpecker.co/rest/v2/domains/availability?query=piedpiper&provider=MAILDOSO";

      HttpClient client = HttpClient.newHttpClient();
      HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(url))
        .header("x-api-key", "{YOUR_API_KEY}")
        .GET()
        .build();

      HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
      if (response.statusCode() == 200) {
        System.out.println("GET response: " + response.body());
      } else {
        throw new Exception("GET request failed: " + response.statusCode() + ", " + response.body());
      }
    } catch (Exception e) {
      System.out.println("Error: " + e.getMessage());
    }
  }
}

Node.js

const axios = require('axios');

async function searchDomainAvailability() {
  const url = 'https://api.woodpecker.co/rest/v2/domains/availability';
  const headers = {
    'x-api-key': '{YOUR_API_KEY}'
  };
  const params = { query: 'piedpiper', provider: 'MAILDOSO' };

  try {
    const response = await axios.get(url, { headers, params });
    console.log('GET response:', response.data);
  } catch (error) {
    console.error('GET request failed:', error.response ? error.response.status : error.message);
  }
}

searchDomainAvailability();

PHP

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$client = new Client([
  'base_uri' => 'https://api.woodpecker.co/rest/v2/',
  'headers'  => [
    'x-api-key' => getenv('WOODPECKER_API_KEY'),
  ],
]);

try {
  $response = $client->get('domains/availability', [
    'query' => ['query' => 'piedpiper', 'provider' => 'MAILDOSO'],
  ]);
  echo $response->getStatusCode(), "\n";
  echo $response->getBody(), "\n";
} catch (RequestException $e) {
  echo "Error: ", $e->getMessage(), "\n";
  if ($e->hasResponse()) {
    echo $e->getResponse()->getBody(), "\n";
  }
}

Response

Response examples

200

Request processed successfully. Returns available domain suggestions with pricing for the selected provider. Returns an empty array if there are no results.

{
  "provider": "MAILDOSO",
  "query": "piedpiper",
  "domains": [
    {
      "domain": "piedpiper.com",
      "available": true,
      "price": {
        "amount": "13.00",
        "currency": "USD"
      }
    }
  ]
}

Body schema

Field	Type	Description
provider	string	Provider used for the availability search
query	string	Search phrase from the request
domains	array	Domain availability results. Empty array if there are no results
└─ domain	string	Domain name
└─ available	boolean	Whether the domain is available
└─ price	object or null	Domain price when available
└─ price.amount	string	Price amount
└─ price.currency	string	Price currency

401

Authentication failed. Please review the authentication guide

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "error details",
  "timestamp": "2026-05-06T12:00:00Z"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
detail	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred

422

Returned when the request has invalid or missing parameters.

{
  "type": "validation_error",
  "message": "Invalid field(s)",
  "code": "invalid_fields",
  "request_id": "1b752aaa-b067-4145-8e22-939582dfeb2c",
  "fields": [
    {
      "field": "provider",
      "issue": "Valid values are MAILDOSO, MAILFORGE, GOOGLE, MICROSOFT",
      "value": "INVALID"
    }
  ]
}

Body schema

Field	Type	Description
type	string	Error type
message	string	Error message
code	string	Error code
request_id	string or null	Request identifier when available
fields	array	Fields that failed validation
└─ field	string	Field with a validation issue
└─ issue	string	Detailed description of the validation issue
└─ value	string/null	Rejected value, or null for a missing required field

500

Unexpected server error

{
  "title": "Internal Server Error",
  "status": 500,
  "details": "error details",
  "timestamp": "2026-05-06T12:00:00Z"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
details	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred

503

Service unavailable or communication error

{
  "title": "Service Unavailable",
  "status": 503,
  "details": "error details",
  "timestamp": "2026-05-06T12:00:00Z"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
details	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred