Order X9 PKI for TLS

14 minute read

POST https://www.digicert.com/services/v2/order/certificate/x9_pki

Use this endpoint to request or renew an X9 PKI for TLS certificate. To renew a certificate, you must place the request from the same account used to order the original certificate.

Note

The DigiCert X9 PKI for TLS certificate is a flexible certificate that supports any type of public FQDN and IP address configuration. However, the X9 PKI for TLS certificate does not support wildcard domains (*.example.com). For more information, see Flex certificates.

You can only order certificates that are enabled for your CertCentral account:

To enable DigiCert’s X9 PKI for TLS certificate for your DigiCert CertCentral® account, contact your account manager or our DigiCert Support.
Use the Product list endpoint to get the list of products available for your account.

For more information, see DigiCert X9 PKI for TLS certificate.

Example requests and responses

cURL

curl -X POST \
  https://www.digicert.com/services/v2/order/certificate/x9_pki \
  -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>",
    "signature_hash": "sha256",
    "server_platform": {
      "id": 2
    },
    "key_usages": [
      "key_agreement_encipherment" 
    ],
    "extended_key_usages": [    
      "server_authentication",            
      "client_authentication"
    ]
  },
  "comments": "Certificate for app server.",
  "container": {
    "id": 334455
  },
  "auto_renew": 1,
  "custom_renewal_message": "Keep this renewed.",
  "organization": {
    "id": 123456,
    "contacts": [
      {
        "contact_type": "organization_contact",
        "user_id": 565611
      },
      {
        "contact_type": "technical_contact",
        "first_name": "Jill",
        "last_name": "Valentine",
        "job_title": "STAR Member",
        "telephone": "8017019600",
        "email": "jill.valentine@digicert.com"
      }
    ]
  },
  "order_validity": {
    "years": 1
  },
  "payment_method": "balance"
}'

{
  "id": 112233,
  "requests": [
    {
      "id": 113,
      "status": "pending"
    }
  ]
}

{
  "id": 112233,
  "requests": [
    {
      "id": 113,
      "status": "submitted"
    }
  ]
}

{
  "id": 112233,
  "requests": [
    {
      "id": 113,
      "status": "approved"
    }
  ],
  "domains": [
    {
      "id": 1469,
      "name": "example.com",
      "dns_name": "example.com"
    },
    {
      "id": 1469,
      "name": "example.com",
      "dns_name": "sub.example.com"
    },
    {
      "id": 1469,
      "name": "example.com",
      "dns_name": "app.example.com"
    }
  ],
  "certificate_id": 113
}

{
  "id": 112233,
  "domains": [
    {
      "id": 1469,
      "name": "example.com",
      "dns_name": "example.com"
    },
    {
      "id": 1469,
      "name": "example.com",
      "dns_name": "sub.example.com"
    },
    {
      "id": 1469,
      "name": "example.com",
      "dns_name": "app.example.com"
    }
  ],
  "certificate_id": 113
}

{
  "id": 112233,
  "domains": [
    {
      "id": 1469,
      "name": "example.com",
      "dns_name": "example.com"
    },
    {
      "id": 1469,
      "name": "example.com",
      "dns_name": "sub.example.com"
    },
    {
      "id": 1469,
      "name": "example.com",
      "dns_name": "app.example.com"
    }
  ],
  "certificate_id": 113,
  "certificate_chain": [
    {
      "subject_common_name": "example.com",
      "pem": "<pem_certificate>"
    },
    {
      "subject_common_name": "DigiCert SHA2 Secure Server CA",
      "pem": "<pem_certificate>"
    },
    {
      "subject_common_name": "DigiCert Global Root CA",
      "pem": "<pem_certificate>"
    }
  ]
}

Request parameters

