Check domain availability

Check availability for a specific list of domains with a selected provider. The response includes each domain's availability status and price. Use this endpoint when you already have exact domain names to verify before placing an order.

Use the search domain availability endpoint when you have domain keywords and want provider-generated domain proposals.

Request

Endpoint

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

Headers

x-api-key: {YOUR_API_KEY}
Content-Type: application/json

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

Parameters

Check currently available providers with the providers endpoint before sending requests. Provider availability can change, and that endpoint is the source of truth.

Parameter	Required	Type	Description
provider	Yes	string	Provider that handles the check, for example MAILDOSO, MAILFORGE, GOOGLE, or MICROSOFT

Body

{
  "domains": [
    "piedpiper.com",
    "piedpiper.io"
  ]
}

Body schema

Field	Type	Required	Description
domains	array[string]	Yes	Domain names to check

Request samples

Check domains

cURL

curl --request POST \
  --url "https://api.woodpecker.co/rest/v2/domains/availability?provider=MAILDOSO" \
  --header "x-api-key: {YOUR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "domains": [
      "piedpiper.com",
      "piedpiper.io"
    ]
  }'

Python

import requests

def check_domain_availability():
  url = "https://api.woodpecker.co/rest/v2/domains/availability"
  headers = {
    "x-api-key": "{YOUR_API_KEY}",
    "Content-Type": "application/json"
  }
  params = {"provider": "MAILDOSO"}
  payload = {"domains": ["piedpiper.com", "piedpiper.io"]}

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

if __name__ == "__main__":
  try:
    data = check_domain_availability()
    print("POST 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?provider=MAILDOSO";
      String jsonData = """
        {
          "domains": [
            "piedpiper.com",
            "piedpiper.io"
          ]
        }
        """;

      HttpClient client = HttpClient.newHttpClient();
      HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(url))
        .header("x-api-key", "{YOUR_API_KEY}")
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(jsonData))
        .build();

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

Node.js

const axios = require('axios');

async function checkDomainAvailability() {
  const url = 'https://api.woodpecker.co/rest/v2/domains/availability';
  const headers = {
    'x-api-key': '{YOUR_API_KEY}',
    'Content-Type': 'application/json',
  };
  const params = { provider: 'MAILDOSO' };
  const data = { domains: ['piedpiper.com', 'piedpiper.io'] };

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

checkDomainAvailability();

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'),
    'Content-Type' => 'application/json',
  ],
]);

try {
  $response = $client->post('domains/availability', [
    'query' => ['provider' => 'MAILDOSO'],
    'json' => ['domains' => ['piedpiper.com', 'piedpiper.io']],
  ]);
  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. Unavailable domains return price: null. Returns an empty array if there are no results.

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

Body schema

Field	Type	Description
provider	string	Provider used for the availability check
domains	array	Domain availability 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

400

Invalid request or malformed request syntax

{
  "title": "Bad Request",
  "status": 400,
  "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

401

Authentication failed. Please review the authentication guide

{
  "title": "Unauthorized",
  "status": 401,
  "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

422

Returned when the request body is valid JSON but contains invalid or missing fields.

{
  "type": "validation_error",
  "message": "Invalid field(s)",
  "code": "invalid_fields",
  "request_id": "1b752aaa-b067-4145-8e22-939582dfeb2c",
  "fields": [
    {
      "field": "domains",
      "issue": "required",
      "value": null
    }
  ]
}

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