Save domain owner

Create or update the domain owner details for the account. A domain owner is required before you can order domains to register them. This endpoint replaces the saved owner details, so the request body must include the complete domain owner object.

Request

Endpoint

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

Headers

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

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

Body

{
  "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": "+16505550100",
  "configuration": {
    "default_domain_redirect_url": "https://piedpiper.com",
    "default_email_forward_address": "forward@piedpiper.com"
  }
}

Body schema

Field	Type	Required	Description
`email`	string	Yes	Owner email address
`first_name`	string	Yes	Owner first name
`last_name`	string	Yes	Owner last name
`company_name`	string	No	Company name
`address`	string	Yes	Owner address
`city`	string	Yes	Owner city
`state`	string	Yes	Owner state or region
`country`	string	Yes	Owner country
`zip_code`	string	Yes	Postal code in the format valid for the selected country
`phone`	string	Yes	Phone number valid for the selected country
`configuration`	object	No	Default settings for ordered domains
└─ `default_domain_redirect_url`	string	No	Default domain redirect URL. If not empty, it must start with `http://` or `https://`
└─ `default_email_forward_address`	string	No	Default email forwarding address. If not empty, it must be a valid email address

Request samples

Save domain owner

cURL
Python
Java
Node.js
PHP

curl --request POST \
  --url "https://api.woodpecker.co/rest/v2/domains/owner" \
  --header "x-api-key: {YOUR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "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": "+16505550100",
    "configuration": {
      "default_domain_redirect_url": "https://piedpiper.com",
      "default_email_forward_address": "forward@piedpiper.com"
    }
  }'

import requests

def save_domain_owner():
  url = "https://api.woodpecker.co/rest/v2/domains/owner"
  headers = {
    "x-api-key": "{YOUR_API_KEY}",
    "Content-Type": "application/json"
  }
  payload = {
    "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": "+16505550100",
    "configuration": {
      "default_domain_redirect_url": "https://piedpiper.com",
      "default_email_forward_address": "forward@piedpiper.com"
    }
  }

  response = requests.post(url, headers=headers, 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 = save_domain_owner()
    print("POST response:", data)
  except Exception as e:
    print("Error:", e)

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/owner";
      String jsonData = """
        {
          "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": "+16505550100",
          "configuration": {
            "default_domain_redirect_url": "https://piedpiper.com",
            "default_email_forward_address": "forward@piedpiper.com"
          }
        }
        """;

      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());
    }
  }
}

const axios = require('axios');

async function saveDomainOwner() {
  const url = 'https://api.woodpecker.co/rest/v2/domains/owner';
  const headers = {
    'x-api-key': '{YOUR_API_KEY}',
    'Content-Type': 'application/json',
  };
  const data = {
    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: '+16505550100',
    configuration: {
      default_domain_redirect_url: 'https://piedpiper.com',
      default_email_forward_address: 'forward@piedpiper.com',
    },
  };

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

saveDomainOwner();

<?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/owner', [
    'json' => [
      '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' => '+16505550100',
      'configuration' => [
        'default_domain_redirect_url' => 'https://piedpiper.com',
        'default_email_forward_address' => 'forward@piedpiper.com',
      ],
    ],
  ]);

  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

Request processed successfully. Owner created or updated

{
  "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",
  "configuration": {
    "default_domain_redirect_url": "https://piedpiper.com",
    "default_email_forward_address": "forward@piedpiper.com"
  }
}

Body schema

Field	Type	Description
`email`	string	Owner email address
`first_name`	string	Owner first name
`last_name`	string	Owner last name
`company_name`	string/null	Company name
`address`	string	Owner 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
`configuration`	object	Default domain settings
└─ `default_domain_redirect_url`	string/null	Default redirect URL
└─ `default_email_forward_address`	string/null	Default forwarding address

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

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

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": "city",
      "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

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

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

Request​

Endpoint​

Headers​

Body​

Body schema​

Request samples​

Save domain owner​

Response​

Response examples​

Body schema​

Body schema​

Body schema​

Body schema​

Body schema​

Body schema​

Request

Endpoint

Headers

Body

Body schema

Request samples

Save domain owner

Response

Response examples

Body schema

Body schema

Body schema

Body schema

Body schema

Body schema