Name	Req/Opt	Type	Description
certificate	required	object	Certificate details.
.. common_name	required	string	Domain to be secured.
.. dns_names	optional	array	Additional domains to be secured. Can result in additional costs. (See Best practices – Get both versions of a domain for free.)
.. csr	required	string	Certificate signing request (CSR) or public key in PEM format. Format the CSR/public key as a base64-encoded string without line breaks or escape characters. Include the PEM headers and footers (such as `-----BEGIN CERTIFICATE REQUEST-----...` and `...-----END CERTIFICATE REQUEST-----`). For more information about generating a CSR, see Create a CSR. After placing the order, if the status of the order is `pending`, you can use the Update CSR endpoint to update the CSR. To check the status of the order, use the Order validation status endpoint. Note: The Services API does not extract information from the CSR to fill in the details of a certificate request.
.. signature_hash	required	string	Hash algorithm used to signing the certificate. Default: `sha-256` Allowed values:: `sha256`, `sha384`, `sha512`.
.. server_platform	optional	object	Server platform type. Default: -1 (other)
.. .. id	required	int	Server platform ID. See Glossary – Server platforms.
comments	optional	string	Comments 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.
container	optional	object	If needed, specify the container the order should be placed under.
.. id	required	int	Container ID.
auto_renew	optional	int	Specify if the certificate should automatically renew. Allowed values:0 (disabled), 1 (enabled) Default: 0
custom_renewal_message	optional	string	Custom message to be included in renewal notifications.
renewal_of_order_id	optional^*	int	If order is a renewal, enter the previous order’s ID. *Renewal orders must include either a renewed_thumbprint or renewal_of_order_id value.
.. key_usages	optional	array	Specify the key usages (KUs) to include in your X9 PKI for TLS certificate. Allowed values:digital_signature , key_agreement_encipherment Default: digital_signature The explanation for the KUs are:
.. extended_key_usages	optional	array	Specify the Extended Key Usages (EKUs) to include in your X9 PKI for TLS certificate. Allowed values: server_authentication, client_authentication, or both Default: server_authentication and client_authentication The explanation for the EKUs are:
.. ca_cert_id	optional	string	ID of the intermediate certificate authority (ICA) certificate to select as the issuing certificate. To get the `ca_cert_id` value for an ICA, use the Product list endpoint. Account administrators can customize the default and allowed ICAs for each product at the container or user role level. If you do not provide a value for this parameter, we issue the certificate using the default ICA. If you provide the `ca_cert_id` value for an ICA that is not allowed, the request returns an error^. To see the custom ICA settings for each product, use the Product limits endpoint. This parameter is ignored if the option for ICA selection is not enabled for your account. Learn more about the ICA certificate chain feature for your public TLS certificates.
renewed_thumbprint	optional^*	string	If 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.
csa_agreed_to	required	boolean	Specify if the Certificate Subscriber Agreement (CSA) has been agreed to. Set this parameter to `true` to indicate agreement and `false` for disagreement. Default: true Allowed values: true or false.
promo_code	optional	string	Promotional code for the order.
dcv_method	optional	string	DCV method to use when verifying domain control. See Glossary – DCV methods.
certificate_dcv_scope	optional	string	Domain validation scope for domains on the order. Domain validation scope determines the specific domains that you must validate before DigiCert can issue your certificate.
Allowed values:
base_domain: Validate each domain and subdomain in the request at the base domain level (for example, example.com).
fqdn: Validate each domain and subdomain included in the order exactly as named in the request. When using fqdn:
If a domain is a subdomain of another domain included on the order, complete the DCV check for the higher-level domain.
For OV and EV certificates only, if a higher-level domain exists in the account with an active validation, we validate the domain under the scope of the existing domain.
Default: This parameter overrides the domain validation scope settings for your CertCentral account. If you omit this parameter, the account setting is used.
skip_approval	optional	bool	Specify if the order should skip the approval step and be immediately submitted for validation and issued when complete. Default:
false
additional_emails	optional	array	Additional email addresses to receive certificate notification emails (e.g., certificate issuance, duplicate certificate, certificate renewals, etc.).
locale	optional	string	Language that the DCV email should use. See Glossary – Locale codes.
organization	required	object	Object 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.
.. id	required^*	int	The ID of an existing organization to associate with the order. To get the ID of organizations in your account, use the List organizations endpoint. *Not required if you are creating a new organization with your request.
.. contacts	conditional	array	List of contacts for the organization.
When creating a new organization:
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.
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.
For more information about about updating contacts, see .
.. .. contact_type	required	string	Contact type.
Allowed values: organization_contact, technical_contact, or verified_contact.
.. .. user_id	required^*	int	ID of existing user or contact for the account. *Can be omitted if adding a new contact.
.. .. first_name	optional	string	First 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_name	optional	string	Last 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_title	optional	string	Job 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.
.. .. telephone	optional	string	Telephone 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.
.. .. email	optional	string	Email 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.
organization_contact	optional	object	Organization 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_name	required	string	Contact first name.
.. last_name	required	string	Contact last name.
.. email	required	string	Contact email address.
.. job_title	optional	string	Contact job title.
.. telephone	optional	string	Contact telephone number.
technical_contact	optional	object	Technical 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_name	required	string	Contact first name.
.. last_name	required	string	Contact last name.
.. email	required	string	Contact email address.
.. job_title	optional	string	Contact job title.
.. telephone	optional	string	Contact telephone number.
order_validity	required	object	Defines the validity period of the order.
.. years	required^*	int	Number of years the order is valid. Max: 1
.. days	optional	int	Number of days the order is valid. Overrides order_validity.years. Max: 397
.. custom_expiration_date	optional	string	Custom expiration date for the order. Overrides order_validity.days and order_validity.years. Format: dd MMM YYYY (for example, “09 JUN 2025”) Range: Must be within 397 days of the date you request the order.
payment_method	optional	string	Payment method for the order. Allowed values:
credit_card	conditional	object	Object with information about the credit card charged for the order. Required if `payment_method` is `card`.
.. number	required	string	Credit card number.
.. expiration_month	required	integer	Credit card expiration month. Format as a two-digit number between `01` (Jan) and `12` (Dec).
.. expiration_year	required	integer	Credit card expiration year. Format as a four-digit number. For example: `2026`
.. cvv	required	integer	Card verification value (CVV). Format as a three- or four-digit number. For example: `333` or `4444`
.. cardholder_name	required	string	Cardholder’s first and last name.
billing_address	conditional	object	Object with information about the billing address. Required if `payment_method` is `card`.
.. address	required	string	Billing street address.
.. address2	optional	string	Continuation of street address.
.. city	required	string	Billing city.
.. state	conditional	string	Billing state or province. Optional for some countries.
.. country	required	string	Billing country.
.. zip	conditional	string	Billing zip or postal code. Optional for some countries.
vat_number	optional	string	If 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.

