Adding and Verifying Domains

This guide explains how to add and verify a domain for your environment using the WP Engine Hosting API. To ensure platform security, all root domains must be verified via a DNS TXT record before traffic can be routed to your site.

Steps

1. Adding the domain to your environment

Use the Add Domain endpoint to add the domain to your environment.

Example request:

cURL

Add Domain

# Replace 12345 with your install ID
curl -X POST "https://api.wpengineapi.com/v1/installs/12345/domains" \
  -u "$WPE_API_USER_ID:$WPE_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "example.com",
    "primary": false
  }'

Go

Add Domain

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  user := os.Getenv("WPE_API_USER_ID")
  pass := os.Getenv("WPE_API_PASSWORD")
  installID := "12345" // replace with your install ID

  payload := map[string]interface{}{
    "name":    "example.com",
    "primary": false,
  }
  body, _ := json.Marshal(payload)

  url := fmt.Sprintf("https://api.wpengineapi.com/v1/installs/%s/domains", installID)
  req, _ := http.NewRequest("POST", url, bytes.NewBuffer(body))
  req.SetBasicAuth(user, pass)
  req.Header.Set("Content-Type", "application/json")

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()

  respBody, _ := io.ReadAll(resp.Body)
  fmt.Println(string(respBody))
}

JavaScript

Add Domain

const user = process.env.WPE_API_USER_ID;
const pass = process.env.WPE_API_PASSWORD;
const auth = "Basic " + Buffer.from(`${user}:${pass}`).toString("base64");
const installId = 12345; // replace with your install ID

try {
  const res = await fetch(`https://api.wpengineapi.com/v1/installs/${installId}/domains`, {
    method: "POST",
    headers: {
      Authorization: auth,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      name: "example.com",
      primary: false
    })
  });
  if (!res.ok) throw new Error(`Request failed: ${res.status}`);
  console.log(await res.json());
} catch (e) { console.error(e); }

Python

Add Domain

import os, requests

user = os.getenv("WPE_API_USER_ID")
password = os.getenv("WPE_API_PASSWORD")
install_id = 12345  # replace with your install ID

url = f"https://api.wpengineapi.com/v1/installs/{install_id}/domains"
resp = requests.post(
  url,
  auth=(user, password),
  json={"name": "example.com", "primary": False},
  timeout=10
)
print(resp.json())

Example response:

{
  "id": "e41fa98f-ea80-4654-b229-a9b765d0863a",
  "name": "example.com",
  "primary": false,
  "duplicate": false,
  "secure_all_urls": false,
  "ownership_status": "TXT_VERIFICATION_PENDING",
  "txt_verification_key": "_wpeproperty",
  "txt_verification_value": "abc123def456ghi789jkl012",
  "txt_verified_time": null,
  "txt_verified_domain": null,
  "network_type": "AN",
  "network_details": {
    "dns_config_info": {
      "cname": "example.wpengine.com",
      "a_records": ["192.0.2.1"]
    },
    "network_info": {
      "status": "ACTIVE",
      "ssl": {
        "status": "pending"
      }
    }
  },
  "redirects_to": []
}

Key fields in the response for DNS configuration and verification:

• txt_verification_key: The “name” or “host” for your TXT record.
• txt_verification_value: The “value” or “content” for your TXT record.
• network_details.dns_config_info.cname: The CNAME target for your domain.
• network_details.dns_config_info.a_records: Array of IP addresses for A records.
• ownership_status: This will initially return TXT_VERIFICATION_PENDING.

2. Update your DNS records

At your domain registrar (e.g., GoDaddy, Namecheap, etc.), add the records provided in the previous step:

• TXT Record: Add a TXT record using the txt_verification_key for the Host/Name field and the txt_verification_value for the Value field.
• Routing Record: Add your CNAME (from network_details.dns_config_info.cname) or A record (from network_details.dns_config_info.a_records) as provided in the API response.

Note

TXT verification is only required for root domains. Sub-domains do not require separate verification once the root domain is verified.

3. Trigger the verification check

Once the DNS records are saved, you must manually instruct WP Engine to look for them and move the domain out of the “unverified” state.

Use the Verify Domain TXT Record endpoint to trigger this check.

Example request:

cURL

Trigger Verification

# Replace 12345 with your install ID and the UUID with your domain ID
curl -X POST "https://api.wpengineapi.com/v1/installs/12345/domains/e41fa98f-ea80-4654-b229-a9b765d0863a/verification" \
  -u "$WPE_API_USER_ID:$WPE_API_PASSWORD"

Go

Trigger Verification

package main

import (
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  user := os.Getenv("WPE_API_USER_ID")
  pass := os.Getenv("WPE_API_PASSWORD")
  installID := "12345" // replace with your install ID
  domainID := "e41fa98f-ea80-4654-b229-a9b765d0863a"  // replace with your domain ID

  url := fmt.Sprintf("https://api.wpengineapi.com/v1/installs/%s/domains/%s/verification", installID, domainID)
  req, _ := http.NewRequest("POST", url, nil)
  req.SetBasicAuth(user, pass)

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()

  body, _ := io.ReadAll(resp.Body)
  fmt.Println(string(body))
}

JavaScript

Trigger Verification

const user = process.env.WPE_API_USER_ID;
const pass = process.env.WPE_API_PASSWORD;
const auth = "Basic " + Buffer.from(`${user}:${pass}`).toString("base64");
const installId = 12345; // replace with your install ID
const domainId = "e41fa98f-ea80-4654-b229-a9b765d0863a";  // replace with your domain ID

try {
  const res = await fetch(
    `https://api.wpengineapi.com/v1/installs/${installId}/domains/${domainId}/verification`,
    {
      method: "POST",
      headers: { Authorization: auth }
    }
  );
  if (!res.ok) throw new Error(`Request failed: ${res.status}`);
  console.log(await res.json());
} catch (e) { console.error(e); }

Python

Trigger Verification

import os, requests

user = os.getenv("WPE_API_USER_ID")
password = os.getenv("WPE_API_PASSWORD")
install_id = 12345  # replace with your install ID
domain_id = "e41fa98f-ea80-4654-b229-a9b765d0863a"   # replace with your domain ID

url = f"https://api.wpengineapi.com/v1/installs/{install_id}/domains/{domain_id}/verification"
resp = requests.post(url, auth=(user, password), timeout=10)
print(resp.json())

Example response:

{
  "id": "e41fa98f-ea80-4654-b229-a9b765d0863a",
  "name": "example.com",
  "txt_verification_key": "_wpeproperty",
  "txt_verification_value": "abc123def456ghi789jkl012",
  "txt_verified_time": "2026-05-06T12:05:00.007Z",
  "txt_verified_domain": "example.com"
}

4. Verify the activation status

The verification process typically completes within a few minutes. To confirm the domain is ready, use the Get Domain endpoint and check for the following values:

Example request:

cURL

Get Domain

# Replace 12345 with your install ID and the UUID with your domain ID
curl -X GET "https://api.wpengineapi.com/v1/installs/12345/domains/e41fa98f-ea80-4654-b229-a9b765d0863a" \
  -u "$WPE_API_USER_ID:$WPE_API_PASSWORD"

Go

Get Domain

package main

import (
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  user := os.Getenv("WPE_API_USER_ID")
  pass := os.Getenv("WPE_API_PASSWORD")
  installID := "12345" // replace with your install ID
  domainID := "e41fa98f-ea80-4654-b229-a9b765d0863a"  // replace with your domain ID

  url := fmt.Sprintf("https://api.wpengineapi.com/v1/installs/%s/domains/%s", installID, domainID)
  req, _ := http.NewRequest("GET", url, nil)
  req.SetBasicAuth(user, pass)

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()

  body, _ := io.ReadAll(resp.Body)
  fmt.Println(string(body))
}

JavaScript

Get Domain

const user = process.env.WPE_API_USER_ID;
const pass = process.env.WPE_API_PASSWORD;
const auth = "Basic " + Buffer.from(`${user}:${pass}`).toString("base64");
const installId = 12345; // replace with your install ID
const domainId = "e41fa98f-ea80-4654-b229-a9b765d0863a";  // replace with your domain ID

try {
  const res = await fetch(
    `https://api.wpengineapi.com/v1/installs/${installId}/domains/${domainId}`,
    {
      headers: { Authorization: auth }
    }
  );
  if (!res.ok) throw new Error(`Request failed: ${res.status}`);
  const data = await res.json();
  console.log("Status:", data.ownership_status);
  console.log("Verified at:", data.txt_verified_time);
  console.log(data);
} catch (e) { console.error(e); }

Python

Get Domain

import os, requests

user = os.getenv("WPE_API_USER_ID")
password = os.getenv("WPE_API_PASSWORD")
install_id = 12345  # replace with your install ID
domain_id = "e41fa98f-ea80-4654-b229-a9b765d0863a"   # replace with your domain ID

url = f"https://api.wpengineapi.com/v1/installs/{install_id}/domains/{domain_id}"
resp = requests.get(url, auth=(user, password), timeout=10)
data = resp.json()
print(f"Status: {data.get('ownership_status')}")
print(f"Verified at: {data.get('txt_verified_time')}")
print(data)

Example response when verification is complete:

{
  "id": "e41fa98f-ea80-4654-b229-a9b765d0863a",
  "name": "example.com",
  "primary": false,
  "duplicate": false,
  "secure_all_urls": false,
  "ownership_status": "TXT_VERIFIED",
  "txt_verification_key": null,
  "txt_verification_value": null,
  "txt_verified_time": "2026-05-06T12:05:00.007Z",
  "txt_verified_domain": "example.com",
  "network_type": "AN",
  "network_details": {
    "dns_config_info": {
      "cname": "example.wpengine.com",
      "a_records": ["192.0.2.1"]
    },
    "network_info": {
      "status": "ACTIVE",
      "ssl": {
        "status": "active"
      }
    }
  },
  "redirects_to": []
}

Key fields to check:

• ownership_status: Should now return TXT_VERIFIED.
• txt_verified_time: Indicates the exact timestamp the verification handshake was completed.
• txt_verified_domain: Confirms the specific domain successfully verified by the system.
• txt_verification_key and txt_verification_value: Will be null once verified.

Once verified, traffic will begin routing automatically. If this domain was designated as the Primary Domain, that change will now take effect.

Tip

If you need to retrieve your verification keys or check your DNS targets at a later time, you can call the Get Domain endpoint or visit the Domains page in the WP Engine User Portal.