DV SSL: Check 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 DV certificate order with a DCV method of dns-txt-token, dns-cname-token, or http-token.

To check the DCV for a pending domain submitted for prevalidation or as part of an OV/EV certificate order request, use the OV/EV SSL: Check DCV endpoint.

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

Example requests and responses

cURL (Check all domains)
curl -X PUT \
  'https://www.digicert.com/services/v2/order/certificate/{{order_id}}/check-dcv' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}'
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"
    }
  ]
}'
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"
    }
  ]
}
400 (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."
    }
  ]
}
400 (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
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

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