Order Common Mark Certificate (CMC)

  15 minute read  

POST https://www.digicert.com/services/v2/order/certificate/mark_certificate
Use this endpoint to order an Common Mark Certificate (CMC).

CMCs allow companies to place a brand logo next to the “sender” field in customer inboxes—even before the message is opened. The logo acts as confirmation of your domain’s DMARC (Domain-based Message Authentication, Reporting, and Conformance) status and your organization’s authenticated identity. Digicert’s CMC supports Prior Use Mark and Modified Registered Trademark. For more information, see Common Mark Certificate.

When you create an order for a CMC certificate, you can include the logo in your order request. To submit a logo with your order request:

  • Format the data for your SVG logo as a compressed, base64-encoded string. For example, in a bash shell, run this command:
    echo '<XML content for your SVG logo>' | gzip | base64
  • In the JSON payload, submit the string containing the encoded logo data as the value of the vmc.logo parameter.

Example requests and responses

curl --request POST 'https://www.digicert.com/services/v2/order/certificate/mark_certificate' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "certificate": {
    "dns_names": [
        "<example.com>"
    ]
  },
  "vmc": {        
        "logo": "H4sIAAAAAAAAA01OS0\/EIBj8K+TzWspLGmpKN9lVb5t40LPpWmxJEJpCyrq\/XqoXT\/PIZGa6w\/XLoc2s0QavgdUUkPEfYbR+0vD2+owVHPoubhMqQR81zCktD4TknOss6rBOhFNKSUkA2qzJx3DVQBFFjErUCvhfzgFdhmhe1vBpndGQrP\/GS4S+SzY50w9juJj33e3In9MtQ5rRqOHcNBWdRbu14nYWqnAs1K+QvBLScVlJNWPWOKww25m6ASozTsPd0yM78fsyQ\/a6AuVt\/wPn9Zxi+wAAAA==",
        "enable_hosting": "1"       
  },
  "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"
      },
      {
        "first_name": "Doe",
        "last_name": "John",
        "email": "doe.john@digicert.com",
        "job_title": "Analyst",
        "telephone": "+1 1234547860",
        "name": "Doe John",
        "contact_type": "organization_contact"
      },
      {
        "first_name": "John",
        "last_name": "Doe",
        "email": "jd@jd.com",
        "job_title": "Analyst",
        "telephone": "1234567890",
        "name": "John Doe",
        "contact_type": "technical_contact",
        "type": "existing_contact"
       }
    ]
  },
  "order_validity": {
    "years": 1
  },
  "payment_method": "balance"
}
curl --request POST 'https://www.digicert.com/services/v2/order/certificate/mark_certificate' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "certificate": {
    "dns_names": [
        "<example.com>"
    ]
  },
  "vmc": {         
        "logo": "H4sIAAAAAAAAA01OS0\/EIBj8K+TzWspLGmpKN9lVb5t40LPpWmxJEJpCyrq\/XqoXT\/PIZGa6w\/XLoc2s0QavgdUUkPEfYbR+0vD2+owVHPoubhMqQR81zCktD4TknOss6rBOhFNKSUkA2qzJx3DVQBFFjErUCvhfzgFdhmhe1vBpndGQrP\/GS4S+SzY50w9juJj33e3In9MtQ5rRqOHcNBWdRbu14nYWqnAs1K+QvBLScVlJNWPWOKww25m6ASozTsPd0yM78fsyQ\/a6AuVt\/wPn9Zxi+wAAAA==",
        "enable_hosting": "1"       
  },
  "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"
      },
      {
        "first_name": "Doe",
        "last_name": "John",
        "email": "doe.john@digicert.com",
        "job_title": "Analyst",
        "telephone": "+1 1234547860",
        "name": "Doe John",
        "contact_type": "organization_contact"
      },
      {
        "first_name": "John",
        "last_name": "Doe",
        "email": "jd@jd.com",
        "job_title": "Analyst",
        "telephone": "1234567890",
        "name": "John Doe",
        "contact_type": "technical_contact",
        "type": "existing_contact"
       }
    ]
  },
  "order_validity": {
    "years": 1
  },
  "payment_method": "balance"
}
curl --request POST 'https://www.digicert.com/services/v2/order/certificate/mark_certificate' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "certificate": {
    "dns_names": [
        "<example.com>"
    ]
  },
  "vmc": {        
        "logo": "H4sIAAAAAAAAA01OS0\/EIBj8K+TzWspLGmpKN9lVb5t40LPpWmxJEJpCyrq\/XqoXT\/PIZGa6w\/XLoc2s0QavgdUUkPEfYbR+0vD2+owVHPoubhMqQR81zCktD4TknOss6rBOhFNKSUkA2qzJx3DVQBFFjErUCvhfzgFdhmhe1vBpndGQrP\/GS4S+SzY50w9juJj33e3In9MtQ5rRqOHcNBWdRbu14nYWqnAs1K+QvBLScVlJNWPWOKww25m6ASozTsPd0yM78fsyQ\/a6AuVt\/wPn9Zxi+wAAAA==",
        "enable_hosting": "1"       
  },
  "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"
      },
      {
        "first_name": "Doe",
        "last_name": "John",
        "email": "doe.john@digicert.com",
        "job_title": "Analyst",
        "telephone": "+1 1234547860",
        "name": "Doe John",
        "contact_type": "organization_contact"
      },
      {
        "first_name": "John",
        "last_name": "Doe",
        "email": "jd@jd.com",
        "job_title": "Analyst",
        "telephone": "1234567890",
        "name": "John Doe",
        "contact_type": "technical_contact",
        "type": "existing_contact"
       }
    ]
  },
  "order_validity": {
    "years": 1
  },
  "payment_method": "balance"
}
{
  "id": 144457095,
  "requests": [
    {
      "id": 11963702,
      "status": "pending"
    }
  ]
}
{
  "id": 144457092,
  "requests": [
    {
      "id": 11963700,
      "status": "submitted"
    }
  ]
}
{
  "id": 144457096,
  "requests": [
    {
      "id": 11963703,
      "status": "approved"
    }
  ],
  "domains": [
    {
      "id": 3612638,
      "name": "example.com",
      "dns_name": "example.com"
    }
  ],
  "certificate_id": 145451175
}
{
  "id": 144457097,
  "domains": [
    {
      "id": 3612638,
      "name": "example.com",
      "dns_name": "example.com"
    }
  ],
  "certificate_id": 145451176
    "vmc": {        
        "logo_id": 5891    
   }
}

