OV/EV certificate lifecycle

The OV/EV certificate lifecycle consists of these main steps:

  • Prepare certificate request
  • Submit certificate order
  • (Optional) Cancel certificate order
  • Complete domain control validation (DCV)
  • Complete organization validation
  • Check order status
  • Download issued certificate

Once a certificate has been issued, you can perform any of these actions:

  • Reissue a certificate
  • Revoke a certificate

Prepare certificate request

In order to construct your request body and submit an order request, you need to collect some key pieces of information:

  • Domain name(s) to be secured by the certificate.
  • Certificate signing request (CSR) generated on the server where the certificate will be installed.
  • Validity period of the certificate (amount of time the certificate should be valid).
  • DCV method to use when demonstrating control over the domain(s).
  • The legal name and registration information for the Organization being validated.

Domain name(s)

Once you've collected the domain name(s) to be secured by the certificate, they should be entered in one of two request body parameters.

Parameter Type Description
common_name string Primary domain to be secured by the certificate.
dns_names array Any additional domains to be secured by the certificate.
Adding domains to this parameter may incur additional costs.

All OV/EV certificate orders allow you to include a specific additional SAN on single domain certificates for free. When constructing your request body, add the base domain ([your-domain].com) to the common_name parameter and then the other version of the domain (www.[your-domain].com) to the dns_names array.

Certificate signing request (CSR)

The CSR should be generated on the server where the certificate will be installed. Once generated, enter the PEM formatted CSR in the csr parameter of the request body. See Create a CSR (Certificate Signing Request) for additional information.

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, certificate.dns_names, and organization.id. If you are requesting an OV or EV certificate for an organization without an existing ID, you must provide values for all required parameters of the organization object. For more information, see Organization details.

Validity periods

When you submit an order request, you set a validity period for the certificate and for the order. The validity period of the certificate determines when the certificate expires. The validity period of the order determines how long you can reissue the certificate without additional costs.

DigiCert's public SSL/TLS certificates support orders for Multi-year Plans. With Multi-year Plans, you pick the SSL/TLS certificate, the certificate validity period, and the duration of coverage you want (up to six years). Until the order expires, you reissue the certificate at no additional cost each time it reaches the end of its validity period. For more information, see Multi-year Plans.

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

Flat fee contracts do not support Multi-year Plans. To find a solution that works with your contract, contact your account manager.

Order validity period

Use the order_validity object in your request body to customize the number of years or days the order is valid, or to set a custom expiration date for the order. Orders for Multi-year Plans can be valid for up to six years.

Order validity can be greater than certificate validity. If you do not specify a custom certificate validity period, we issue the certificate using the validity period of the order or the maximum certificate validity period defined in the CA/B Forum baseline requirements, whichever is shorter.

Name Req/Opt Type Description
order_validity required* object Defines the validity period of the order. Order validity determines the length of a Multi-year Plan.
*Requests must include a value for either the order_validity object or for one of the top-level order validity parameters (validity_yearsvalidity_days, or custom_expiration_date). The values you provide in the order_validity object override the top-level validity parameters.
.. years required* int Number of years the order is valid.
*Can be replaced by order_validity.days or order_validity.custom_expiration_date.
Range1-6
.. days optional int Number of days the order is valid.
Overrides order_validity.years.
Max2190
.. custom_expiration_date optional string Custom expiration date for the order.
Overrides order_validity.days and order_validity.years.
Formatdd MMM YYYY (for example, "09 JUN 2025")
Range: Must be within six years of the date you request the order.

For example:

order_validity.years
...
	"order_validity": {
		"years": 2
	},
...
order_validity.days
...
	"order_validity": {
		"days": 900 
	},
...
order_validity.custom_expiration_date
...
	"order_validity": {
		"custom_expiration_date": "09 JUN 2025"
	},
...

(Optional) Certificate validity period

Use the optional certificate.cert_validity object in your request body to customize the number of years or days the certificate is valid, or to set a custom expiration date for the certificate.

Name Req/Opt Type Description
certificate required object Certificate details.
.. 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 ignored in 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 values1
.. .. days optional int Number of days the certificate is valid after it is issued.
Overrides cert_validity.years.
Max397
.. .. custom_expiration_date optional string A custom expiration date for the certificate.
Overrides cert_validity.days and cert_validity.years.
Formatdd MMM YYYY (for example, "09 JUN 2021")
Range: Must be within 397 days of the date you request the certificate.

