Skip to main content

Verified Mark Certificate (VMC) lifecycle

The lifecycle of a Verified Mark Certificate (VMC) consists of these main steps:

  • Prepare certificate request

  • Submit certificate order

  • Complete domain control validation (DCV)

  • Complete organization and logo validation

  • Check order status

  • Download issued certificate

After DigiCert issues a certificate, you can perform these actions:

  • Reissue a certificate

  • Revoke a certificate

Prepare certificate request

To construct your request body and submit a VMC order request, you need to collect some key pieces of information:

  • Domains the certificate is for

  • DCV method to use when demonstrating control over domains

  • Legal name and registration information for the organization being validated

  • Logo information

    Note

    You can add logo information when you create the order or while the order is pending.

Domain names

Once you've collected the domains, enter them in the certificate.dns_names request body parameter:

Parameter

Type

Description

certificate

object

Object with certificate details.

.. dns_names

array

List of domains to be secured. Ordering a certificate for multiple domains can result in additional costs.

Important

Domains must be DMARC compliant to qualify for VMC. To learn more, visit How to Set Up DMARC to Qualify Your Domain for VMC.

Validity period

When you submit an order request for a VMC certificate, you choose the validity period of the order.

DigiCert offers Multi-year Plan support for VMC certificates. In your certificate order request, the order validity determines the duration of coverage you want for your Multi-year Plan (up to three years). When the active certificate for the Multi-year Plan is about to expire, you reissue the certificate to maintain your coverage.

Note

DigiCert does not support custom certificate validity periods for VMC certificates. Instead, DigiCert issues VMC certificates using the maximum certificate validity allowed by industry standards. This means:

  • If a VMC order is valid for 1 year, the certificate is valid for 1 year.

  • If a VMC order is valid for 2-3 years, the validity period of the first certificate issued for the order is 397 days. Each time you reissue a certificate for a VMC Multi-year Plan, the validity period of the reissued certificate defaults to 397 days or the validity period remaining on the order, whichever is shorter.

Use the order_validity.years request body parameter to set the validity period for the order.

Name

Req/Opt

Type

Description

order_validity

required

object

Object that defines the validity period of the order.

.. years

required

int

Number of years the order is valid.

Allowed values: 1-3

For example:

DCV method

The default DCV method for VMC orders is email. To use a different DCV method, include 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 (for example, 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 requires 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 requires 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. Using this method requires the ability to upload files to the web server.

Notice

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

Organization details

For VMC orders, industry standards require DigiCert to validate the organization included in your certificate request before we can issue your certificate.

To submit the details of an organization with your order, use the organization object in the body of your request. You can request a VMC for an organization that already exists in your CertCentral account, or you can create a new organization with your certificate order request.

Request certificate for existing organization

To associate an order with an existing organization, use the ID of the organization instead of providing the organization's details in the body of your request. Pass the ID of the organization as the value of the organization.id parameter. To get ID values for existing organizations, use the List organizations endpoint.

Note

To ensure unused organizations are never accidentally assigned to a new order request, deactivate them with the Deactivate organization endpoint.

This example shows the organization object in the JSON payload of a request for a certificate for an existing organization with an id of 112236:

{
...
    "organization": {
        "id": 112236
    },
...
}

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.

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.

This example shows the organization object for a request that creates a new organization:

{
...
  "organization": {
    "name": "Epigyne Unwieldiness llc",
    "assumed_name": "Epigyne Unwieldiness",
    "country": "us",
    "address": "932 Prospect Street",
    "address2": "Floor 08",
    "city": "Minneapolis",
    "state": "Minnesota",
    "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@example.com",
      "telephone": "666-186-6450",
      "telephone_extension": "736"
    },
    "contacts": [
      {
        "contact_type": "verified_contact",
        "first_name": "First",
        "last_name": "Last",
        "telephone": "123-456-7890",
        "job_title": "Project Manager",
        "email": "first.last@example.com"
      }
    ],
    "skip_duplicate_org_check": true
  },
...
}

(Optional) dcv_emails array

When using email as the DCV method, you can specify email addresses that should be used when sending the DCV emails. To do this, include the dcv_emails array in the request body. This array is a list of objects with email addresses for each domain on the order.