Request parameters

NameReq/OptTypeDescription
certificaterequiredobjectObject with certificate details.
.. dns_namesoptionalarrayList of domains to be secured. Ordering a certificate for multiple domains can result in additional costs.
vmcoptionalobjectObject with logo data for a Common Mark Certificate. If you submit an order request for a Common 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 CMC order request may include a logo that already exists in your account for another CMC order.
.. logoconditionalstringCompressed logo file, formatted as a base64-encoded string. To see if a logo is formatted correctly:
It is recommended to include the logo in the request; otherwise, you must upload an SVG logo to a pending order.
.. enable_hostingoptionalboolIf 1, DigiCert hosts the image and certificate files. Otherwise, 0 (default).
When image and certificate file hosting is enabled, the Order info](/certcentral-apis/services-api/orders/order-info.html) endpoint returns the location of the hosted files in the hosted_logo_location and hosted_cert_location response parameters.
[Learn more about CMC image and file hosting.
renewed_thumbprintoptional*stringIf order is a renewal, enter the SHA-1 thumbprint of the previous order’s primary certificate. For more information, see How to check a certificate’s thumbprint.
*Renewal orders must include either a renewed_thumbprint or renewal_of_order_id value.
order_validityrequiredobjectObject that defines the validity period of the order.
DigiCert offers Multi-year Plan support for CMC certificates. When you submit an order request for a CMC certificate, the order validity determines the duration of coverage you want for the 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 CMC certificates. Instead, DigiCert issues CMC certificates using the maximum certificate validity allowed by industry standards. This means:
.. yearsrequiredintNumber of years the order is valid.
Range: 1-3
commentsoptionalstringComments about the order for the administrator or approver reviewing the order request. The comments value is stored on the order request. If the order skips the approval step (skip_approval is set to true), any provided comments value is ignored since CertCentral creates the order directly without creating a corresponding request.
auto_renewoptionalintSpecify if the certificate should automatically renew.
Allowed values: 0 (disabled) or 1 (enabled)
Default: 0
custom_renewal_messageoptionalstringCustom message to be included in renewal notifications.
disable_renewal_notificationsoptionalboolSpecify if renewal notification emails should be disabled.
Default:
false
additional_emailsoptionalarrayAdditional email addresses to receive certificate notification emails (for example, certificate issuance, certificate duplication, certificate renewals, etc.).
localeoptionalstringLanguage that the DCV email should use. See Glossary – Locale codes.
renewal_of_order_idoptional*intIf order is a renewal, enter the previous order’s ID.
*Renewal orders must include either a renewed_thumbprint or renewal_of_order_id value.
payment_methodoptionalstringPayment method for the order. Allowed values:
credit_cardconditionalobjectObject with information about the credit card charged for the order. Required if payment_method is card.
.. numberrequiredstringCredit card number.
.. expiration_monthrequiredintegerCredit card expiration month. Format as a two-digit number between 01 (Jan) and 12 (Dec).
.. expiration_yearrequiredintegerCredit card expiration year. Format as a four-digit number. For example: 2026
.. cvvrequiredintegerCard verification value (CVV). Format as a three- or four-digit number. For example: 333 or 4444
.. cardholder_namerequiredstringCardholder’s first and last name.
billing_addressconditionalobjectObject with information about the billing address. Required if payment_method is card.
.. addressrequiredstringBilling street address.
.. address2optionalstringContinuation of street address.
.. cityrequiredstringBilling city.
.. stateconditionalstringBilling state or province. Optional for some countries.
.. countryrequiredstringBilling country.
.. zipconditionalstringBilling zip or postal code. Optional for some countries.
vat_numberoptionalstringIf the payment method is card (new credit card) or profile (default credit card), use the vat_number request parameter to set a value-added tax (VAT) or goods and services tax (GST) identification number for the order transaction. DigiCert includes this number on the transaction receipt as a reference for your financial records.
If omitted, DigiCert uses the VAT/GST number from the finance settings for the CertCentral account. If the VAT/GST number is absent from both the order request and account settings, DigiCert doesn’t store a VAT/GST number for the transaction.
Note
DigiCert only stores a VAT/GST number for credit card transactions. For orders using other payment methods, the vat_number request parameter is ignored.
VAT/GST numbers are not supported for DigiCert USA and DigiCert Japan billing entities. If the billing entity for the account is DigiCert, Inc. (US) or DigiCert Japan G.K. (Japan), the vat_number parameter is ignored, and DigiCert doesn’t store a VAT/GST number for the transaction. To learn more about your account’s billing entity, contact your account manager.
dcv_methodoptionalstringDCV method to use when verifying domain control. See Glossary – DCV methods.
To change the domain control validation (DCV) method, use the Change DCV method endpoint.
skip_approvaloptionalboolSpecify if the order should skip the approval step and be immediately submitted for validation and issued when complete.
Default:
false
organization_contactoptionalobjectOrganization contact for the order.
Include this object at the root of the request body to create the order with a different organization contact than the one assigned to the organization on the request. If omitted, the order uses the same organization contact assigned to the organization.
Note: The order-level organization_contact is only used on the order. It does not replace the organization contact assigned to the organization on the request.
.. first_namerequiredstringContact first name.
.. last_namerequiredstringContact last name.
.. emailrequiredstringContact email address.
.. job_titleoptionalstringContact job title.
.. telephoneoptionalstringContact telephone number.
.. telephone_extensionoptionalstringTelephone extension.
technical_contactoptionalobjectTechnical contact for the order.
Include this object at the root of the request body to create the order with a different technical contact than the one assigned to the organization on the request. If omitted, the order uses the same technical contact assigned to the organization.
Note: The order-level technical_contact is only used on the order. It does not replace the technical contact assigned to the organization on the request.
.. first_namerequiredstringContact first name.
.. last_namerequiredstringContact last name.
.. emailrequiredstringContact email address.
.. job_titleoptionalstringContact job title.
.. telephoneoptionalstringContact telephone number.
.. telephone_extensionoptionalstringTelephone extension.
organizationrequiredobjectObject with information about the organization to associate with the request. You can associate the request with an existing organization, or you can create a new organization when you submit the order request.
To associate the request with an existing organization, pass the ID of the organization as the value of organization.id in the body of your request. To create a new organization, include the details of the organization in the organization object. For more information about the structure and required parameters of the organization object, see the Create organization documentation.
Note: 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.
Important: 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.
.. idconditional*intThe ID of an existing organization to associate with the order. To get the ID of organizations in your account, use the List organizations endpoint.
*Requests that do not include organization details must include an organization ID.
.. skip_duplicate_org_checkoptionalboolUse true to skip the check for duplicate organizations in your account. When you skip this check, you force the request to create a new organization, regardless of whether the details you provide in the request match the details of an organization that already exists in your account.
Default: false
.. contactsconditionalarrayList of contacts for the organization.
When creating a new organization:
For CMC certificates, providing a verified_contact is required.
Providing an organization_contact is conditional. An organization_contact is required if the request is from a service user. If omitted, the organization is created and the authenticated user is used as the organization contact.
Providing a technical_contact is optional. If omitted, the organization is created with no technical contact.
When using an existing organization ID:
Providing an organization_contact and technical_contact is optional. If provided, the new organization and technical contact replace the existing contacts stored on the organization.
For CMC certificates, providing a verified_contact is optional if the organization has already been submitted for the corresponding validation type.
For CMC certificates, providing a verified_contact is required if the organization has never been submitted for the corresponding validation type.
Note: By default, DigiCert creates the order with the organization contact and technical contact (if one exists) assigned to the organization on the request. To create the order with a different organization or technical contact than those assigned to the organization, include the organization_contact or technical_contact object at the root of the request payload.
.. .. contact_typerequiredstringContact type.
Allowed values:organization_contact, technical_contact, verified_contact (formerly ev_approver*)
*Note: To identify a verified contact for the organization, use verified_contact instead of ev_approver. While the API still accepts order requests that use ev_approver to identify verified contacts, ev_approver is a legacy label chosen when the only DigiCert products that required verified contacts were EV TLS/SSL certificates. Both contact type labels (verified_contact and ev_approver) have the same meaning, but verified_contact uses generalized terminology applicable to every product that requires a verified contact.
.. .. user_idrequired*intID of existing user for the account.
*Can be omitted if adding a new contact.
.. .. first_nameoptionalstringFirst name of the new contact.
Note: Required when omitting user_id. If user_id is not omitted, the specified user’s information will be updated with the new value.
.. .. last_nameoptionalstringLast name of the new contact.
Note: Required when omitting user_id. If user_id is not omitted, the specified user’s information will be updated with the new value.
.. .. job_titleoptionalstringJob title of the new contact.
Note: Required when omitting user_id. If user_id is not omitted, the specified user’s information will be updated with the new value.
.. .. telephoneoptionalstringTelephone number of the new contact.
Note: Required when omitting user_id. If user_id is not omitted, the specified user’s information will be updated with the new value.
.. .. emailoptionalstringEmail address of the new contact.
Note: Required when omitting user_id. If user_id is not omitted, the specified user’s information will be updated with the new value.
containeroptionalobjectIf needed, specify the container the order should be placed under.
.. idrequiredintContainer ID.
custom_fieldsoptional*arrayAccount-specific custom fields.
*Whether or not these fields are required depends on your custom field settings.
.. metadata_idrequiredintCustom field ID.
.. valuerequiredstringValue for the custom field. Data validation type depends on your custom field settings.
alternative_order_idoptionalstringA custom alphanumeric ID to assign the order. To see the alternative_order_id assigned to an order, use the Order info endpoint.
Alternative order IDs do not replace the unique order ID that DigiCert assigns each order request. You cannot use alternative order IDs to search for or identify orders in API calls that require an order_id parameter in the URL path or request body.
If the Require unique alternative order IDs option is enabled in your account settings, you cannot submit order requests with an alternative order ID that is already assigned to an order in your account. Use this feature to enable nonce order requests, or to prevent your integration from creating duplicate orders in cases where you do not receive a response from the API. Account administrators can toggle this option from the CertCentral console. From the Settings > Preferences page, open the Advanced Settings menu, and look for the Alternative order ID option.
This parameter is always optional, even if the Require unique alternative order IDs option is enabled in your account. If a request does not use this parameter, no alternative_order_id value is assigned to the order.
Maximum length: 64 characters
Note: The Require unique alternative order IDs option may not appear in the advanced settings menu for all CertCentral accounts. To enable this option for your account, contact your account manager or our Support team.

Response parameters

NameTypeDescription
idintOrder ID.
domainsarrayList of objects with details about the domains in your account that are submitted for validation with the certificate order request. You must have an active validation for the domains in this array to prove you control the SANs on the order.
.. idintDomain ID of the domain in your account.
.. nameintName of the domain in your account.
.. dns_namestringA SAN from the order request. To prove you control this domain, you must have an active validation for the domain associated with the domains[].name and domains[].id key/value pairs.
.. dcv_tokenobjectObject with details about the domain control validation (DCV) token for the domain. Not returned when using email as the DCV method.
Note: The dcv_token object is not returned for domains that will be validated under the scope of another domain on the order, for domains that already exist in your account, or for subdomains of existing domains. For example, if you request a certificate to secure the newly created domains example.com, www.example.com, and subdomain.example.com, the response only includes a dcv_token object for example.com. To get the DCV token for an existing domain, use the Domain info endpoint.
.. .. tokenstringRandom value used to prove control over the domain.
.. .. statusstringStatus of the domain validation process.
.. .. expiration_datestringTimestamp of when the token will expire.
Format: UTC timezone and ISO 8601 date
.. .. verification_valuestringValue for the DNS record target host field.
Only returned if the DCV method is dns-cname-token.
.. .. http_token_urlstringFilename and location for the .txt file.
Only returned if the DCV method is http-token.
requestsarrayContains information about the request.
.. idintRequest ID.
.. statusstringRequest status.
Possible values: pending, submitted, approved, rejected
certificate_idintCertificate ID. Returned if request status is approved.
vmcobjectObject with CMC details.
.. logo_idintID of the CMC logo on the order. Only returned when the logo in the request matches an existing CMC logo. When the logo matches an existing logo, we use the existing logo for the order instead of uploading a duplicate image.