For example:

certificate.cert_validity.years
...
	"certificate": {
		...
		"cert_validity": {
			"years": 1
		}
	},
...
certificate.cert_validity.days
...
	"certificate": {
		...
		"cert_validity": {
			"days": 100
		}
	},
...
certificate.cert_validity.custom_expiration_date
...
	"certificate": {
		...
		"cert_validity": {
			"custom_expiration_date": "01 MAY 2021"
		}
	},
...

DCV method

Email DCV is the default DCV method used for OV/EV certificate orders. If desired, you can change the default DCV method by including the dcv_method parameter in the request body. The dcv_method parameter accepts these values:

Value Description
email Sends DCV emails to any email address (e.g., administrator and technical contacts) we find in the domain’s WHOIS record and to the five constructed email addresses for the domain (admin, administrator, webmaster, hostmaster, and postmaster
@[domain_name]).
When using this method, you can define a specific email scope by including the dcv_emails object.
dns-cname-token Returns a random value token in the response body to be added to a DNS CNAME record on the domain. Using this method required the ability to modify domain DNS records.
dns‑txt‑token Returns a random value token in the response body to be added to a DNS TXT record on the domain. Using this method required the ability to modify domain DNS records.
http‑token Returns a random value token in the response body to be placed in a .txt file on the website to be secured by the certificate. Using this method requires the ability to upload files to the web server.

See Demonstrate control over domains on a pending certificate order for more information about different DCV methods and how to complete them.

Organization details

Each OV/EV certificate order must include information about the organization that will receive the certificate. Before DigiCert can issue the certificate, industry standards require us to validate the organization you include in the request. For more information about organization validation, see TLS certificate organization validation process.

Consider validating your organizations and domains in advance to speed up the certificate issuance process. For more information, see OV/EV certificate immediate issuance.

Use the organization object in the body of your request to submit the details of an organization with your order. You can use this object to create a new organization, or you can associate the certificate with an organization that already exists in your account.

  • To create a new organization, use the organization object to provide the name, address, and contact information for individuals associated with the organization. For details about the structure and required parameters of the organization object, see the documentation for the Create organization endpoint.

    This example shows the organization object for a request that creates a new organization:
json
{
...
    "organization": {
        "name": "Epigyne Unwieldiness llc",
        "assumed_name": "Epigyne Unwieldiness",
        "country": "us",
        "address": "932 Prospect Street",
        "address2": "Floor 08",
        "city": "Minneapolis",
        "state": "mn",
        "zip": "40849",
        "telephone": "666-186-6450",
        "container": {
            "id": 93288
        },
        "organization_contact": {
            "first_name": "Gia",
            "last_name": "Booth",
            "job_title": "Clinical Laboratory Technician",
            "email": "gia.booth@inbox.com",
            "telephone": "666-186-6450",
            "telephone_extension": "736"
        },
        "skip_duplicate_org_check": true
    },
...
}

When you submit an order with organization details instead of providing an organization ID, we check the organizations that already exist in your account to avoid creating a duplicate.

  • If we find one matching organization, we automatically associate the order with that organization instead of creating a new one.
  • If we find two or more matching organizations, we automatically associate the order with the oldest matching organization in your account instead of creating a new one.

To override this behavior and force the request to create a new organization, set the organization.skip_duplicate_org_check parameter to true in the body of your request.

When you want to associate an order with an existing organization, we recommend always using the ID of the organization instead of the organization's details in the body of your request. To get the ID values for organizations in your account, use the List organizations endpoint. Additionally, we recommend deactivating unused organizations to ensure they are never accidentally assigned to a new order request. To deactivate an organization, use the Deactivate organization endpoint.

  • To associate the request with an existing organization, pass the ID of the organization as the value of the organization.id parameter. To get ID values for organizations that already exist in your account, use the List organizations endpoint.

    This example shows the organization object from a request that associates the order with an existing organization:
json
{
...
    "organization": {
        "id": 112236
    },
...
}

(Optional) dcv_emails array

When using the email DCV method, it's possible to specify the email addresses that should be used when sending the DCV emails. To do this, include the dcv_emails array in the request body and add an entry for each domain on the order.

