REST API List Certificates

List Certificates GET

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

Note

In case you have more than 100 ACME certificates you need at least a ZeroSSL basic plan in order to work with those in Dashboard or API. In case you have more than 100K ACME certificates you need at least a ZeroSSL premium plan in order to work with those in Dashboard or API.

API Request URL:

api.zerossl.com/certificates

GET Request Parameters:

Parameter Description
access_key [Required] Use this parameter to specify your API access key.
certificate_status Use 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).
certificate_type Use this parameter to filter the results by certificate type (comma-separated values). You can either use the string representation or the integer code as value.
Value Description
single90Days / 1 Single-Domain 90-Day certificates
wildcard90Days / 2 Wildcard 90-Day certificates
multiDomain90Days / 3 Multi-Domain 90-Day certificates
single1Year / 4 Single-Domain annual certificates
wildcard1Year / 5 Wildcard annual certificates
multiDomain1Year / 6 Multi-Domain annual certificates
acme90Days / 7 ACME certificates
search Use this parameter to search for certificates having the given common name or SAN.

High volume limitation

If you have more than 1000 certificates: You must provide the exact common name of the certificate. SAN can not be searched at the moment (we are going to provide a solution for this use case in the future).
limit Use this parameter to specify a pagination limit (Default: 100).

High volume limitation

You may retrieve a maximum of 1000 certificates with one API call. If you have more results, you have to use the pagination (check total_count, result_count, page and limit from the response).
page Use 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 certificates.

{
    "total_count": 11,
    "result_count": 10,
    "page": 1,
    "limit": 10,
    "acmeUsageLevel": "LOW",
    "isAcmeLocked": false,
    "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": "",
            "fingerprint_sha1": null,
            "brand_validation": null,
            "signature_algorithm_properties": "sha384WithRSAEncryption:2048",
            "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"
                    }
                }
            },
            "last_updated": "2020-04-30 10:04:20",
            "ca_certificate_id": 1,
            "has_private_key": true
        },
        {...}
    ]
}

Response Objects:

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