Response parameters

Name	Type	Description
id	int	Order ID.
dcv_random_value	string	Random value used for domain control validation (DCV). Only returned when using `dns-txt-token`, `dns-cname-token`, or `http-token` as the DCV method.
organization	object	Container for new organization details. Only returned if a new organization was created with the order.
.. id	int	Organization ID for the new organization.
domains	array	List of objects with details about the domains that are submitted for validation with the certificate order request. You must validate these domains to prove you control the common name and each SAN on the order.
.. id	int	Domain ID of the domain in your account.
.. name	int	Name of the domain in your account.
.. dns_name	string	Common name or SAN on the order. To prove you control this common name or SAN, you must validate the domain associated with the `domains[].name` and `domains[].id` key/value pairs.
.. dcv_token	object	Object with details about the DCV random value. Each domain returns the same order random value, and you can use this value to complete the DCV check for any domain submitted for validation with the order. Only returned when using a DCV method of `dns-txt-token`, `dns-cname-token`, or `http-token`.
.. .. token	string	DCV random value.
.. .. status	string	Status of the domain validation process.
.. .. expiration_date	string	Timestamp of when the token will expire. Format: UTC timezone and ISO 8601 date
.. .. verification_value	string	Value for the DNS record target host field. Only returned if the DCV method is dns-cname-token.
.. .. http_token_url	string	Filename and location for the .txt file. Only returned if the DCV method is http-token.
requests	array	Contains information about the request.
.. id	int	Request ID.
.. status	string	Request status. Possible values: pending, submitted, approved, rejected
certificate_id	int	Certificate ID. Returned if request status is approved.
certificate_chain	array	Ordered list of objects with information about each certificate in the certificate chain (for example, SSL certificate, intermediate CA certificate, and root certificate). The first object in the array contains the end-entity certificate. The next objects contain the intermediate CA certificates. The final object contains the root certificate. Each certificate is signed by the certificate in the object that follows it. For example, the end-entity certificate is signed by the intermediate CA certificate. ** Note:** This endpoint only returns the `certificate_chain` array for TLS certificates that DigiCert issues immediately. To get the certificate chain after DigiCert issues a certificate, use the Certificate chain endpoint.
.. subject_common_name	string	Common name on the certificate.
.. pem	string	PEM-encoded certificate data. Note: The `pem` response parameter includes newline characters `\r\n`, which are an inherent part of PEM-encoded certificates.