---
title: "Add domain"
source_url: https://dev.digicert.com/certcentral-apis/services-api/domains/add-domain.html
api_method: POST
api_endpoint: "/services/v2/domain"
api_url: "https://www.digicert.com/services/v2/domain"
---

**POST** `https://www.digicert.com/services/v2/domain`

Use this endpoint to add a domain, associate it with an organization, and submit it for validation.


> **Info**
>
> You must specify at least one validation type for the domain. Use the [Get validation types](https://dev.digicert.com/md/certcentral-apis/services-api/domains/validation-types.md) endpoint to get available validation types.


> **Info**
>
> **Domain validation reuse periods will continue to decrease**
>
> Due to industry-wide changes, the domain validation reuse period will continue to shorten over time. Starting February 24, 2026, the maximum domain validation reuse period will be 199 days. For existing pre-validated domains, the new expiration date must be calculated as the last validation date + 199 days. By 2029, the domain validation reuse period will be reduced to 10 days. For more information, see <a href="https://knowledge.digicert.com/alerts/domain-validation-reuse-changes-in-2026" target="_blank" rel="noopener noreferrer">Domain validation reuse changes in 2026</a>.


## Domain names with "www"

By default, if you are not using [file-based domain control validation](https://dev.digicert.com/md/certcentral-apis/services-api/file-based-domain-control-validation-http-token.md) (DCV)*, the **Add domain** endpoint always removes the *www.* subdomain label from the `name` value. For example, if you send *www.example.com* and your DCV method is `email`, `dns-txt-token`, or `dns-cname-token`, DigiCert adds *example.com* to your account and submits it for validation.

To keep the *www* and limit the scope of the approval to the *www* subdomain, set the value of the `keep_www` request parameter to true.


> **Tip**
>
> *Adding and validating a domain using the `email`, `dns-txt-token`, or `dns-cname-token` DCV methods demonstrates control over any subdomains of that domain.
>
> Adding and validating a domain using file-based DCV (`http-token`) only demonstrates control over the exact FQDN in your request.


## Example requests and responses

**cURL**

```bash
curl -X POST \
  https://www.digicert.com/services/v2/domain \
  --header 'Content-Type: application/json' \
  --header 'X-DC-DEVKEY: {{api_key}}' \
  --data-raw '{
    "name": "example.com",
    "organization": {
      "id": 112233
    },
    "validations": [
      {
        "type": "ov"
      },
      {
        "type": "ev"
      }
    ],
    "dcv_method": "email"
}'
```

**Python**

```python
import requests

url = "https://www.digicert.com/services/v2/domain"

payload = "{\n    \"name\": \"example.com\",\n    \"organization\": {\n        \"id\": 112233\n    },\n    \"validations\": [\n        {\n            \"type\": \"ov\"\n        },\n        {\n        \t\"type\": \"ev\"\n        }\n    ],\n    \"dcv_method\": \"email\"\n}"
headers = {
    'X-DC-DEVKEY': "{{api_key}}",
    'Content-Type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
```

**Go**

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://www.digicert.com/services/v2/domain"

	payload := strings.NewReader("{\n    \"name\": \"example.com\",\n    \"organization\": {\n        \"id\": 112233\n    },\n    \"validations\": [\n        {\n            \"type\": \"ov\"\n        },\n        {\n        \t\"type\": \"ev\"\n        }\n    ],\n    \"dcv_method\": \"email\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-DC-DEVKEY", "{{api_key}}")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

**NodeJS**

```javascript
var request = require("request");

var options = { method: 'POST',
  url: 'https://www.digicert.com/services/v2/domain',
  headers: 
   { 'Content-Type': 'application/json',
     'X-DC-DEVKEY': '{{api_key}}' },
  body: 
   { name: 'example.com',
     organization: { id: 112233 },
     validations: [ { type: 'ov' }, { type: 'ev' } ],
     dcv_method: 'email' },
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
```


**201 Created (email)**

```
{
    "id": 123356,
    "validation_emails": {
        "name_scope": "example.com",
        "base_emails": [
            "postmaster@example.com",
            "administrator@example.com",
            "hostmaster@example.com",
            "admin@example.com",
            "webmaster@example.com"
        ]
    }
}
```

**201 Created (dns-txt-token)**

```
{
    "id": 123356,
    "dcv_token": {
        "token": "{{random_token}}",
        "status": "pending",
        "expiration_date": "2019-03-02T17:21:39+00:00"
    }
}
```

**201 Created (dns-cname-token)**

```json
{
    "id": 123356,
    "dcv_token": {
        "token": "{{random_token}}",
        "status": "pending",
        "expiration_date": "2019-03-02T17:22:05+00:00",
        "verification_value": "dcv.digicert.com"
    }
}
```

**201 Created (http-token)**

```json
{
    "id": 671903,
    "dcv_token": {
        "token": "{{random_token}}",
        "status": "pending",
        "expiration_date": "2019-03-02T17:22:48+00:00",
        "http_token_url": "http://example.com/.well-known/pki-validation/{{random_filename}}.txt"
    }
}
```


## Request parameters

<table class="params-table">
<thead>
<tr>
<th>Name</th>
<th>Req/Opt</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>required</td>
<td>string</td>
<td>Domain name to submit</td>
</tr>
<tr>
<td>organization</td>
<td>required</td>
<td>object</td>
<td>The organization of the domain.</td>
</tr>
<tr>
<td>.. id</td>
<td>required</td>
<td>integer</td>
<td>Organization ID.</td>
</tr>
<tr>
<td>validations</td>
<td>required</td>
<td>array of objects</td>
<td>List of validation types for the domain.</td>
</tr>
<tr>
<td>.. type</td>
<td>required</td>
<td>string</td>
<td>Validation type identifier. See Glossary – Validation types</td>
</tr>
<tr>
<td>dcv_method</td>
<td>optional</td>
<td>string</td>
<td>Domain control validation method to use.<br>Allowed values: See Glossary – DCV methods<br>Default:
email</td>
</tr>
<tr>
<td>locale</td>
<td>optional</td>
<td>string</td>
<td>Locale code for the language of the DCV emails. Ignored if <code>dcv_method</code> is not <code>email</code>.<br>Allowed values: See Glossary – Locale codes.<br>Default: If the request does not include a valid locale code, we send the DCV emails in English.</td>
</tr>
<tr>
<td>email_array</td>
<td>optional</td>
<td>array of strings</td>
<td>When <code>dcv_method</code> is <code>email</code>, limit who receives verification DCV emails to addresses in this list. Ignored for other DCV methods.<br>Each email address must be a valid <a href="https://docs.digicert.com/en/certcentral/manage-certificates/organization-and-domain-management/manage-domains/supported-domain-control-validation--dcv--methods-for-domain-prevalidation.html#constructed-email-dcv-method" target="_blank" rel="noopener noreferrer">constructed email address</a> for the domain or an approved DNS-based email contact from the domain’s DNS TXT record. Other email addresses are ignored.<br>Your CertCentral account settings<sup>*</sup> configure the addresses you can choose from when limiting verification DCV email recipients. If none of the emails you provide are configured to receive verification DCV emails, or if you omit the <code>email_array</code> parameter from your request, DigiCert sends emails to all constructed email addresses and DNS TXT record emails for the domain.<br><sup>*</sup>To view your account settings, in the left main menu, go to <strong>Settings > Preferences</strong>. Then, on the <strong>Preferences</strong> page, expand <strong>Advanced Settings</strong>, and look under <strong>Send Verification DCV Emails to</strong>.</td>
</tr>
<tr>
<td>keep_www</td>
<td>optional</td>
<td>string</td>
<td>If false (default) and you are not using file-based DCV<em>, DigiCert removes any </em>www.<em> subdomain label from the <code>name</code> value before adding the domain to your account and submitting it for validation. If true, DigiCert keeps the </em>www.* subdomain label if it is included in the name value. Learn more: <a href="#section-idm4546517960196833284456370824">Domain names with "www"</a><br>This parameter does not affect domain names submitted with no www. subdomain label.<br><strong>*Note:</strong> When using file-based DCV (<code>http-token</code>), DigiCert always adds the domain and submits it for validation exactly as named in the request. Learn more: <a href="https://dev.digicert.com/md/certcentral-apis/services-api/file-based-domain-control-validation-http-token.md">File-based domain control validation</a></td>
</tr>
</tbody>
</table>

## Response parameters

<table class="params-table">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>id</td>
<td>integer</td>
<td>ID of the added domain.</td>
</tr>
<tr>
<td>validation_emails</td>
<td>object</td>
<td>Email addresses used when sending DCV emails. Only returned for email DCV method.</td>
</tr>
<tr>
<td>.. name_scope</td>
<td>string</td>
<td>Domain scope used for constructed email addresses and DNS-based contacts.</td>
</tr>
<tr>
<td>.. base_emails</td>
<td>array of strings</td>
<td>List of constructed email addresses.</td>
</tr>
<tr>
<td>.. email_array</td>
<td>array of strings</td>
<td>Complete list of email addresses you can choose from when limiting who receives DCV emails for the domain. Configure this list in your CertCentral account.<sup>*</sup><br>The <code>email_array</code> response parameter is only returned if you changed the default settings for which email addresses can receive verification DCV emails for your account.<br><sup>*</sup>To view your account settings, in the left main menu, go to <strong>Settings > Preferences</strong>. Then, on the <strong>Preferences</strong> page, expand <strong>Advanced Settings</strong>, and look under <strong>Send Verification DCV Emails to</strong>.</td>
</tr>
<tr>
<td>dcv_token</td>
<td>object</td>
<td>DCV token details. Only returned for dns-txt-token, dns-cname-token, and http-token DCV methods.</td>
</tr>
<tr>
<td>.. token</td>
<td>string</td>
<td>Random value used to complete DCV. For DNS CNAME validation, this value is used to construct the CNAME record target.</td>
</tr>
<tr>
<td>.. status</td>
<td>string</td>
<td>DCV status.<br>Possible values:pending, active</td>
</tr>
<tr>
<td>.. expiration_date</td>
<td>string</td>
<td>Timestamp for when the token expires.<br>Format: UTC timezone and ISO 8601 date</td>
</tr>
<tr>
<td>.. http_token_url</td>
<td>string</td>
<td>Filename of the text file and where it should be placed on the web server. Only returned for http-token DCV method.</td>
</tr>
</tbody>
</table>