Verified Mark Certificate (VMC) lifecycle

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

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

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.

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.

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
  },
...
}

"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"
  }
]

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 Verified Mark Certificates and Common Mark 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:

"vmc": {
  "logo": {{compressed_base64_encoded_svg_logo}},
  "enable_hosting": true,
  "mark_type": "registered_mark",
  "mark_type_data": {
    "country_code": "us",
    "registration_number": "A1234-B1234"
  }
}

"vmc": {
  "logo": {{compressed_base64_encoded_svg_logo}},
  "enable_hosting": true,
  "mark_type": "government_mark",
  "mark_type_data": {
    "country_code": "us",
    "state_province": "utah",
    "locality": "lehi",
    "citation": {{citation}}
  }
}

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:

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

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}},
    "enable_hosting": true,
    "mark_type": "registered_mark",
    "mark_type_data": {
      "country_code": "us",
      "registration_number": "A1234-B1234"
    }
  },
  "organization": {
    "id": {{organization_id}},
    "contacts": [
      {
        "contact_type": "verified_contact",
        "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"
}'

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

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

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>'

{
  "id": 99,
  "organization_id": 1374401
}

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 '{
    "mark_type_data": {
      "country_code": "au",
      "registration_number": "C1234-D1234"
    }
}'

// No content

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.

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."
}'

// No content

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

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:

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.

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 -X GET \
  'https://www.digicert.com/services/v2/organization/{{organization_id}}/validation' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}'

{
  "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"
        }
      ]
    }
  ]
}

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:

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}}'

{
  "orders": [
    {
      "order_id": 112233,
      "certificate_id": 123456,
      "status": "issued"
    }
  ]
}

{}

{
  "errors": [
    {
      "code": "time_frame_too_long",
      "message": "An error occurred while processing your request."
    }
  ]
}

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.

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.

The Reissue certificate endpoint accepts the following optional parameters:

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

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
  }
}'

{
  "id": 112233,
  "certificate_id": 111112
}

{
  "id": 112233,
  "requests": [
    {
      "id": 332211
    }
  ]
}

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.

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:

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
    }
}'

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

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.

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.

curl --request PUT 'https://www.digicert.com/services/v2/certificate/{{certificate_identifier}}/revoke' \
--header 'Content-Type: application/json' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--data-raw '{
  "skip_approval": true
}'

curl --request PUT 'https://www.digicert.com/services/v2/certificate/{{certificate_identifier}}/revoke' \
--header 'Content-Type: application/json' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--data-raw '{
  "comments": "I no longer need this certificate."
}'

curl --request PUT 'https://www.digicert.com/services/v2/certificate/{{certificate_identifier}}/revoke' \
--header 'Content-Type: application/json' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--data-raw '{
  "revocation_reason": "superseded",
  "skip_approval": true
}'

// empty

{
  "id": 1,
  "date": "2016-02-10T17:06:15+00:00",
  "type": "revoke",
  "status": "pending",
  "requester": {
    "id": 242140,
    "first_name": "Jack",
    "last_name": "White",
    "email": "j.white@fakeaddy.com"
  },
  "comments": "Revoked via API!"
}