---
title: Create a domain
url: https://developers.wpengine.com/docs/managed-hosting-platform/api/reference/operations/createdomain/
image: https://developers.wpengine.com/og/docs/managed-hosting-platform/api/reference/operations/createdomain.png
---

# Create a domain

POST

/installs/{install_id}/domains

Select code sample

```sh
curl --request POST \
  --url https://api.wpengineapi.com/v1/installs/294deacc-d8b8-4005-82c4-0727ba8ddde0/domains \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example.com", "primary": true }'
```

-

Adds a domain or redirect to the install, and optionally sets it as the primary domain. For domain verification, see the [Adding and Verifying Domains](https://developers.wpengine.com/docs/managed-hosting-platform/api/guides/adding-and-verifying-domains) guide.

## Limitations & Warnings

- The domain is created, but doesn’t serve traffic until its ownership is verified. Verification status is in the `ownership_status` field (`TXT_VERIFIED` or `TXT_VERIFICATION_PENDING`).
- To verify the domain, add a DNS TXT record to your domain registry using the `txt_verification_key` and `txt_verification_value` fields on the created domain. Then POST to `/installs/{install_id}/domains/{domain_id}/verification` to complete verification.

## Authorizations

- **[basicAuth](https://developers.wpengine.com/docs/managed-hosting-platform/api/reference/#basicauth)**

## Parameters

### Path Parameters

**install_id**

required

string format: uuid

ID of install

#### Example

```
294deacc-d8b8-4005-82c4-0727ba8ddde0
```

## Request Bodyrequired

##### Properties

- name - **required** - The name of the new domain
- primary - **optional** - Sets the domain as the primary domain on the install
- redirect_to - **optional** - ID of a domain to create a redirect to

Media typeapplication/json

object

**name**

required

string

**primary**

boolean

**redirect_to**

string format: uuid

### Example

```json
{
  "name": "example.com",
  "primary": true
}
```

## Responses

### 201

Returns the created `Domain` object.

Media typeapplication/json

object

**name**

required

string

**duplicate**

required

boolean

**primary**

required

boolean

**id**

required

string

**network_type**

The WP Engine network type configured for the domain. Possible values are ‘AN’ (Advanced Network) ‘GES’ (Global Edge Security) and ‘LEGACY’.

string

**network_details**

Details about the network configuration for the domain.

object

**dns_config_info**

DNS configuration information for the domain.

object

**cname**

The CNAME value to use to configure a DNS CNAME record for the domain.

string

**a\_records**

IP addresses that can be used to configure a DNS A record for the domain.

Array\<string>

**network_info**

object

**status**

The status of the network configuration for the domain.

string

**ssl**

SSL configuration status

object

**status**

string

**redirects_to**

Array\<object>

object

**id**

string format: uuid

**name**

string

**secure_all_urls**

required

boolean

**txt_verified_time**

The time when the TXT record was verified

string

nullable

**txt_verified_domain**

The domain that the TXT record was verified for

string

**txt_verification_key**

The TXT record verification key. Null if the domain is already verified.

string

nullable

**txt_verification_value**

The TXT record verification value. Null if the domain is already verified.

string

nullable

**ownership_status**

Ownership verification status of the domain.

- TXT_VERIFIED indicates the domain ownership has been verified.
- TXT_VERIFICATION_PENDING indicates the domain ownership still requires verification using TXT record.

**NOTE**: To verify the domain, a DNS TXT record must be added to your domain registry using the `txt_verification_key` and `txt_verification_value` fields provided with the domain. After the TXT record is in place, POST to `/installs/{install_id}/domains/{domain_id}/verification` to complete verification.

string

Allowed values: TXT_VERIFIED TXT_VERIFICATION_PENDING

#### Example

```json
{
  "name": "torquemag.io",
  "duplicate": true,
  "primary": true,
  "id": "e41fa98f-ea80-4654-b229-a9b765d0863a",
  "network_type": "AN",
  "network_details": {
    "dns_config_info": {
      "cname": "wp.wpenginepowered.com",
      "a_records": [
        "127.0.0.1"
      ]
    },
    "network_info": {
      "status": "ACTIVE",
      "ssl": {
        "status": "active"
      }
    }
  },
  "redirects_to": [
    {
      "id": "e41fa98f-ea80-4006-b229-a9b765d0863a",
      "name": "redirect.com"
    }
  ],
  "secure_all_urls": false,
  "txt_verified_time": "2026-04-20T16:00:00.007Z",
  "txt_verified_domain": "example.com",
  "txt_verification_key": "_wpe_verification",
  "ownership_status": "TXT_VERIFIED"
}
```

### 400

Bad Request

Media typeapplication/json

object

**message**

required

A message regarding the error that occurred on the server

string

**documentation_url**

(Optional) A URL where documentation regarding this specific error can be found

string

**errors**

An array of error objects describing specific errors that arose when servicing the request

Array\<object>

object

**resource**

required

The name of the resource that was being processed when the error occurred

string

**field**

required

(Optional) The specific field associated with the error

string

**type**

required

(Optional) A type associated with the error. `invalid_value`, `access_error`, `value_unavailable`

string

**code**

required

(Optional) A machine code relating to the error that occurred with the field and resource

string

**message**

required

(Optional) A human-readable message relating to the error that occurred with the field and resource

string

#### Example

```json
{
  "message": "Invalid request.",
  "errors": [
    {
      "resource": "Resource",
      "field": "field_name",
      "type": "invalid_value",
      "code": "invalid",
      "message": "The value is invalid."
    }
  ]
}
```

### 401

Authentication Error

Media typeapplication/json

object

**message**

required

A message regarding the error that occurred on the server

string

**documentation_url**

(Optional) A URL where documentation regarding this specific error can be found

string

#### Example

```json
{
  "message": "Bad Credentials"
}
```

### 403

Not authorized

Media typeapplication/json

object

**message**

required

A message regarding the error that occurred on the server

string

**documentation_url**

(Optional) A URL where documentation regarding this specific error can be found

string

#### Example

```json
{
  "message": "You don't have permission to perform that action"
}
```

### 404

Not found

Media typeapplication/json

object

**message**

required

A message regarding the error that occurred on the server

string

**documentation_url**

(Optional) A URL where documentation regarding this specific error can be found

string

#### Example

```json
{
  "message": "Not Found"
}
```

### 429

Too many requests

### 500

Internal Server Error

Media typeapplication/json

object

**message**

required

A message regarding the error that occurred on the server

string

#### Example

```json
{
  "message": "An unexpected error occurred, please try again in a few minutes"
}
```

### 502

An invalid response was received from an upstream server

### 503

Service unavailable

## Was this helpful?

Thanks for the feedback!

```json
{"@context":"https://schema.org","@graph":[{"@type":"WebSite","@id":"https://developers.wpengine.com/#website","name":"WP Engine Product Documentation","url":"https://developers.wpengine.com/","description":"Resources for developing, deploying, and scaling on WP Engine.","inLanguage":"en-US","keywords":["API documentation","product documentation","headless WordPress","managed WordPress hosting"],"publisher":{"@id":"https://wpengine.com/#organization"}}]}
```