# Certificate Analytics API (TCA-0503) — Spectra Intelligence

> Submit a certificate common name or partial name to TCA-0503 and receive matching common names with their associated MD5, SHA1, and SHA256 thumbprints.

# Certificate thumbprint search (TCA-0503)

This service provides a list of thumbprints (MD5, SHA1, SHA256) for certificates matching the requested common name or common name part.

## Certificate Search Query

The query returns common names matching the request, along with the list of thumbprints of all the certificates sharing that common name.

The common name in the request can contain a wildcard `*` which substitutes any subset of all possible characters. For retrieving the next page of the results, both of the pagination arguments should be provided in the request.

<Button title="View OpenAPI Specification" href="/SpectraIntelligence/API-reference/#tag/certificate-threat-intelligence/post/apicertificatesearchv1querysubjectpost_format" />

### Request

```
POST /api/certificate/search/v1/query/subject/{post_format}
```

Path parameters:

- `post_format`
  - allows choosing between XML and JSON format in the POST payload

#### Request body

``` json
{
  "rl": {
    "query": {
      "common_name": "string",
      "response_format": "string",
      "limit": 5,
      "page_common_name": "string",
      "page_thumbprint": "string"
    }
  }
}
```

- `common_name`
  - Common name can contain a wildcard '\*’ which substitutes any subset of all possible characters (for example, if we want all certificates with a common name that contains the word "Windows" we would type *Windows*. If we want all certificates with a common name that begins with the word "Windows", we would type Windows\*)
  - Required
- `limit`
  - Maximum number of certificate thumbprints to be returned. It is possible to choose a number between 1 and 100 (100 is used by default)
  - Optional
- `page_common_name`
  - An optional pagination parameter for retrieving the next page of the results. Pagination value for the next page is provided in the previous request response as `next_page_common_name`
  - Optional
- `page_thumbprint`
  - An optional pagination parameter for retrieving the next page of the results. Pagination value for the next page is provided in the previous request response as `next_page_thumbprint`
  - Optional
- `response_format`
  - Allows choosing between XML and JSON format for the response. Default is xml.
  - Optional

### Response

The query will return all common names matching the requested common name, along with the list of thumbprints of all the certificates sharing that common name.

```json
{
  "rl": {
    "next_page_common_name": "string",
    "search": [],
    "next_page_thumbprint": "string",
    "request": {}
  }
}
```

- `request`
  - **common_name**: requested common name; **response_format**: output format; **limit**: number of requested samples; **page_common_name**: requested page common name value; **page_thumbprint**: requested page thumbprint value
- `next_page_common_name`
  - Pagination value for retrieving the next page (if it exists)
- `next_page_thumbprint`
  - Pagination value for retrieving the next page (if it exists)
- `search`
  - **common_name**: common name matching the requested name; **thumbprints**: list of certificate thumbprints associated with the requested common name

## Examples

### Request

`/api/certificate/search/v1/query/subject/json`

```json
{
  "rl": {
    "query": {
      "common_name": "Microsoft",
      "response_format": "json",
      "limit": 5
    }
  }
}
```

### Response

<details>
<summary>Response</summary>

```json
{
  "rl": {
    "next_page_common_name": "Microsoft",
    "search": [
      {
        "common_name": "Microsoft",
        "thumbprints": [
          {
            "certificate_thumbprints": [
              {
                "name": "MD5",
                "value": "91888389aa2cac07c610f469e5f18092"
              },
              {
                "name": "SHA1",
                "value": "e8a53bed75c33d48cf49382ddba6b048e85072b2"
              },
              {
                "name": "SHA256",
                "value": "0AF958372FEDCFA29B8DD4C6DB83D44DC25AC6AD2435ACA5C0B08DCD5D596828"
              }
            ]
          },
          {
            "certificate_thumbprints": [
              {
                "name": "MD5",
                "value": "f971881e5219b17d98c181d50440d3d0"
              },
              {
                "name": "SHA1",
                "value": "b5d1c90c8e8036610094bb6182d6c3f7481cd9eb"
              },
              {
                "name": "SHA256",
                "value": "0F59B2A0809BE2B87728DCE7051C81FFD005A00CEA60FF1F0D7E11C911C8BBAB"
              }
            ]
          },
          {
            "certificate_thumbprints": [
              {
                "name": "MD5",
                "value": "2377666edb5a4d5656f68e002efb8415"
              },
              {
                "name": "SHA1",
                "value": "4f0333347b6f953b33966e976f24c5da36d75143"
              },
              {
                "name": "SHA256",
                "value": "18254B1DC375B74E339EB99ABFE31AF0D735CB5A3B535570731175811D735B0D"
              }
            ]
          },
          {
            "certificate_thumbprints": [
              {
                "name": "MD5",
                "value": "e0379a7291368975ffa2c8c10cb71fe7"
              },
              {
                "name": "SHA1",
                "value": "c8f9dd2174879e6d50def833c68338fe4227c26f"
              },
              {
                "name": "SHA256",
                "value": "0695208909EDBFD9AEBAAF712EEE1FC7916BC0F563475CDEE5E64F497D7563D0"
              }
            ]
          },
          {
            "certificate_thumbprints": [
              {
                "name": "MD5",
                "value": "2acdfc999c7b50813635718cfb0eea7f"
              },
              {
                "name": "SHA1",
                "value": "39c4da3d122c4bc9369928464377ead34878d4a6"
              },
              {
                "name": "SHA256",
                "value": "2606995A71C2128D6410DE8F1D7C199C5254F677FA44EA312C32A8B991F32C5F"
              }
            ]
          }
        ]
      }
    ],
    "next_page_thumbprint": "2606995A71C2128D6410DE8F1D7C199C5254F677FA44EA312C32A8B991F32C5F",
    "request": {
      "common_name": "Microsoft",
      "limit": 5,
      "response_format": "json"
    }
  }
}
```
</details>
