Order DV SSL

POST

https://www.digicert.com/services/v2/order/certificate/{{dv_ssl_certificate_id}}

End of 2-year public SSL/TLS certificates

The Services API no longer issues public SSL/TLS certificates with a validity period greater than 397 days. Requests for public SSL/TLS certificates that specify an order validity greater than 1 year (or 397 days) create a new Multi-year Plan. To learn more about this change, see End of 2-year DV, OV, and EV public SSL/TLS certificates.

Use this endpoint to request or renew a DV SSL certificate. To renew a certificate, you must place the request from the same account used to order the original certificate.

Replace {{dv_ssl_certificate_id}} in the URL with the product identifier for the type of certificate to order:

ssl_dv_geotrust – GeoTrust Standard DV SSL Certificate
ssl_dv_rapidssl – RapidSSL Standard DV SSL Certificate
wildcard_dv_geotrust – GeoTrust Wildcard DV SSL Certificate
wildcard_dv_rapidssl – RapidSSL Wildcard DV SSL Certificate
cloud_dv_geotrust – GeoTrust Cloud DV

Public TLS/SSL certificates support Multi-year Plans. With Multi-year Plans, you pick the SSL/TLS certificate, the certificate validity period, and the duration of coverage you want. To order a Multi-year Plan with this endpoint, use the order_validity object to set the validity period of the order (up to six years). Optionally, use the certificate.cert_validity parameter to customize the validity of the first certificate issued for the order. For more information, see Multi-year Plans.

Enterprise License Agreement (ELA) and Flat Fee contracts only support 1- and 2-year Multi-year Plans.

In addition to these products, DigiCert offers flexible certificates that support any type of domain configuration. You can order a flexible DV certificate with the Order GeoTrust DV SSL endpoint. To activate this certificate type for your CertCentral account, contact your account manager or our Support team. For more information, see Flex certificates.

You can only order certificates that are enabled for your account. Use the Product list endpoint to get the list of products available for your account.

Example requests and responses

cURL

curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/{{dv_ssl_certificate_id}}' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
    "certificate": {
        "common_name": "example.com",
        "dns_names": [
        	"sub.example.com",
        	"log.example.com"
        ],
        "csr": "<csr>",
        "server_platform": {
            "id": 2
        }
    },
    "custom_expiration_date": "",
    "comments": "Message for the approver.",
    "container": {
        "id": 69748
    },
    "custom_renewal_message": "Renew me.",
    "skip_approval": true,
    "disable_ct": 0,
    "order_validity": {
      "years": 1
    },
    "custom_fields": [
        {
            "metadata_id": 12,
            "value": "Invoice #12345"
        }
    ],
    "payment_method": "balance",
    "dcv_method": "email",
    "dcv_emails": [
    	{
    		"dns_name": "example.com",
    		"email_domain": "example.com",
    		"email": "admin@example.com"
    	},
    	{
    		"dns_name": "sub.example.com",
    		"email_domain": "example.com",
    		"email": "jim.smith@example.com"
    	},
    	{
    		"dns_name": "log.example.com",
    		"email_domain": "example.com",
    		"email": "it@example.com"
    	}
    ],
    "locale": "en",
    "technical_contact": {
        "first_name": "Jim",
        "last_name": "Smith",
        "telephone": "555-555-5555",
        "job_title": "IT Admin",
        "email": "jim.smith@example.com"
    }
}'

Python

import requests

url = "https://www.digicert.com/services/v2/order/certificate/{{dv_ssl_certificate_id}}"

payload = "{\n    \"certificate\": {\n        \"common_name\": \"example.com\",\n        \"dns_names\": [\n        \t\"sub.example.com\",\n        \t\"log.example.com\"\n        ],\n        \"csr\": \"<csr>\",\n        \"server_platform\": {\n            \"id\": 2\n        }\n    },\n    \"custom_expiration_date\": \"\",\n    \"comments\": \"Message for the approver.\",\n    \"container\": {\n        \"id\": 69748\n    },\n    \"custom_renewal_message\": \"Renew me.\",\n    \"skip_approval\": true,\n    \"disable_ct\": 0,\n    \"order_validity\": {\n            \"years\": 1\n        },\n    \"custom_fields\": [\n        {\n            \"metadata_id\": 12,\n            \"value\": \"Invoice #12345\"\n        }\n    ],\n    \"payment_method\": \"balance\",\n    \"dcv_method\": \"email\",\n    \"dcv_emails\": [\n    \t{\n    \t\t\"dns_name\": \"example.com\",\n    \t\t\"email_domain\": \"example.com\",\n    \t\t\"email\": \"admin@example.com\"\n    \t},\n    \t{\n    \t\t\"dns_name\": \"sub.example.com\",\n    \t\t\"email_domain\": \"example.com\",\n    \t\t\"email\": \"jim.smith@example.com\"\n    \t},\n    \t{\n    \t\t\"dns_name\": \"log.example.com\",\n    \t\t\"email_domain\": \"example.com\",\n    \t\t\"email\": \"it@example.com\"\n    \t}\n    ],\n    \"locale\": \"en\",\n    \"technical_contact\": {\n        \"first_name\": \"Jim\",\n        \"last_name\": \"Smith\",\n        \"telephone\": \"555-555-5555\",\n        \"job_title\": \"IT Admin\",\n        \"email\": \"jim.smith@example.com\"\n    }\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/order/certificate/{{dv_ssl_certificate_id}}"

	payload := strings.NewReader("{\n    \"certificate\": {\n        \"common_name\": \"example.com\",\n        \"dns_names\": [\n        \t\"sub.example.com\",\n        \t\"log.example.com\"\n        ],\n        \"csr\": \"<csr>\",\n        \"server_platform\": {\n            \"id\": 2\n        }\n    },\n    \"custom_expiration_date\": \"\",\n    \"comments\": \"Message for the approver.\",\n    \"container\": {\n        \"id\": 69748\n    },\n    \"custom_renewal_message\": \"Renew me.\",\n    \"skip_approval\": true,\n    \"disable_ct\": 0,\n    \"order_validity\": {\n            \"years\": 1\n        },\n    \"custom_fields\": [\n        {\n            \"metadata_id\": 12,\n            \"value\": \"Invoice #12345\"\n        }\n    ],\n    \"payment_method\": \"balance\",\n    \"dcv_method\": \"email\",\n    \"dcv_emails\": [\n    \t{\n    \t\t\"dns_name\": \"example.com\",\n    \t\t\"email_domain\": \"example.com\",\n    \t\t\"email\": \"admin@example.com\"\n    \t},\n    \t{\n    \t\t\"dns_name\": \"sub.example.com\",\n    \t\t\"email_domain\": \"example.com\",\n    \t\t\"email\": \"jim.smith@example.com\"\n    \t},\n    \t{\n    \t\t\"dns_name\": \"log.example.com\",\n    \t\t\"email_domain\": \"example.com\",\n    \t\t\"email\": \"it@example.com\"\n    \t}\n    ],\n    \"locale\": \"en\",\n    \"technical_contact\": {\n        \"first_name\": \"Jim\",\n        \"last_name\": \"Smith\",\n        \"telephone\": \"555-555-5555\",\n        \"job_title\": \"IT Admin\",\n        \"email\": \"jim.smith@example.com\"\n    }\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

var request = require("request");

var options = { method: 'POST',
  url: 'https://www.digicert.com/services/v2/order/certificate/{{dv_ssl_certificate_id}}',
  headers: 
   { 'Content-Type': 'application/json',
     'X-DC-DEVKEY': '{{api_key}}' },
  body: 
   { certificate: 
      { common_name: 'example.com',
        dns_names: [ 'sub.example.com', 'log.example.com' ],
        csr: '<csr>',
        server_platform: { id: 2 } },
     custom_expiration_date: '',
     comments: 'Message for the approver.',
     container: { id: 69748 },
     custom_renewal_message: 'Renew me.',
     skip_approval: true,
     disable_ct: 0,
     order_validity: { years: 1 },
     custom_fields: [ { metadata_id: 12, value: 'Invoice #12345' } ],
     payment_method: 'balance',
     dcv_method: 'email',
     dcv_emails: 
      [ { dns_name: 'example.com',
          email_domain: 'example.com',
          email: 'admin@example.com' },
        { dns_name: 'sub.example.com',
          email_domain: 'example.com',
          email: 'jim.smith@example.com' },
        { dns_name: 'log.example.com',
          email_domain: 'example.com',
          email: 'it@example.com' } ],
     locale: 'en',
     technical_contact: 
      { first_name: 'Jim',
        last_name: 'Smith',
        telephone: '555-555-5555',
        job_title: 'IT Admin',
        email: 'jim.smith@example.com' } },
  json: true };

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

  console.log(body);
});