When using the dcv_emails parameter:

  • The email addresses you provide 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]).

  • We only send the DCV email to the specified email addresses. For example, if you specify john.doe@[domain_name], we do not send DCV emails to any of the default email addresses; or, if you specify admin@[domain.com], we do not send the DCV email to john.doe@[domain_name].

Logo details and file hosting

Before issuing your VMC certificate, DigiCert needs your logo and a few pieces of information to verify your rights to use the logo. You can provide this information when you create the order or when the order is pending. You also have the option to enable file hosting for your image and certificate files.Image and file hosting for VMCs

Notice

To submit a logo with your VMC order request:

  • You must format the logo as a Scalable Vector Graphic (SVG) file.

  • The SVG must adhere to the SVG Tiny Portable/Secure (SVG Tiny PS) profile.

  • In your JSON request body, include a base64-encoded string with the compressed logo data.

Learn more about formatting logos for VMC certificates.

In your JSON request body, use the vmc object to provide your logo, logo information, and file hosting settings. The vmc object has these fields:

Name

Req/Opt

Type

Description

vmc

optional

object

Object with logo data for a Verified Mark Certificate. If you submit an order request for a Verified Mark Certificate without including logo data, you must add this data to the order before DigiCert can issue the certificate. To update this information on an existing order, use the following endpoints:

Note: Your VMC order request may include a logo that already exists in your account for another VMC order.

  • If the existing logo is pending approval, we update all pending VMC orders that use the logo with the data from the new order request. If the new order request does not include logo data, the logo on the new order inherits the data that already exists for the logo.

  • If the existing logo is approved, any logo data in the new order request should match the data for the existing approved logo. Otherwise, the API returns an error.

.. logo

conditional

string

Compressed logo file, formatted as a base64-encoded string. To see if a logo is formatted correctly:

Note: A logo is required in requests that include other logo information (mark_type_data).

.. enable_hosting

optional

bool

If true, DigiCert hosts the image and certificate files. Otherwise, false (default).

When image and certificate file hosting is enabled, the Order info endpoint returns the location of the hosted files in the hosted_logo_location and hosted_cert_location response parameters.

Learn more about VMC image and file hosting.

.. mark_type

optional

string

Mark type.

Allowed values:registered_mark (default, registered trademarks) and government_mark (government marks).

.. mark_type_data

optional

object

Object with details about the logo the certificate secures.

.. .. country_code

conditional

string

Two-letter country code. For government marks, identifies the country or region that grants you rights to use the logo. For registered trademarks, identifies the country or region where the logo is registered.

For government marks, when you provide a citation value, you must also provide a country_code.

Allowed values: See Glossary – Trademark offices and country codes for VMC logos

.. .. state_province

optional

string

For government marks, state or province that grants you the rights to use the logo. Ignored for registered trademarks.

.. .. locality

optional

string

For government marks, the locality that grants you the rights to use the logo. Ignored for registered trademarks.

.. .. citation

optional

string

For government marks, identifier for the law, statute, or citation that grants you the rights to use the logo. Ignored for registered trademarks.

.. .. registration_number

optional

string

For registered trademarks, the trademark registration number for the logo. Ignored for government marks.

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, using vmc_basic as the product identifier:

https://digicert.com/services/v2/certificate/order/vmc_basic

For more information about this endpoint, including descriptions for all optional parameters, see Order Verified Mark Certificate (VMC).

A successful POST to the 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 on the details and status of the order.

  • certificate_id: The ID of the certificate.

    Use this ID to perform operations such as downloading or revoking the certificate.

  • domains: A list of objects with details about the domains submitted for validation with the certificate order request.

The example below shows a request and response for the Order Verified Mark Certificate endpoint:

(Optional) Upload logo

If you need to add or update the logo for a pending order, use the Upload VMC logo (SVG) or Upload VMC logo (encoded) endpoint.

  • Provide the ID of your pending VMC order in the endpoint path.

  • Set the Content-Type header.

    • For the Upload VMC logo (SVG) endpoint, use image/svg+xml.

    • For the Upload VMC logo (encoded) endpoint, use application/json.

  • Submit the logo data.

    • For the Upload VMC logo (SVG) endpoint, submit the XML or SVG data for the image as the payload of the request.

    • For the Upload VMC logo (encoded) endpoint, submit the compressed logo data formatted as a base64-encoded string in the JSON payload.