When using this parameter, entered email addresses must be specified in the domain’s WHOIS record or be one of the default email addresses for the domain (defined by industry standards as: admin, administrator, webmaster, hostmaster, and/or postmaster @[domain_name]). In addition, we will only send the DCV email to the addresses specified.

For example, if you specify john.doe@[domain_name], we will not send DCV emails to any of the default email addresses. Or if you specify admin@[domain.com], we will not send the DCV email to john.doe@[domain_name].

Example dcv_emails array
"dcv_emails": [
  { 
    "dns_name": "example.com",
    "email_domain": "example.com",
    "email": "hostname@example.com"
  },
  { 
    "dns_name": "my.example.com",
    "email_domain": "example.com",
    "email": "admin@example.com"
  },
  { 
    "dns_name": "another.example.com",
    "email_domain": "example.com",
    "email": "admin@example.com"
  }
]

(Optional) ICA selection

When you request an OV or EV certificate with flex capabilities, you can choose which intermediate certificate authority (ICA) should sign the certificate.

To use ICA selection:

  • ICA selection must be enabled for your account.
    To enable ICA selection, contact your account manager or the Support team.
  • You must request an OV or EV certificate with flex capabilities.
    For a list of products with flex capabilities, see Flex certificates.
  • You must know the ca_cert_id of the ICA that you want to sign the certificate.
    For the ca_cert_id values of public ICAs that can sign each type of certificate, see Glossary – Public ICAs.

To select an ICA, include the certificate.ca_cert_id parameter in your certificate request. The value of this parameter is the ID of the ICA that should issue the certificate.

For example:

json
{
	"certificate": {
		"common_name": "example.test.com",
		"csr": {{csr}},
		"signature_hash": "sha256",
		"ca_cert_id": "4A7259E3E5D112A"
	},
	"order_validity": {
		"years": 1
	},
	"locale": "en",
	"skip_approval": true,
	"organization": {
		"id": {{organization_id}}
	},
	"payment_method": "profile"
}

Account administrators can limit the public ICAs you can select for each product. If you provide the ID of an ICA that is not allowed, the request returns an error. To get the IDs of allowed and default ICAs for products that support ICA selection in your account, use the Product limits endpoint. To customize the allowed intermediates for a product that supports ICA selection, use the Settings > Product Settings page in the CertCentral console.

Submit certificate order

After you collect the above information, you're ready to construct your request body and submit your order request. To do this, submit a POST request to the order endpoint for the type of certificate you want to buy.

The following table lists the endpoints for ordering different OV/EV SSL products:

Endpoint SSL products
Order SSL (type_hint) This endpoint attempts to determine the appropriate SSL product based on the information you provide in the request body.
Order Basic OV Basic OV SSL certificate
Order Basic EV Basic EV SSL certificate
Order Secure Site OV Secure Site OV SSL certificate
Order Secure Site EV Secure Site EV certificate
Order Secure Site Pro SSL Secure Site Pro SSL certificate
Order Secure Site Pro EV SSL Secure Site Pro EV SSL certificate
Order Private SSL Private SSL OV, Private SSL Plus, Private SSL Wildcard, and Private SSL Multi Domain certificates
Order OV/EV SSL Standard SSL, SSL Multi Domain, WildCard, EV SSL, SSL EV Multi-Domain, or SSL Cloud certificates.
Order Multi-year Plan Order a Multi-year Plan for a flex certificate.

Legacy customers can also use these endpoints to request GeoTrust, Thawte, Encryption Everywhere, and RapidSSL certificates. To get a list of products that are enabled for your account, use the Product list endpoint.

A successful POST to an order endpoint returns a 201 Created HTTP response code. The response body includes information that you can use to check the status of the order and to download the certificate when it is issued, including:

  • id – The ID of the order in your account.
    Use this ID with the Order info endpoint to check the details of the order.
  • certificate_id – The ID of the certificate.
    Use this ID to perform operations such as downloading or revoking the certificate.
  • dcv_random_value – Randomly generated token used for dns-txt-token and http-token DCV methods. This token expires after 30 days.

The example below shows the entire request and response bodies for a sample request to the Order OV/EV SSL endpoint:

cURL
curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/{{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",
            "app.example.com"
        ],
        "csr": "<csr>",
        "server_platform": {
            "id": 45
        },
        "signature_hash": "sha256"
    },
    "order_validity": {
        "years": 1
    },
    "comments": "Message for the approver",
    "disable_renewal_notifications": true,
    "locale": "en",
    "dcv_emails": [
      { 
        "dns_name": "example.com",
        "email_domain": "example.com",
        "email": "hostname@example.com"
      },
      { 
        "dns_name": "sub.example.com",
        "email_domain": "example.com",
        "email": "admin@example.com"
      },
      { 
        "dns_name": "app.example.com",
        "email_domain": "example.com",
        "email": "admin@example.com"
      }
    ]
    "payment_method": "balance",
    "organization": {
        "name": "Epigyne Unwieldiness llc",
        "assumed_name": "Epigyne Unwieldiness",
        "country": "us",
        "address": "932 Prospect Street",
        "address2": "Floor 08",
        "city": "Minneapolis",
        "state": "mn",
        "zip": "40849",
        "telephone": "666-186-6450",
        "container": {
            "id": 93288
        },
        "organization_contact": {
            "first_name": "Gia",
            "last_name": "Booth",
            "job_title": "Clinical Laboratory Technician",
            "email": "gia.booth@inbox.com",
            "telephone": "666-186-6450",
            "telephone_extension": "736"
        }
    },
    "custom_fields": [
        {
            "metadata_id": 11,
            "value": "Invoice #00001"
        }
    ]
}'
201 Created (email)
{
  "id": 112233,
  "certificate_id": 123456
}
201 Created (dns-txt-token or http-token)
{
  "id": 112233,
  "certificate_id": 123456,
  "dcv_random_value": "icru1984rnekfj"
}

After submitting the order, you can use the Order info endpoint to get order details and review the submitted information.

(Optional) Cancel certificate order

After placing an order, there may be times when you need to cancel it. To cancel an order, you need to change the status from pending to canceled. This is done with a PUT to the Update order status endpoint.

A successful PUT to this endpoint returns a 204 No Content HTTP response.

The status parameter only allows a value of CANCELED (case sensitive).

cURL
curl -X PUT \
  'https://www.digicert.com/services/v2/order/certificate/{{order_id}}/status' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
    "status": "CANCELED",
    "note": "Message about the cancellation."
}'
204 No Content
// empty

Complete domain control validation (DCV)

With the OV/EV order submitted, you now need to prove control over the domains on the order.

Regardless of the DCV method chosen, you must complete the DCV for each domain to be secured by the certificate. For example, if dns-txt-token method was chosen, you must create a DNS TXT record for each domain on the order.

Email DCV method

If the dcv_emails array was included in the response body, then DCV emails are sent to the addresses defined in the array. Otherwise, DCV emails are sent to these addresses:

  • All email addresses found in the domain's WHOIS record
  • These five constructed email addresses:
    • admin@[domain_name]
    • administrator@[domain_name]
    • webmaster@[domain_name]
    • hostmaster@[domain_name]
    • postmaster@[domain_name]

