Get domain details

Retrieve details for a single purchased domain, including owner data, forwarding settings, readiness status, and mailbox summary. To retrieve all purchased domains that belong to your account, use the list domains endpoint.

Request

Endpoint

GET https://api.woodpecker.co/rest/v2/domains/{domain_name}

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
domain_name	Yes	string	Full domain name

Request samples

Get a domain

cURL

curl --request GET \
  --url "https://api.woodpecker.co/rest/v2/domains/piedpiper.com" \
  --header "x-api-key: {YOUR_API_KEY}"

Python

import requests

def get_domain(domain_name):
  url = f"https://api.woodpecker.co/rest/v2/domains/{domain_name}"
  headers = {
    "x-api-key": "{YOUR_API_KEY}"
  }

  response = requests.get(url, headers=headers)
  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 = get_domain("piedpiper.com")
    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 domainName = "piedpiper.com";
      String url = "https://api.woodpecker.co/rest/v2/domains/" + domainName;

      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 getDomain(domainName) {
  const url = `https://api.woodpecker.co/rest/v2/domains/${domainName}`;
  const headers = {
    'x-api-key': '{YOUR_API_KEY}'
  };

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

getDomain('piedpiper.com');

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 {
  $domainName = 'piedpiper.com';
  $response = $client->get("domains/{$domainName}");
  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

{
  "owner": {
    "email": "owner@piedpiper.com",
    "first_name": "Richard",
    "last_name": "Hendricks",
    "company_name": "Pied Piper",
    "address": "5230 Newell Road",
    "city": "Palo Alto",
    "state": "CA",
    "country": "US",
    "zip_code": "94303",
    "phone": "+1 650 555 0100"
  },
  "email_forward_address": "forward@piedpiper.com",
  "domain_redirect_url": "https://piedpiper.com",
  "expires": "2027-06-24T10:00:00",
  "created": "2026-06-24T10:00:00",
  "is_custom_domain": true,
  "is_ready": true,
  "provider": "GOOGLE",
  "mailboxes_count": 2,
  "max_mailboxes": 10,
  "all_mailboxes_are_ready": false
}

Body schema

Field	Type	Description
owner	object	Domain owner details
└─ email	string	Owner email address
└─ first_name	string	Owner first name
└─ last_name	string	Owner last name
└─ company_name	string or null	Owner company name
└─ address	string	Owner street address
└─ city	string	Owner city
└─ state	string	Owner state or region
└─ country	string	Owner country code
└─ zip_code	string	Owner postal code
└─ phone	string	Owner phone number
email_forward_address	string or null	Domain forwarding email address
domain_redirect_url	string or null	Domain redirect URL
expires	string	Domain expiration timestamp
created	string	Domain creation timestamp
is_custom_domain	boolean	Whether the domain is marked as custom
is_ready	boolean	Whether the domain is ready to use
provider	string	Public provider name
mailboxes_count	integer	Number of non-deleted mailboxes on the domain
max_mailboxes	integer	Maximum number of mailboxes allowed on the domain
all_mailboxes_are_ready	boolean	Whether every non-deleted mailbox on the domain is ready

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

404

The domain was not found, belongs to another account, or is deleted. The response body is empty

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": "dc4faa0f-78bf-54e9-9d5d-ce9538f2eec5",
  "fields": [
    {
      "field": "domain_name",
      "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. Possible fields include domain_name
└─ 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