Certificate Transparency Search APIv1


When a publicly-trusted certificate is issued, it can result in a certificate, a precertificate, or both being logged to multiple Certificate Transparency logs. SSLMate monitors public Certificate Transparency logs, coalescing all the certificates and precertificates for a particular issuance event into a single issuance object. SSLMate indexes the issuances by DNS name, and you can use the API described below to efficiently query all the issuances for a particular domain, and then poll for new issuances. Learn more

List issuances

GET https://api.certspotter.com/v1/issuances?domain=DOMAIN

The following parameters may be specified in the query string:


Return issuances that are valid for the given DNS name, which must be a registered domain or subordinate to a registered domain. For example, www.example.com and example.com are valid, but com is not.

Omit this parameter to return all known issuances (requires subscribing to Firehose Access).

include_subdomains Also include issuances that are valid for sub-domains (of any depth) of domain. true or false. Default: false.
match_wildcards Also include issuances for wildcard DNS names that match domain. For example, a request for domain=www.example.com&match_wildcards=true will return issuances for *.example.com. true or false. Default: false.

Return issuances that were discovered by SSLMate since the issuance with the specified ID.

If after is not specified, then the behavior depends on the tail parameter, described below.


Controls the behavior when the after parameter is omitted.

If tail is false (the default), then the API returns issuances discovered since the beginning of time. This is useful if you are interested in reliably discovering all valid issuances matching your query.

If tail is true, then the API only returns a single page of the most recently-discovered issuances. This is useful if you are only interested in recent issuances.

It is an error to specify both the after and tail parameters.

expand Include the given field in the response, as described below. Repeat this parameter to expand multiple fields.

Response: JSON array of issuance objects, in the order that they were discovered by SSLMate.

Issuance Object

An issuance is represented by a JSON object with the following fields:

id string An opaque identifier which represents this issuance object.
tbs_sha256 string The hex-encoded SHA-256 digest of the TBSCertificate, as defined in RFC 6962 Section 3.2.
dns_names array of strings DNS names for which the issuance is valid, taken from both the DNS subject alternative names (SANs) and the subject common name (CN). Internationalized domain names are encoded in Punycode. Only present if expanded.
pubkey_sha256 string The hex-encoded SHA-256 digest of the Subject Public Key Info.
issuer issuer object Information about the issuer. Only present if expanded.
not_before string The not before date, in RFC 3339 format (e.g. 2016-06-16T00:00:00Z).
not_after string The not after (expiration) date, in RFC 3339 format (e.g. 2016-06-16T00:00:00Z).
cert certificate object Information about the certificate (if known) or precertificate (if certificate not known) corresponding to this issuance. Only present if expanded.

Certificate Object

A certificate or precertificate is represented by a JSON object with the following fields:

type string cert or precert.
sha256 string The hex-encoded SHA-256 digest of the X.509 (pre-)certificate, encoded in ASN.1 DER.
data string The base64 representation of the X.509 (pre-)certificate, encoded in ASN.1 DER.

Issuer Object

An issuer is represented by a JSON object with the following fields:

name string The subject distinguished name of the issuer, formatted according to RFC 2253.
pubkey_sha256 string The hex-encoded SHA-256 digest of the issuer's Subject Public Key Info.

Example Issuance (with all fields expanded)

