Skip to main content

Add 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.

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

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

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 WHOIS record and constructed email addresses.

.. base_emails

array of strings

List of constructed email addresses.

.. whois_emails

array of strings

List of email addresses on WHOIS record.

.. email_array

array of strings

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.