To complete email DCV, in your email client inbox locate the email with the subject [Action Required] Approve Certificate Request for [yourdomain] {Order #} and follow the instructions.

If you need to resend the DCV emails for a submitted order, you can use the Resend emails endpoint (replace the {{order_id}} placeholder with the order ID returned in the response body when you submitted the order).

DNS CNAME DCV method

Follow these steps to complete DNS CNAME DCV and demonstrate control over your domains:

  1. Copy the dcv_random_value that was generated when the order was placed. For OV/EV orders, you can retrieve this value by using the Domain info endpoint and including the include_dcv=true URL query string.
  2. Go to your DNS provider’s site and create a new CNAME record.
  3. In the hostname field (or equivalent), enter the random value you copied.
  4. In the record type field (or equivalent), select CNAME.
  5. In the target host field (or equivalent), enter dcv.digicert.com (this points the CNAME record to dcv.digicert.com).
  6. Select a Time-to-Live (TTL) value or use your DNS provider’s default value.
  7. Save the record.
  8. Repeat the above steps for each domain on the order.

Once you've added the DNS CNAME record for all domains on the order, you're ready to have us verify the CNAME records.

DNS TXT DCV method

Follow these steps to complete DNS TXT DCV and demonstrate control over your domains:

  1. Copy the dcv_random_value that was generated when the order was placed. For OV/EV orders, you can retrieve this value by using the Domain info endpoint and including the include_dcv=true URL query string.
  2. Go to your DNS provider’s site and create a new TXT record.
  3. In the TXT Value field, enter the random value you copied.
  4. Host field
    1. Base domain (for example, [yourdomain].com)
      Are you validating the base domain? Leave the Host field blank or add the @ symbol (depending on your DNS provider requirements).
    2. Subdomain (for example, [your.domain].com)
      Are you validating a subdomain? In the Host field, add the subdomain you are validating.
  5. In the record type filed (or equivalent), select TXT.
  6. Select a Time-to-Live (TTL) value or use your DNS provider’s default value.
  7. Save the record.
  8. Repeat the above steps for each domain on the order.

Once you've added the DNS TXT record for all domains on the order, you're ready to have us verify the TXT records.

HTTP token DCV method

Follow these steps to complete HTTP token DCV and demonstrate control over your domains:

  1. In CertCentral, copy the HTTP token information from the Order Detail page.
  2. In your preferred text editor, paste the random value you copied.
  3. Save the file with a filename of fileauth.txt.
  4. On your web server, upload the fileauth.txt file to this location: [yourdomain]/.well-known/pki-validation/fileauth.txt.

Perform DCV check

When you submit your certificate order, automatic domain control validation (DCV) polling begins immediately and runs for one week. For more information about automatic DCV polling, see Automatic domain control validation checks.

In addition to automatic DCV polling, you can perform a DCV check manually from your CertCentral account by following these steps:

  1. For each domain on the order, add the random token to the DNS TXT record (DNS TXT method), DNS CNAME record (DNS CNAME method), or to the fileauth.txt uploaded to the specified location (HTTP TXT DCV method).
  2. Sign in to CertCentral.
  3. Navigate to the Order Detail page for the new order.
  4. In the Order status section of the page, click on each domain listed as pending DCV, and then click Check to have the DCV method checked and confirmed.

Organization validation

In addition to domain validation, all OV/EV orders also require organization validation. Once an order is submitted, DigiCert's validation team will begin working on the OV/EV organization validation process.

Both organization and domain validation must be complete before the certificate can be issued.

Check validation status

You can check the current validation status for an organization with a GET to the Organization Validation details endpoint.

A successful GET to this endpoint returns a 200 OK HTTP response.

cURL
curl -X GET \
  'https://www.digicert.com/services/v2/organization/{{organization_id}}/validation' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}'
200 OK
{
  "validations": [
    {
      "type": "ov",
      "name": "OV",
      "description": "Normal Organization Validation",
      "status": "pending"
    },
    {
      "type": "ev",
      "name": "EV",
      "description": "Extended Organization Validation (EV)",
      "status": "pending",
      "verified_users": [
        {
          "id": 12,
          "first_name": "John",
          "last_name": "Smith"
        }
      ]
    }
  ]
}

Check order status

After submitting your order and completing the DCV for each domain, you'll want to know when the order status changes and the certificate is ready to download. The best way to do this is with a GET to the Status change list endpoint.

A GET to this endpoint returns three possible responses:

  • 200 OK (orders array) – The orders array lists all orders that have changed status in the specified timeframe. When your order's status changes from pending to issued, it will appear in the list. If multiple orders are returned, use either the order ID or certificate ID to locate the order.
  • 200 OK (empty object) – A response with an empty object ({}) means no orders have had a status change in the specified timeframe. Either increase the timeframe or wait to send another request.
  • 400 Bad Request – A response with the time_frame_too_long error code means the timeframe specified in the URL query string exceeds the maximum value. Reduce the timeframe to a value less than 10080 minutes (7 days).

cURL
curl -X GET \
  'https://www.digicert.com/services/v2/order/certificate/status-changes?minutes=10' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}'
200 OK
{
  "orders": [
    {
      "order_id": 112233,
      "certificate_id": 123456,
      "status": "issued"
    }
  ]
}
200 OK (no orders found)
{}
400 Bad Request
{
  "errors": [
    {
      "code": "time_frame_too_long",
      "message": "An error occurred while processing your request."
    }
  ]
}

Download certificate

Once the order status changes from pending to issued, your certificate is ready to be downloaded. Depending on your needs, there are four endpoints you can use to download your certificate:

Reissue certificate

Reissuing a certificate allows you to add, remove, or swap domain names, update the CSR, or change the signature hash of a certificate without submitting a new order. Additionally, if a certificate expires before the end of an order, you can reissue the certificate to receive a new certificate with a new expiration date.