{ "id":"23527804", "tbs_sha256":"e94af5279c0b9253bcefca8e65b9e0de5cb3be25855c73bccdcff81701b8a2e6", "dns_names":["*.example.com","example.com"], "pubkey_sha256":"9bc7338cde39136a1fcfda35887cec3b278d2e72f6e360ca791a544321aeedef", "issuer":{"name":"C=US, O=\"thawte, Inc.\", CN=thawte SSL CA - G2","pubkey_sha256":"691e8352a37ca8ae07406841a5c0cb56791102f3871f56de8694145355e5edf1"}, "not_before":"2016-07-14T00:00:00Z", "not_after":"2018-07-14T23:59:59Z", "cert":{"type":"precert","sha256":"94482136a1400bc3a1136feca3e79d4d200e03dd20b245d19f0e78b5679eaf48","data":"MIIEzjCCA7agAwIBAgIQEobGqV5B2WhzJt1o7kIUFjANBgkqhkiG9w0BAQsFADBBMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMdGhhd3RlLCBJbmMuMRswGQYDVQQDExJ0aGF3dGUgU1NMIENBIC0gRzIwHhcNMTYwNzE0MDAwMDAwWhcNMTgwNzE0MjM1OTU5WjBwMQswCQYDVQQGEwJLUjEOMAwGA1UECAwFU2VvdWwxEjAQBgNVBAcMCVNlb2Noby1ndTESMBAGA1UECgwJQ3Jvc3NjZXJ0MREwDwYDVQQLDAhWQ1MgdGVzdDEWMBQGA1UEAwwNKi5leGFtcGxlLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMFDRD/iURNGYWDu1A4aQKMP5X/QbehylISxE0aF4mzNfT0xdl1owpxotOPSP8wqy77WNuHXIckYS/4SxNX9f3aJ/5cBFQIqRvJzyB7Mv48EtTk00w5/1b53xFpqptJFkandcN4dIZHRfMGR9l1+mj4tTxEaSuEGl7z4Rdvq2L3Q0YeMdNScqLQ0MbS5khmPHP+eZM8wajtZ5HE7/TjDOU+0pNmnwyrUBNIZ9PpC0oJmzSSEjEF8qyQZc7VIqkjAPVLlyw/vf1j/1rPOGkfV0wAQoMkFSSQtOVuxT7+nakhv8kS0O/8fTtQ7MWRusq8fWaX8fpBgEPI6XNRJzC04scsCAwEAAaOCAZEwggGNMCUGA1UdEQQeMByCDSouZXhhbXBsZS5jb22CC2V4YW1wbGUuY29tMAkGA1UdEwQCMAAwbgYDVR0gBGcwZTBjBgZngQwBAgIwWTAmBggrBgEFBQcCARYaaHR0cHM6Ly93d3cudGhhd3RlLmNvbS9jcHMwLwYIKwYBBQUHAgIwIwwhaHR0cHM6Ly93d3cudGhhd3RlLmNvbS9yZXBvc2l0b3J5MA4GA1UdDwEB/wQEAwIFoDAfBgNVHSMEGDAWgBTCT0hX/NFPmsBdOH0OBdvZLrVSYDArBgNVHR8EJDAiMCCgHqAchhpodHRwOi8vdGouc3ltY2IuY29tL3RqLmNybDAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwVwYIKwYBBQUHAQEESzBJMB8GCCsGAQUFBzABhhNodHRwOi8vdGouc3ltY2QuY29tMCYGCCsGAQUFBzAChhpodHRwOi8vdGouc3ltY2IuY29tL3RqLmNydDATBgorBgEEAdZ5AgQDAQH/BAIFADANBgkqhkiG9w0BAQsFAAOCAQEAWr/m0cGFDRcuKcvpH/tWXDIpwWZGgE0AhaZQtAcU1O5X8j1k48kibWagjfLo84aUjiQyEhFN8O15t/B4QI9KlvtRCKbkKB/EUgzDK4wMUlxbWeJ080c2unVr3EoF5ZaSl1wsi9bdTTpLm1pFXK/ssi6v59p4iMDH7Cvsae86H8DoZbEB6Pii5wYzIvElq6JEm6rlnO4KYuoGshjYTkeByN1azQBEqAKBgVaQIRQ3pW7o5MJXoC+OheEwpjUbnjWMXFhrSjdU6yCWdUJNDSfvTGLjRjI/8hcJ8DNEV6/1mZjAAWP/yQWhOOOw69Z0b5nCgWckHP/+cSHzuliQ6GaeVg=="} }

Expanding Object Fields

As indicated in the documentation for an object, certain object fields are not included in responses by default. To include such a field, you must specify the field name in the request's expand parameter. This parameter can be specified more than once to expand multiple fields.

Example: GET https://api.certspotter.com/v1/issuances?domain=example.com&expand=dns_names&expand=issuer

Issuance Pagination

The API returns a limited number of issuances in a single response. To retrieve additional issuances, take the id field of the last issuance and pass it to the issuances endpoint in the after parameter (leaving the other parameters as-is). Repeat until the issuances endpoint returns an empty array.

Polling For New Issuances

When the issuances endpoint returns an empty array, it includes a Retry-After HTTP header containing a number of seconds. After the specified time has elapsed, you may retry the request. If SSLMate has discovered new issuances matching your query, they will be returned. You can then request subsequent pages until another empty response is returned.


You can make a limited number of unauthenticated API queries per hour, for personal or evaluation purposes.

When you're ready to launch in production, we ask that you sign up for an account and authenticate to the API using one the following methods:

Your API key can be found on your account page.


curl -H "Authorization: Bearer 123_sampleapikey" https://api.certspotter.com/v1/issuances?domain=example.com

curl -u 123_sampleapikey: https://api.certspotter.com/v1/issuances?domain=example.com

Provisioned Indexes

Provisioned indexes speed up full-domain queries of domains which have a large number of certificates. Provisioned indexes start at $100/month per domain. Contact us to set up a provisioned index.


SSLMate may make backwards-compatible changes to this API, such as adding new endpoints, adding new fields to responses, or adding new optional parameters to requests.

Backwards-incompatible changes will be avoided if at all possible, but should such a change become necessary, SSLMate will strive to provide at least 12 months notice. To ensure you receive notice, please use your API key when making requests.

See Also

Sign up for an API key