REST API List Certificates

List CertificatesHTTP GET

To retrieve information about an existing certificate using the ZeroSSL API you will need to make an HTTP GET request to the API's certificates. You can use a series of GET parameters to specify certificate status, search and configure pagination.

API Request URL:

api.zerossl.com/certificates

HTTP GET Request Parameters:

Parameter Description
access_key access_key[Required] Use this parameter to specify your API access key.
certificate_status certificate_statusUse this parameter to specify one or multiple comma-separated certificate status values. Possible values: draft, pending_validation, issued, cancelled, revoked, expired.

You can also send the special status expiring_soon. In this case all issued certificates are included, which expire within the next 30 days and should be renewed (in paid ZeroSSL accounts those are not credited anymore).
search search Use this parameter to search for specific certificates using full-text search.
High volume limitation If you have more than 1000 certificates: We will only search for the common name and your search string must have at least 4 characters. Otherwise, the search string is ignored.
limit limitUse this parameter to specify a pagination limit (Default: 100).
High volume limitation You may retrieve a maximum of 10000 certificates with one API call. If you have more results, you have to use the pagination.
page pageUse this parameter to specify a pagination page. If not specified the default 1 is returned, otherwise a numeric string containing the number of the page.

API Response:

If your API request has been successful, you will receive a JSON API response containing all the details of your SSL certificate. For illustration purposes, you will find an example API response below.

{
    "total_count": 11,
    "result_count": 10,
    "page": 1,
    "limit": 10,
    "results": [
        {
            "id": "a856a39a1c3ad0s8asa606g37667d221",
            "type": "1",
            "common_name": "domain.com",
            "additional_domains": "www.domain.com",
            "created": "2020-04-29 09:04:19",
            "expires": "2020-07-28 00:00:00",
            "status": "draft",
            "validation_type": null,
            "validation_emails": null,
            "replacement_for": "",
            "validation": {
                "email_validation": {
                    "domain.com": [
                        "[email protected]",
                        "[email protected]",
                        "[email protected]",
                        "[email protected]",
                        "[email protected]"
                    ]
                },
                "other_methods": {
                    "domain.com": {
                        "file_validation_url_http": "http://domain.com/.well-known/pki-validation/2449B.txt",
                        "file_validation_url_https": "https://domain.com/.well-known/pki-validation/2449B.txt",
                        "file_validation_content": [
                            "2B449B722B449B729394793947",
                            "comodoca.com",
                            "4bad7360c7076ba"
                        ],
                        "cname_validation_p1": "2B449B7293947.domain.com",
                        "cname_validation_p2": "2B449B7293947.23DD7293947.11DD7293941.ca.com"
                    },
                    "www.domain.com": {
                        "file_validation_url_http": "http://www.domain.com/.well-known/pki-validation/2449B.txt",
                        "file_validation_url_https": "https://www.domain.com/.well-known/pki-validation/2449B.txt",   
                        "file_validation_content": [
                            "2B449B722B449B729394793947",
                            "comodoca.com",
                            "4bad7360c7076ba"
                        ],
                        "cname_validation_p1": "2B449B7293947.www.domain.com",
                        "cname_validation_p2": "2B449B7293947.23DD7293947.11DD7293941.ca.com"
                    }
                }
            }
        },
        {...}
    ]
}

Response Objects:

Parameter Description
total_count total_countReturns the total number of results found for your query.
result_count result_countReturns the number of results shown on the current page.
page pageReturns the current page number.
limit limitReturns the specified pagination page limit.
results resultsReturns an array of certificates. For detailed information about certificate response objects, please refer to the Get Certificate section.