201 (skip approval, email DCV)

{
  "id": 6484932,
  "certificate_id": 6079436
}

201 (skip approval, dns-txt-token/http-token DCV)

{
  "id": 6484932,
  "certificate_id": 6079436,
  "dcv_random_value": {{dcv_token}}
}

201 (one step approval)

{
  "id": 144457158,
  "requests": [
    {
      "id": 11963731,
      "status": "pending"
    }
  ]
}

201 (two step approval)

{
  "id": 144457159,
  "requests": [
    {
      "id": 11963732,
      "status": "submitted"
    }
  ]
}

201 (auto approve, dns-txt-token/http-token DCV)

{
  "id": 144457160,
  "requests": [
    {
      "id": 11963733,
      "status": "approved"
    }
  ],
  "certificate_id": 145451220,
  "dcv_random_value": {{dcv_token}}
}

201 (auto approve, email DCV)

{
  "id": 144457162,
  "requests": [
    {
      "id": 11963735,
      "status": "approved"
    }
  ],
  "certificate_id": 145451222
}

Request parameters

For information about allowed values for certificate fields, see Publicly Trusted Certificates – Data Entries that Violate Industry Standards.

Name	Req/Opt	Type	Description
certificate	required	object	Certificate details.
.. common_name	required	string	Domain to be secured.
.. dns_names	optional	array	Additional domains to be secured. Can result in additional costs. (See Best practices – Get both versions of a domain for free.)
.. csr	required^*	string	Certificate signing request (CSR). Note: The Services API does not extract information from the CSR to fill in the details of a certificate request. You must provide values for all relevant request parameters, including `certificate.common_name` and `certificate.dns_names`.
.. organization_units	optional	array	Department in your organization the certificate is for. Deprecated. This field is ignored for public TLS/SSL certificate requests. See our knowledge base article.
.. server_platform	optional	object	Server platform type. Default: `-1` (other)
.. .. id	required	int	Server platform ID. See Glossary – Server platforms
.. cert_validity	optional	object	Defines the validity period of the first certificate issued for this order. Cannot exceed order validity period. If not provided, the certificate's validity period defaults to the validity period of the order or the maximum certificate validity period defined by CA/B Forum baseline requirements, whichever is shorter. This object is not used for requests from accounts that do not have Multi-year Plans enabled.
.. .. years	optional	int	Number of years the certificate is valid after it is issued. Can be replaced with `cert_validity.days` or `cert_validity.custom_expiration_date`. Allowed value: `1`
.. .. days	optional	int	Number of days the certificate is valid after it is issued. Overrides `cert_validity.years`. Max: `397`
.. .. custom_expiration_date	optional	string	A custom expiration date for the certificate. Overrides `cert_validity.days` and `cert_validity.years`. Format: `dd MMM YYYY` (for example, `"09 JUN 2021"`) Range: Must be within 397 days of the date you request the certificate.
.. ca_cert_id	optional	string	ID of the intermediate certificate authority (ICA) certificate to select as the issuing certificate. To get the `ca_cert_id` value for an ICA, use the Product list endpoint. The following public DV products support the option for ICA selection: `ssl_dv_geotrust_flex` `ssl_dv_thawte` `ssl_dv_rapidssl` `wildcard_dv_rapidssl` `ssl_dv_ee` Account administrators can customize the default and allowed ICAs for each product at the container or user role level. If you do not provide a value for this parameter, we issue the certificate using the default ICA. If you provide the `ca_cert_id` value for an ICA that is not allowed, the request returns an error^. To see the custom ICA settings for each product, use the Product limits endpoint. ^This parameter is ignored if the option for ICA selection is not enabled for your account. For more information, see ICA certificate chain option.
renewed_thumbprint	optional*	string	If order is a renewal, enter the SHA-1 thumbprint of the previous order's primary certificate. For more information, see How to check a certificate's thumbprint. *Renewal orders must include either a `renewed_thumbprint` or `renewal_of_order_id` value.
order_validity	required	object	Defines the validity period of the order. Order validity determines the length of a Multi-year Plan.
.. years	required^*	int	Number of years the order is valid. ^Can be replaced by `order_validity.days` or `order_validity.custom_expiration_date`. Range*: `1`-`6`
.. days	optional	int	Number of days the order is valid. Overrides `order_validity.years`. Max: `2190`
.. custom_expiration_date	optional	string	Custom expiration date for the order. Overrides `order_validity.days` and `order_validity.years`. Format: `dd MMM YYYY` (for example, `"09 JUN 2025"`) Range: Must be within six years of the date you request the order.
validity_years	optional	int	Number of years the order is valid. Deprecated. Use the `order_validity` object to set the validity period of the order. Use the `cert_validity` object to set the validity period of the certificate. Range: `1`-`6`
validity_days	optional	int	Number of days the order is valid. Deprecated. Use the `order_validity` object to set the validity period of the order. Use the `cert_validity` object to set the validity period of the certificate. Overrides `validity_years`. Max: `2190`
custom_expiration_date	optional	string	Custom expiration date for the order. Deprecated. Use the `order_validity` object to set the validity period of the order. Use the `cert_validity` object to set the validity period of the certificate. Overrides `validity_days` and `validity_years`. Format: `yyyy-MM-dd` Range: Must be within six years of the date you request the order.
comments	optional	string	Comments about the order for the approver.
apply_cr_discount	optional	bool	When `true`, applies any competitive replacement discounts that are available for the domains on the order. To calculate competitive replacement discounts before you place an order, use the List replacement benefits endpoint. Default: `false`
serial_number	optional	string	Serial number of the non-DigiCert certificate for which you expect to receive a competitive replacement discount when you place the order. If not provided, we use the information from your order request to look for a match among certificates on the CT log servers, and we apply a discount based on the best match we can find.
auto_renew	optional	int	Specify if the certificate should automatically renew. Allowed values: `0` (disabled) or `1` (enabled) Default: `0`
auto_reissue	optional	int	Auto-reissue setting for the order. When auto-reissue is enabled for a Multi-year Plan, DigiCert automatically creates a reissue request for the most recently issued certificate when that certificate is within 30 days of expiring. Auto-reissue repeats until the order expires. To learn more about reissuing certificates in a Multi-year Plan, see Multi-year Plans. Allowed values: `0` (disabled) or `1` (enabled) Default: `0` (disabled) Note: We ignore the `auto_reissue` request parameter if: The product does not support Multi-year Plans. Multi-year Plans are disabled for the account.
custom_renewal_message	optional	string	Custom message to be included in renewal notifications.
disable_renewal_notifications	optional	bool	Specify if renewal notification emails should be disabled. Default: `false`
additional_emails	optional	array	Additional email addresses to receive certificate notification emails (e.g., certificate issuance, duplicate certificate, certificate renewals, etc.).
renewal_of_order_id	optional*	int	If order is a renewal, enter the previous order's ID. *Renewal orders must include either a `renewed_thumbprint` or `renewal_of_order_id` value.
payment_method	optional	string	Payment method for the order. Allowed values: `balance` (default): Pay with account balance. Returns an error if the option to bill to account balance is disabled for the account, or if the account balance has insufficient funds. Learn how to debit purchases against your CertCentral account balance. `profile`: Pay with the account’s default credit card. Returns an error if no default credit card is configured for the account. Learn how to set up a default credit card. `card`: Pay with a new credit card. Requests that use `card` as the payment method must include a `credit_card` and `billing_address` object. Returns an error if the option to pay with a credit card is disabled for the account.
credit_card	conditional	object	Object with information about the credit card charged for the order. Required if `payment_method` is `card`.
.. number	required	string	Credit card number.
.. expiration_month	required	integer	Credit card expiration month. Format as a two-digit number between `01` (Jan) and `12` (Dec).
.. expiration_year	required	integer	Credit card expiration year. Format as a four-digit number. For example: `2026`
.. cvv	required	integer	Card verification value (CVV). Format as a three- or four-digit number. For example: `333` or `4444`
.. cardholder_name	required	string	Cardholder’s first and last name.
billing_address	conditional	object	Object with information about the billing address. Required if `payment_method` is `card`.
.. address	required	string	Billing street address.
.. address2	optional	string	Continuation of street address.
.. city	required	string	Billing city.
.. state	conditional	string	Billing state or province. Optional for some countries.
.. country	required	string	Billing country.
.. zip	conditional	string	Billing zip or postal code. Optional for some countries.
dcv_method	optional	string	DCV method to use when verifying domain control. See Glossary – DCV methods
dcv_emails	optional	array	List specifying the email scope when sending DCV emails. You can add an entry for each DNS name being secured by the certificate.
.. dns_name	required	string	DNS name on the certificate that this scope should apply to.
.. email_domain	required	string	WHOIS domain record to use to verify email addresses. This value must match the `dns_names` base domain.
.. email	optional	string	Email address to use when sending DCV emails. This email address must appear on the WHOIS record for the domain specified in the `email_domain` parameter.
locale	optional	string	Language that the DCV email should use. See Glossary – Locale codes
skip_approval	optional	bool	Specify if the order should skip the approval step and be immediately submitted for validation and issued when complete. Default: `false`
disable_ct	optional	bool	Specify if CT logging for the certificate should be disabled. Order-specific CT logging must be enabled or this will be ignored. See Allow Users to Keep Certificates Out of CT Logs. Default: `false`
container	optional	object	If needed, specify the container the order should be placed under.
.. id	required	int	Container ID.
custom_fields	optional*	array	Account-specific custom fields. *Whether or not these fields are required depends on your custom field settings.
.. metadata_id	required	int	Custom field ID.
.. value	required	string	Value for the custom field. Data validation type depends on your custom field settings.
technical_contact	optional	object	Technical contact details.
.. first_name	required	string	First name of the technical contact.
.. last_name	required	string	Last name of the technical contact.
.. telephone	required	string	Telephone number of the technical contact.
.. job_title	optional	string	Job title of the technical contact.
.. email	required	string	Email address of the technical contact.
alternative_order_id	optional	string	A custom alphanumeric ID to assign the order. To see the `alternative_order_id` assigned to an order, use the Order info endpoint. Alternative order IDs do not replace the unique order ID that DigiCert assigns each order request. You cannot use alternative order IDs to search for or identify orders in API calls that require an `order_id` parameter in the URL path or request body. If the Require unique alternative order IDs option is enabled in your account settings, you cannot submit order requests with an alternative order ID that is already assigned to an order in your account. Use this feature to enable nonce order requests, or to prevent your integration from creating duplicate orders in cases where you do not receive a response from the API. Account administrators can toggle this option from the CertCentral console. From the Settings > Preferences page, open the Advanced Settings menu, and look for the Alternative order ID option. This parameter is always optional, even if the Require unique alternative order IDs option is enabled in your account. If a request does not use this parameter, no `alternative_order_id` value is assigned to the order. Maximum length: 64 characters Note: The Require unique alternative order IDs option may not appear in the advanced settings menu for all CertCentral accounts. To enable this option for your account, contact your account manager or our Support team.
enable_guest_access	optional	int	Whether to enable guest access for the order. This parameter is not allowed if guest access is disabled in your account settings. Allowed values: `1` (enabled) or `0` (disabled) Default: The default configuration for new orders is determined by your account settings. Account administrators can change these settings from the Guest Access page in the CertCentral console.
use_auth_key	optional	bool	Whether to check the DNS records for an AuthKey request token when you submit the order request. For information about using an AuthKey for immediate DV certificate issuance, see DV certificate immediate issuance. Default: `true` if an AuthKey exists for the account. Otherwise, `false`. Note: This parameter is ignored in requests for Encryption Everywhere DV certificates. All requests for Encryption Everywhere DV certificates require an AuthKey request token for DCV checks.

Response parameters

Name	Type	Description
id	int	Order ID.
certificate_id	int	Certificate ID.
dcv_random_value	string	Random value used for domain control validation. Only returned when using either `dns-txt-token` or `http-token` as the DCV method.
certificate_chain	array	Ordered list of objects with information about each certificate in the certificate chain (for example, SSL certificate, intermediate CA certificate, and root certificate). The first object in the array contains the end-entity certificate. The next objects contain the intermediate CA certificates. The final object contains the root certificate. Each certificate is signed by the certificate in the object that follows it. For example, the end-entity certificate is signed by the intermediate CA certificate. Note: This endpoint only returns the `certificate_chain` array for TLS certificates that DigiCert issues immediately. To get the certificate chain after DigiCert issues a certificate, use the Certificate chain endpoint.
.. subject_common_name	string	Common name on the certificate.
.. pem	string	PEM-encoded certificate data.
requests	array	Contains information about the request.
.. id	int	Request ID.
.. status	string	Request status. Possible values: `pending`, `submitted`, `approved`, `rejected`

Example requests and responses

Request parameters

Response parameters

About