REST API Verify Domains

Verify DomainsHTTP POST

In order for your certificate to be issued, all domains included in your certificate will need to be verified. There are four methods that can be used to verify domains: email verification, verification via DNS (CNAME), verification via HTTP file upload and verification via HTTPS file upload.

To initiate domain verification, you will need to make a request to the endpoint below carrying your API access key as well as some HTTP POST request parameters. Please note that {id} must be replaced with your certificate ID (hash).

API Request URL:

api.zerossl.com/certificates/{id}/challenges

HTTP GET Request Parameters:

Parameter Description
access_key access_key[Required] Use this parameter to specify your API access key.
{id} {id}[Required] Use this parameter to specify your certificate ID / hash.

HTTP POST Request Parameters:

Parameter Description
validation_method validation_method[Required] Use this parameter to specify the verification method to use for this certificate. Possible values: EMAIL (email verification), CNAME_CSR_HASH (CNAME verification), HTTP_CSR_HASH (HTTP file upload), HTTPS_CSR_HASH (HTTPS file upload)
validation_email validation_emailIf your selected verification method is Email Verification, use this parameter to specify one or multiple verification email addresses. You need to specify one verification email address per domain.
Verification Methods Please note that you can use the API endpoint above to re-initiate domain verification using the same or another verification method at any given time before the certificate is validated and issued.

Email Verification API Response

If you selected email verification and your API request was successful, you will receive a verification email to the selected verification email address for each of the domains in your certificate. In order for your certificate to be issued, you will need to follow the steps shown in these verification emails. If you are not sure about how to verify your domains via email, you can learn more about email verification here.

For as long as your domains remain unverified, the status of your certificate will be pending_validation. As soon as your domains have been verified and your certificate has been issued, the certificate status will be changed to issued automatically by our system.

Check Verification Status To check the email verification status of the domains in your certificate, you can use the API's Status endpoint.

CNAME / File Upload API Response

If the verification of your CNAME-records or uploaded files was successful, the ZeroSSL API will return your entire certificate object with status pending_validation. From this moment it will take just a few seconds (in some cases, up to 5-10 minutes) for our system to validate and issue your certificate. As soon as your certificate has been issued, the certificate status will change to issued automatically.

CNAME / File Upload Possible Errors

If the verification of some or all of your CNAME-records or uploaded files fails, the API will return an error object in JSON format outlining in detail whichn of the domains could be verified and which could not be verified.

You will find an example error response for CNAME verification below:

{
    "success": false,
    "error": {
        "code": 0,
        "type": "domain_control_validation_failed",
        "details": {
            "domain.com": {
                "domain.com": {
                    "cname_found": 0,
                    "record_correct": 0,
                    "target_host": "_2B449B729284AA7CB56014584F261FBF",
                    "target_record": "A1063BBA157D.686A709A3.4BAD7A.CA.COM",
                    "actual_record": ""
                },
                "www.domain.com": {
                    "cname_found": 0,
                    "record_correct": 0,
                    "target_host": "_2B449B729284AA7CB56014584F261FBF",
                    "target_record": "A1063BBA157D.686A709A3.4BAD7A.CA.COM",
                    "actual_record": ""
                }
            }
        }
    }
}

Response Objects:

Parameter Description
success access_keyReturns false to indicate that an API error occurred.
error errorReturns a sub-object containing error details.
code codeReturns a numeric error code uniquely associated with the specific error.
type typeReturns a text-based error key uniquely associated with the specific error.
details detailsReturns an object containing error details for each domain (or pair of www and non-www domains).
cname_found cname_foundReturns 1 or 0 depending on whether or not your CNAME-record was found.
record_correct record_correctReturns 1 or 0 depending on whether the CNAME-record found is correct.
target_host target_hostReturns the host-part (Name) of the required CNAME-record.
target_record target_recordReturns the value-part (Point To) of the required CNAME-record.
actual_record actual_recordReturns the value-part of the CNAME record found for the given domain.