A reissued certificate has a new certificate ID but the same order ID. After a reissue is approved, a new certificate is issued and needs to be reinstalled.

When reissuing a certificate, you need to provide this information:

  • Common name
  • SANs (include both the current SANs in the dns_names parameter as well as any additional SANs to be secured)
  • CSR (to get and reuse the current CSR, use the Request info endpoint)
  • Server platform ID (options listed here)

Even if some of the above details are staying the same, you still need to include it in the reissue request.

Note that certain changes, such as adding additional SANs ('dns_names') may incur additional costs.

It may be necessary to perform DCV for some or all of the domains.

The Reissue certificate endpoint accepts the following optional parameters:

  • comments – Adds a message to the request for the approver.
  • skip_approval ­– Allows the request to be immediately submitted for validation, bypassing the need to approve the reissue request.
  • certificate.cert_validity (Multi-year Plans) – Allows you to customize the validity period for the reissued certificate. For more information about the parameters in this object, see Multi-year Plan certificate validity period.

The following example shows the full request and response bodies for a request to the reissue certificate endpoint:

cURL
curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/{{order_id}}/reissue' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
  "certificate": {
    "common_name": "example.com",
    "dns_names": [
        "sub.example.com"
    ],
    "csr": "<csr>",
    "server_platform": {
      "id": 2
    },
    "signature_hash": "sha256"
    "skip_approval": true
  }
}'
201 Created
{
  "id": 112233,
  "requests": [
    {
      "id": 332211
    }
  ]
}
201 skip_approval
{
  "id": 112233,
  "certificate_id": 111112
}

After a reissue is complete, download the new certificate (see Download Certificate).

You can get a complete reissue history for an order by using the List reissues endpoint.

Renew order

Renewing an order allows you to link a new order to an expiring order such that you can track the history of your certificates using CertCentral and the Services API. When you renew an order, you receive a new certificate and a new order ID.

To renew, send a request to the endpoint for the certificate you want to buy. Follow the instructions to prepare the certificate request, and include a value for one of the following parameters:

Name Type Description
renewed_thumbprint string The SHA-1 thumbprint of the previous order's primary certificate. For more information, see How to check a certificate's thumbprint.
renewal_of_order_id int If order is a renewal, enter the previous order's ID.

For example, a request to renew the order with ID 123456 looks like this:

json
curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/{{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",
            "app.example.com"
        ],
        "csr": "<csr>",
        "server_platform": {
            "id": 45
        },
        "signature_hash": "sha256"
    },
    "order_validity": {
        "years": 2
    },
    "comments": "Message for the approver",
    "disable_renewal_notifications": true,
    "locale": "en",
    "renewal_of_order_id": 123456,
    "payment_method": "balance",
    "skip_approval": true,
    "organization": {
        "id": 123456
    },
    "custom_fields": [
        {
            "metadata_id": 11,
            "value": "Invoice #00001"
        }
    ]
}'

If the information for your organization in the renewal request does not match the information from the original order, you may need to provide new documentation to verify the changes. Additionally, certain changes, such as adding additional SANs (dns_names), may incur additional costs. You may need to perform DCV for some or all of the domains.

For renewal orders, the Order info response includes a true value for the is_renewal parameter. The value of the renewed_order_id parameter is the order ID for the previous order:

json
{
    "is_renewal": true,
    "renewed_order_id": 123456
}

After the status of the order renewal changes from pending to issued, you can download the new certificate (see Download certificate) and install it on your server. For more information about installing your certificate, see our SSL Certificate Installation Instructions & Tutorials page.

Revoke certificate

Once your order is issued, you can submit a revoke request if needed.

All revocation requests must be approved by an administrator in CertCentral before DigiCert will revoke the certificate. This approval step is required and cannot be skipped.

You can revoke a certificate using one of two endpoints:

Both endpoints use the same request body parameters.

After submitting the revocation request, the request needs to be approved my an administrator using the Update request status endpoint.

cURL
curl -X PUT \
  'https://www.digicert.com/services/v2/certificate/{{certificate_id}}/revoke' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
  "comments": "I no longer need this cert."
}'
201 Created
{
  "id": 1,
  "date": "2016-02-10T17:06:15+00:00",
  "type": "revoke",
  "status": "pending",
  "requester": {
    "id": 14,
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@digicert.com"
  },
  "comments": "I no longer need this cert."
}