Skip to main content
Every publicly trusted TLS certificate is logged in certificate transparency logs. A certificate names the host it was issued for, so the logs show hosts under your domain that you may not track, and certificates issued for look-alikes of it. This source searches an index of those certificates. Both calls are synchronous: the certificates come back in the same response. Availability: SSL Certificate Monitoring, included in every edition. Cost: no metered allowance. With an API key, each call that returns 2xx uses 1 unit of your monthly API Calls allowance, and a non-2xx response is refunded. Every call also counts toward the per-second rate limit. See Rate limits. When your license is not active, both endpoints return 403:
certificate_database_search takes a query of 3 to 1,024 characters. The default field is domain, so a bare domain finds certificates issued for it and for every subdomain under it. You don’t need a leading *..
To limit by date, add a createdAt clause. The query language has two fields, domain and createdAt, and three operators, AND, OR and NOT. The query contains : and spaces, so let curl -G --data-urlencode encode it.

​
Request parameters

​
Narrow with risk filters

Set any of these query parameters to true to keep only the matching certificates.
onlyOwnDomain and excludeOwnDomain cannot both be true. Sending both returns 400:

​
What comes back

A page of certificates. The certificates are in content. The other fields describe the page.
  • content — the certificates on this page.
  • hasContent — true when this page holds at least one certificate.
  • number — the page index, starting at 0.
  • size — the page size used.
  • numberOfElements — certificates on this page.
  • totalElements — matching certificates across all pages.
  • totalPages — pages available at this size.
  • first / last — true on the first and the last page.
Each certificate carries:
  • id — the certificate’s ID, for certificate_detail.
  • domain — the host the certificate was issued for.
  • issuer — the certificate authority that signed it.
  • notBefore / notAfter — the start and end of its validity.
  • createdAt — the record’s date in the index, the field that createdAt: queries.
  • algorithm, fingerprint, serialNumber — the certificate’s signature algorithm, fingerprint and serial number.
  • cvssScore — a numeric score on the record, or null.
Timestamps use the format YYYY-MM-DD HH:MM:SS.

​
Reading the results

Compare each domain with the hosts your organization knows about:
  • A host you do not recognize under your domain, such as vpn-test.acme.com, can be an unlisted service or a forgotten test system.
  • A certificate for a look-alike means someone set up TLS on that name. Search the look-alike itself, for example query=acme-login.com, to list its certificates.
  • A notAfter in the past marks an expired certificate. The host may still answer.
  • An issuer you do not use shows a certificate obtained outside your usual provider.
To check whether a look-alike was registered recently, search it in New domain registrations. To check whether phishing feeds list it, use Phishing references.

​
Fetch one certificate

certificate_detail returns one certificate by the id from a search result. The path has no trailing slash.
The response is one certificate with the same fields as an item in content. An unknown id returns 404.

​
Monitor new certificates

To receive new certificates for a query without repeating the search, create a monitor on the Certificate service (3 in the service list) with your query as args, for example {"query": "acme.com"}. Read the service’s args_schema from the service list for the other parameters it takes. See Create and manage monitors.

​
Errors

​
Endpoints