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 data
  • Trademark registration number for the logo
  • Country code for the region where the logo is a registered trademark

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.

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

For VMC orders, you must use a validity period of 1 year. Use the order_validity.years request body parameter to set the validity period for the order and certificate.

Name Req/Opt Type Description
order_validity required object Object that defines validity period for the order and certificate.
.. years required int Number of years the order and certificate are valid.
Allowed values1

For example:

order_validity.years
{
...
	"order_validity": {
		"years": 1
	},
...
}

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.

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.

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:

json
{
...
    "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:

json
{
...
  "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": "ev_approver",
        "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].
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"
  }
]

Logo and trademark details

When you submit a request for a VMC order, DigiCert requires the following information to verify that your logo is a registered trademark for your organization:

  • Logo data
  • Country/region where the logo is a registered trademark
  • Trademark registration number for the logo

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 Portable/Secure (SVG-P/S) profile.
  • In your JSON request body, include a base64-encoded string with the compressed logo data.

To learn how to format a logo for VMC, see Getting Ready for BIMI: Prep Your Logo. After formatting your logo, use one of the following endpoints to check if it meets VMC logo requirements:

When submitting your order request, include the logo details in the vmc object:

Name Req/Opt Type Description
vmc optional object Object with logo data and trademark details for a Verified Mark Certificate.

If you submit an order request for a Verified Mark Certificate without including the logo or trademark information, you must add this information 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 trademark information from the new order request. If the new order request does not include trademark information, the logo on the new order inherits the trademark information that already exists for the logo.
  • If the existing logo is approved, any trademark information in the new order request should match the trademark information for the existing approved logo. Otherwise, the API returns an error.
.. logo conditional string Compressed logo data, formatted as a base64-encoded string. To see if a logo is formatted correctly:
Note: A logo is required when submitting a trademark country code or registration number in your request.
.. trademark_country_or_region optional string Two-letter code for the country or region where the logo is trademarked.
Allowed values:
  • us – United States
  • ca – Canada
  • em – European Trademark Office
  • gb – Great Britain
  • de – Germany
  • jp – Japan
  • au – Australia
  • es – Spain
.. trademark_registration_number optional string Trademark registration number of the logo.

For example:

json
{
  ...
  "vmc": {
    "logo": {{compressed_encoded_base64_string}},
    "trademark_country_code": "us",
    "trademark_registration_number": "A1234-B1234"
  },
  ...
}

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:

Order Verified Mark Certificate
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:

cURL
curl --request POST 'https://www.digicert.com/services/v2/order/certificate/vmc_basic' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "certificate": {
    "dns_names": [
        "example.com"
    ]
  },
  "vmc": {
    "logo": {{compressed_base64_encoded_svg_logo}},
    "trademark_country_code": "us",
    "trademark_registration_number": "A1234-B1234"
  },
  "organization": {
    "id": {{organization_id}},
    "contacts": [
      {
        "contact_type": "ev_approver",
        "first_name": "First",
        "last_name": "Last",
        "telephone": "123-456-7890",
        "job_title": "Project Manager",
        "email": "first.last@example.com"
      }
    ]
  },
  "order_validity": {
    "years": 1
  },
  "payment_method": "balance",
  "skip_approval": true
}'
201 Created (email)
{
  "id": 137368279,
  "domains": [
    {
      "id": 3530302,
      "name": "example.com"
    }
  ],
  "certificate_id": 138305366
}

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.
cURL
curl --request POST 'https://www.digicert.com/services/v2/order/certificate/12345/vmc/logo' \
--header 'Content-Type: image/svg+xml' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--data-raw '<?xml version="1.0" encoding="utf-8"?>
<!-- Generator: Adobe Illustrator 24.1.3, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
<svg version="1.2" baseProfile="tiny-ps" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
viewBox="0 0 594.1 800" xml:space="preserve">
<title>Example Logo</title>
<!-- logo data  -->
</svg>'
201 Created
{
  "id": 99,
  "organization_id": 1374401
}

(Optional) Update VMC order

While a VMC order is pending, you can update the trademark country code or registration number by using the Update VMC order endpoint.

  • Provide the ID of your pending VMC order in the endpoint path.
  • Provide new values for the trademark_country and trademark_registration_number parameters in the request body.

Changing these values updates the trademark information for all pending orders with the same logo.

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

cURL
curl --request PUT 'https://www.digicert.com/services/v2/order/certificate/{{order_id}}/vmc' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "trademark_country_code" : "us",
    "trademark_registration_number" : "C1234-D1234"
}'
204 No Content
// No content

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

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
// No content

Complete domain control validation (DCV)

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

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.

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

After the order status changes from pending to issued, you can download the certificate. Depending on your needs, there are four endpoints you can use to download a certificate:

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.

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:

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": {
    "dns_names": [
        "example.net"
    ],
    "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). 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:

json
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_encoded_base64_string}}
        "trademark_country_code": "us",
        "trademark_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
    }
}'

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:

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

Revoke certificate

Once your order is issued, you can submit a revocation request if needed. To submit a revocation request, use one of the following endpoints:

Both endpoints use the same request body parameters. After submitting the revocation request, the request needs to be approved by 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@example.net"
  },
  "comments": "I no longer need this cert."
}