A successful POST request to this endpoint returns a response of 201 Created. The JSON response includes:

  • id: ID of the logo.

  • organization_id: ID of the organization on the order.

(Optional) Update VMC order

To change the mark type, logo registration details, and file hosting settings for an order, use the Update VMC order endpoint.

  • Provide the ID of your VMC order in the endpoint path.

  • Provide new values for the enable_hosting, mark_type, and mark_type_data parameters in the request body.

Warning

You can only change the mark_type and mark_type_data for an order while the order is pending. Changing the mark_type_data updates the logo's information for all pending orders using the same logo.

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

(Optional) Cancel certificate order

After placing a VMC order, there may be times when you need to cancel it. To cancel a VMC order, use the Update order status endpoint to change the status from pending to canceled.

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

Important

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

Complete domain control validation (DCV)

After submitting the VMC order request, you need to prove control over the domains on the order

Notice

Regardless of the DCV method chosen, you must prove control over each domain the certificate secures.

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.

DNS CNAME DCV method

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

  1. Copy the DCV token that was returned when the order was placed.

    If the domain existed in your account before you placed the order, you may need to 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 token that was returned when the order was placed.

    If the domain existed in your account before you placed the order, you may need to 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. Copy the DCV token that was returned when the order was placed.

    If the domain existed in your account before you placed the order, you may need to retrieve this value by using the Domain info endpoint and including the include_dcv=true URL query string.

  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, you must complete the validation process for the organization on the order. After you submit the order, DigiCert’s validation team begins working to validate the organization for VMC issuance.

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.

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

Get certificate

After the order status changes from pending to issued, your certificate is ready.

If you are hosting your own VMC certificate, use one of these endpoints to download the certificate:

If DigiCert is hosting your image and certificate file hosting is enabled, use the Order info endpoint to get the value of the hosted files from the hosted_logo_location and hosted_cert_location response parameters. Learn how to update DNS records when DigiCert hosts your files.

Reissue certificate

Reissuing a certificate allows you to add, remove, or swap domain names on the certificate without submitting a new order.

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 VMC, include both the current SANs in the dns_names parameter as well as any additional SANs to be secured. Even if some of these details are staying the same, you still need to include them the reissue request.

Important

Note

  • Certain changes, such as adding additional SANs (dns_names) may incur additional costs.

  • You may need to perform DCV checks for some or all domains on the reissue request.

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.

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

After a reissue is complete, download the new certificate (see Download certificate). To see the complete reissue history for an order, use the List reissues endpoint.

Renew order

Renewing an order allows you to link a new order to an expiring order, so 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, follow the instructions to prepare the certificate request. Additionally, make sure to include a value for either the renewed_thumbprint or renewal_of_order_id parameter:

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:

curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/vmc_basic' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
    "certificate": {
      "dns_names": ["example.net"]
    },
    "order_validity": {
      "years": 1
    },
    "vmc": {
      "logo": {{compressed_base64_encoded_svg_logo}},
      "enable_hosting": true,
      "mark_type": "registered_mark",
      "mark_type_data": {
        "country_code": "us",
        "registration_number": "A1234-B1234"
      }
    },
    "comments": "Message for the approver",
    "locale": "en",
    "renewal_of_order_id": 123456,
    "payment_method": "balance",
    "skip_approval": true,
    "organization": {
      "id": 123456
    }
}'

Note

If the organization details in the renewal request do not match the details on 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.

If an order is a renewal, the Order info response returns a value of true for the is_renewal parameter. The value of the renewed_order_id parameter is the order ID for the previous order:

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

Revoke certificate

Once your order is issued, you can submit a revoke request if needed. You can revoke a certificate using one of two endpoints. Both endpoints use the same request body parameters.

  • Revoke certificate: Use this endpoint to revoke a specific certificate using the certificate ID or serial number.

  • Revoke order certificate: Use this endpoint to revoke all certificates associated with an order ID.

After submitting the request, an administrator must approve it before DigiCert can revoke the certificate.

To skip the approval step and submit the request directly to DigiCert for revocation, include "skip_approval": true in the body of your request. To skip the approval step, the API key must have admin privileges. See Authentication.