Add domain

5 minute read

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.

Note

You must specify at least one validation type for the domain. Use the Get validation types endpoint to get available validation types.

Domain names with “www”

By default, if you are not using file-based domain control validation (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 -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"
}'

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)

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))

}

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

{
    "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"
        ]
    }
}

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

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

{
    "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

Name	Req/Opt	Type	Description
name	required	string	Domain name to submit
organization	required	object	The organization of the domain.
.. id	required	integer	Organization ID.
validations	required	array of objects	List of validation types for the domain.
.. type	required	string	Validation type identifier. See Glossary – Validation types
dcv_method	optional	string	Domain control validation method to use. Allowed values: See Glossary – DCV methods Default:
email
locale	optional	string	Locale code for the language of the DCV emails. Ignored if `dcv_method` is not `email`. Allowed values: See Glossary – Locale codes. Default: If the request does not include a valid locale code, we send the DCV emails in English.
email_array	optional	array of strings	When dcv_method is email, limit who receives verification DCV emails to addresses in this list. Ignored for other DCV methods.
Each email address must be a valid constructed email address for the domain or an approved DNS-based email contact from the domain’s DNS TXT record. Other email addresses are ignored.
Your CertCentral account settings* 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 email_array parameter from your request, DigiCert sends emails to all constructed email addresses and DNS TXT record emails for the domain.
*To view your account settings, in the left main menu, go to Settings > Preferences. Then, on the Preferences page, expand Advanced Settings, and look under Send Verification DCV Emails to.
keep_www	optional	string	If false (default) and you are not using file-based DCV, DigiCert removes any www.* subdomain label from the `name` value before adding the domain to your account and submitting it for validation. If true, DigiCert keeps the www. subdomain label if it is included in the name value. Learn more: Domain names with “www” This parameter does not affect domain names submitted with no www. subdomain label. *Note: When using file-based DCV (`http-token`), DigiCert always adds the domain and submits it for validation exactly as named in the request. Learn more: File-based domain control validation

Response parameters

Name	Type	Description
id	integer	ID of the added domain.
validation_emails	object	Email addresses used when sending DCV emails. Only returned for email DCV method.
.. name_scope	string	Domain scope used for constructed email addresses and DNS-based contacts.
.. base_emails	array of strings	List of constructed email addresses.
.. email_array	array of strings	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.*
The email_array response parameter is only returned if you changed the default settings for which email addresses can receive verification DCV emails for your account.
*To view your account settings, in the left main menu, go to Settings > Preferences. Then, on the Preferences page, expand Advanced Settings, and look under Send Verification DCV Emails to.
dcv_token	object	DCV token details. Only returned for dns-txt-token, dns-cname-token, and http-token DCV methods.
.. token	string	Random value to use for DCV validation.
.. status	string	DCV status. Possible values:pending, active
.. expiration_date	string	Timestamp for when the token expires. Format: UTC timezone and ISO 8601 date
.. http_token_url	string	Filename of the text file and where it should be placed on the web server. Only returned for http-token DCV method.