Check order DCV

PUT https://www.digicert.com/services/v2/order/certificate/{{order_id}}/check-dcv

Use this endpoint to check the domain control validation (DCV) for a pending TLS/SSL certificate order with a domain control validation (DCV) method of dns-txt-token, dns-cname-token, or http-token.

Notice

To check the DCV for an individual domain, use the Check domain DCV endpoint.

Note

Using this endpoint to check DCV does not reset or restart the polling interval for automatic domain control validation.

Response format

The response format depends on the DCV method and validation status of the checked domains.

DNS TXT and DNS CNAME

When the DCV method is DNS TXT (dns-txt-token) or DNS CNAME (dns-cname-token), the API returns JSON data with a list of dns_name_validations for each checked domain.

If you check DCV for the entire order (default), the API returns JSON data with a list of dns_name_validations for each domain that was submitted for validation.
If you use the dns_names_validations request parameter to check DCV for a subset of domains, the API returns JSON data with a list of dns_name_validations only for the checked domains.

HTTP Practical Demonstration

When the DCV method is HTTP Practical Demonstration (http-token), the API returns a 400 error if DigiCert cannot find the random value at the expected location for one or more checked domains.

Check DCV for all domains or subset	DigiCert finds token for all checked domains	DigiCert does not find tokens for one or more checked domains
All domains (default)	API returns JSON data with list of `dns_name_validations` for each domain on the order. { "order_status": "issued", "certificate_id": 249043544, "dcv_status": "valid", "dns_name_validations": [ { "dns_name": "example.com", "status": "approved" }, { "dns_name": "example.org", "status": "approved" } ] }	400 error: `file_random_value_not_found` { "errors": [ { "code": "file_random_value_not_found", "message": "Could not find the random value at the expected file location for one or more domains." } ] }
Subset of domains (`dns_name_validations` request parameter)	API returns JSON data with list of `dns_name_validations` for each domain in the request: { "order_status": "pending", "certificate_id": 249076909, "dcv_status": "valid", "dns_name_validations": [ { "dns_name": "example.com", "status": "approved" } ] } Note: If all domains are approved after you submit your request, the `order_status` returns `issued` instead of `pending`.	400 error: `file_random_value_not_found` { "errors": [ { "code": "file_random_value_not_found", "message": "Could not find the random value at the expected file location for one or more domains." } ] }

Check DCV for all domains or subset

DigiCert finds token for all checked domains

DigiCert does not find tokens for one or more checked domains

All domains (default)

API returns JSON data with list of dns_name_validations for each domain on the order.

{
  "order_status": "issued",
  "certificate_id": 249043544,
  "dcv_status": "valid",
  "dns_name_validations": [
    {
      "dns_name": "example.com",
      "status": "approved"
    },
    {
      "dns_name": "example.org",
      "status": "approved"
    }
  ]
}

400 error: file_random_value_not_found

{
  "errors": [
    {
      "code": "file_random_value_not_found",
      "message": "Could not find the random value at the expected file location for one or more domains."
    }
  ]
}

Subset of domains (dns_name_validations request parameter)

API returns JSON data with list of dns_name_validations for each domain in the request:

{
  "order_status": "pending",
  "certificate_id": 249076909,
  "dcv_status": "valid",
  "dns_name_validations": [
    {
      "dns_name": "example.com",
      "status": "approved"
    }
  ]
}

Note: If all domains are approved after you submit your request, the order_status returns issued instead of pending.

400 error: file_random_value_not_found

{
  "errors": [
    {
      "code": "file_random_value_not_found",
      "message": "Could not find the random value at the expected file location for one or more domains."
    }
  ]
}

Example requests and responses

Example 1. cURL (Check entire order)

curl --request PUT 'https://www.digicert.com/services/v2/order/certificate/{{order_id}}/check-dcv' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--header 'Content-Type: application/json'

Example 2. cURL (Check specific domains)

curl --request PUT 'https://www.digicert.com/services/v2/order/certificate/{{order_id}}/check-dcv' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "dns_name_validations": [
    {
      "dns_name": "example.com",
      "dcv_method": "dns-txt-token"
    }
  ]
}'

Example 3. 200 OK

{
  "order_status": "issued",
  "certificate_id": 249076999,
  "dcv_status": "valid",
  "dns_name_validations": [
    {
      "dns_name": "sub1.example.com",
      "status": "approved"
    },
    {
      "dns_name": "sub2.example.com",
      "status": "approved"
    }
    {
      "dns_name": "sub3.example.com",
      "status": "approved"
    }
  ]
}

Example 4. 400 Bad Request (file_random_value_not_found)

{
  "errors": [
    {
      "code": "file_random_value_not_found",
      "message": "Could not find the random value at the expected file location for one or more domains."
    }
  ]
}

Example 5. 400 Bad Request (invalid_dns_txt)

{
  "errors": [
    {
      "code": "invalid_dns_txt",
      "message": "Could not find a valid TXT record for one or more domains."
    }
  ]
}

Path parameters

Name	Req/Opt	Description
order_id	required	ID of the order to check. To check DCV, order `status` must be `pending`.

Request parameters

Name	Type	Req/Opt	Description
dns_name_validations	array of objects	optional	List of objects that specifies a subset of domains to check. Each object must include `dns_name` and `dcv_method` key/value pairs. If you omit this list, the API checks DCV for all domains you need to validate before DigiCert can issue the certificate.
.. dns_name	string	required	Domain name.
.. dcv_method	string	required	DCV method.

Response parameters

Note

If the DCV method is http-token and DigiCert cannot find the random value at the expected location for one or more checked domains, the API returns an 400 error instead this JSON response.

Name	Type	Description
order_status	string	Order status. Possible values: `pending`: DCV unapproved for one or more domains. `issued`: DCV approved for all domains.
certificate_id	integer	Certificate ID.
dcv_status	string	Order DCV status. Possible values: `pending`: DCV unapproved for all domains. `valid`: DCV approved for one or more domains.
dns_name_validations	array of objects	List of objects with DCV approval status for each checked domain.
.. dns_name	string	Domain name.
.. status	string	DCV approval status. Possible values:`approved` or `unapproved`

In this section: