# Domain-to-IP Resolution API (TCA-0405) — Spectra Intelligence

> Query TCA-0405 for domain reports with reputation, DNS records, certificates, related URLs, and subdomains from Spectra Intelligence.

This service returns threat intelligence data for the submitted domain name. The reports contain domain reputation from various reputation sources, the maliciousness of files found on the submitted domain, and other metadata like last DNS records, related URLs, and related domains (subdomains, siblings).

Information about the hosted files, last DNS records, related URLs, and domains comes from our internal databases and URLs submitted for analysis using the TCA-0404 Analyze URL service.

### Privacy and Data Handling

Domains submitted for analysis using [TCA-0404 Analyze URL](/SpectraIntelligence/API/NetworkThreatIntel/tca-0404) are treated as public data and accessible to all Spectra Intelligence users.

For other queries (such as retrieving threat intelligence without submitting for analysis), information may be shared with third-party reputation sources as part of the lookup process. For comprehensive privacy considerations and best practices when using networking APIs, see [Privacy & Data Sharing](/General/SecurityAndAccessControl/Privacy#urls).

---

Users can send requests to the following endpoints:

[**Domain report**](#domain-report) and [**Domain bulk report**](#domain-bulk-report)

These endpoints return:

- Third-party domain reputation and categorization
- Counters of samples downloaded from the domain, mapped to their classification status (malicious, suspicious, known, unknown)
- The most common threats (malware type, family) found on the domain
- Last DNS records
- Parent domain information

[**Downloaded files endpoint**](#domain-downloaded-files)

Provides a list of hashes and classifications for files downloaded from the submitted domain.

The results can be filtered to return samples with specific classifications. If requested, the endpoint can return extended metadata for each file.

Extended records contain:

- Additional sample properties: SHA1 hash, MD5 hash, SHA256 hash, sample size, sample type, download availability of the sample, first and last seen dates, first and last download times, last download URL.
- Sample reputation information: classification, threat level, trust factor, malware family name, malware type, threat name, targeted platform and subplatform.

[**Related domains endpoint**](#domain-related-domains)

A list of all subdomains that exist under the top parent domain of the submitted domain. For example, if a request is made with emails.azure.microsoft.com, a list of all subdomains under the top parent domain (microsoft.com) will be provided.

[**Related URLs endpoint**](#domain-urls)

Returns a list of URLs hosted on the submitted domain.

[**Resolutions endpoint**](#domain-resolutions)

Provides a list of a domain-to-IP mappings.

**This API is rate limited to 5 requests per second.**

## Domain report

This service returns threat intelligence data for the submitted domain. The report contains domain reputation from various reputation sources, classification statistics for files downloaded from the domain, the most common threats found on the domain DNS information about the domain, and parent domain information.

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

### Request

```
POST /api/networking/domain/report/v1/query/{format}
```

#### Path parameters

- `format`
  - Defines the POST body format. Supported values: `xml` and `json`.
  - Required

#### Request body

``` json
{
  "rl": {
    "query": {
      "domain": "string",
      "response_format": "string"
    }
  }
}
```

- `domain`
  - The domain for which to retrieve the report.
  - Required
- `response_format`
  - Defines the response format. Supported values: `xml` and `json`.
  - Optional

### Response

The returned report contains third party domain reputation and statistics, counters of downloaded samples mapped to their classification status (malicious, suspicious, known, unknown), the most common threats found on the domain, latest DNS records for the domain with the last change time, and last change time of any of the listed elements.

Third party reputation data will always be present in the response, while other report sections might not.

```json
{
  "rl": {
    "requested_domain": {},
    "third_party_reputations": {},
    "downloaded_files_statistics": {},
    "parent_domain": "string",
    "last_dns_records": [],
    "top_threats": [],
    "last_dns_records_time": "string",
    "first_seen": "string",
    "last_seen": "string",
    "certificates": {},
    "modified_time": {}
  }
}
```

- `third_party_reputations`
  - Third party reputation data
- `parent_domain`
  - TLD of the submitted domain
  - only returned for domains which are not TLD
- `requested_domain`
  - The submitted domain
- `top_threats`
  - Top 5 threats found on the domain
- `last_dns_records_time`
  - last change time in DNS resolutions
- `first_seen`
  - The first time when the requested domain was recorded in the ReversingLabs collection. This can be the first time when we checked the domain reputation against third-party sources, the first time we obtained metadata for the requested domain from ReversingLabs static/dynamic file processing services (related files), or the first time we analyzed a URL containing this domain.
- `last_seen`
  - The last time when the requested domain received an indicator that updated its report. This can be the last time when we checked the domain reputation against third-party sources, the last time we obtained metadata for the requested domain from ReversingLabs static/dynamic file processing services (related files), or the last time we analyzed a URL containing this domain.
- `certificates`
  - An object containing information about the SSL/TLS certificates associated with the requested domain, listed by port number (e.g., `443`). Each certificate entry includes metadata such as validity dates, version, signature algorithm, issuer, common name, serial number, thumbprints (MD5, SHA1, SHA256), and a list of certificate extensions with their criticality and values.
- `modified_time` (deprecated)
  - Same as `last_seen`

----------------------------------------------------------------------

`rl.third_party_reputations.statistics`

```json
{
  "malicious": 0,
  "suspicious": 0,
  "clean": 0,
  "undetected": 0,
  "total": 0
}
```

- `total`
  - The total number of consulted domain reputation sources
- `malicious`
  - The number of sources that consider the domain malicious
- `suspicious`
  - The number of sources that consider the domain suspicious
- `clean`
  - The number of sources that consider the domain clean
- `undetected`
  - The number of sources that do not have information about the domain

----------------------------------------------------------------------

`rl.third_party_reputations.sources[]`

```json
{
  "source": "string",
  "update_time": "string",
  "detection": "string",
  "detect_time": "string",
  "categories": [
    "string"
  ]
}
```

- `source`
  - Name of the third party source
- `detection`
  - Detection for the submitted domain. The possible values are **malicious/suspicious/clean/undetected**. If the source does not have any information about the domain, the value will be undetected.
- `categories`
  - Domain categorization according to the source, e.g. phishing. Not all sources provide categorization information.
- `update_time`
  - Time when the information from the source was last updated
- `detect_time`
  - Time when the domain was last detected or given a category by the source.

----------------------------------------------------------------------

`rl.downloaded_files_statistics`

```json
{
  "unknown": 0,
  "known": 0,
  "suspicious": 0,
  "malicious": 0,
  "total": 0
}
```

- `total`
  - The total number of files downloaded from the domain
- `known`
  - The number of files classified as KNOWN
- `suspicious`
  - The number of files classified as SUSPICIOUS
- `malicious`
  - The number of files classified as MALICIOUS
- `unknown`
  - The number of files without classification

----------------------------------------------------------------------

`rl.certificates[]`

```json
{
  "valid_from": "string",
  "valid_to": "string",
  "version": "string",
  "signature_algorithm": "string",
  "signature": "string",
  "serial_number": "string",
  "common_name": "string",
  "issuer": "string",
  "certificate_thumbprints": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "extensions": [
    {
      "is_critical": "string",
      "name": "string",
      "value": "string"
    }
  ]
}
```

- `valid_from`
  - Start date of the certificate’s validity.
- `valid_to`
  - Expiration date of the certificate.
- `version`
  - X.509 version of the certificate.
- `signature_algorithm`
  - Algorithm used to sign the certificate.
- `signature`
  - The digital signature for the certificate.
- `serial_number`
  - Serial number of the certificate.
- `common_name`
  - Common Name (CN) for which the certificate is issued.
- `issuer`
  - Name of the Certificate Authority that issued the certificate.
- `certificate_thumbprints[]`
  - An array of thumbprints for the certificate in MD5, SHA1, and SHA256 formats.
    - `name`: Hashing algorithm used.
    - `value`: The thumbprint value.
- `extensions[]`
  - X.509 certificate extensions.
    - `is_critical:` Indicates if the extension is marked critical.
    - `name`: Name of the extension.
    - `value`: Extension value content.

----------------------------------------------------------------------

`rl.top_threats[]`

```json
{
  "threat_name": "string",
  "threat_level": 0,
  "files_count": 0
}
```

- `threat_name`
  - Name of the specific threat that was found
- `threat_level`
  - Threat level based on threat_name
- `files_count`
  - The number of files classified as that threat

----------------------------------------------------------------------

`rl.last_dns_records`

```json
{
  "type": "string",
  "value": "string",
  "provider": "string"
}
```

- `type`
  - Type of DNS resolution.
- `value`
  - resolution value (IP)
- `provider`
  - Source of resolution information

----------------------------------------------------------------------

### Examples

#### Retrieve a report (JSON)

Retrieving a domain report in JSON format, using a JSON POST body

```
/api/networking/domain/report/v1/query/json
```

``` json
{
  "rl": {
    "query": {
      "domain": "www.stemalservice.it",
      "response_format": "json"
    }
  }
}
```

#### Retrieve a report (JSON) for domain with no files

Retrieving a domain report in JSON format, using a JSON POST body. The submitted domain has no files associated with it, but third party detections exist.

```
/api/networking/domain/report/v1/query/json
```

``` json
{
  "rl": {
    "query": {
      "domain": "mail.chat.whatsapp.sange.getsviip7.com",
      "response_format": "json"
    }
  }
}
```

## Domain bulk report

This service returns threat intelligence data for the submitted domains. The report for each contains domain reputation from various reputation sources, classification statistics for files downloaded from the domain, the most common threats found on the domain DNS information about the domain, and parent domain information. The limit is 100 domains per request.

### Request

```
POST /api/networking/domain/report/v1/bulk_query/{format}
```

Path parameters:

- `format`
  - Defines the POST body format. Supported values: `xml` and `json`.
  - Required

Request body:

``` json
{
  "rl": {
    "query": {
      "domains": [
        "string"
      ],
      "response_format": "string"
    }
  }
}
```

- `domains`
  - The domains for which to retrieve the report. The limit is 100 domains per request.
  - Required
- `response_format`
  - Defines the response format. Supported values: `xml` and `json`.
  - Optional

### Response

```json
{
  "rl": {
    "entries": [
      {
        "requested_domain": {},
        "third_party_reputations": {},
        "downloaded_files_statistics": {},
        "parent_domain": "string",
        "last_dns_records": [],
        "top_threats": [],
        "last_seen": "string",
        "certificates": {},
      }
    ]
  }
}
```

## Domain downloaded files

### Request

```
POST /api/networking/domain/downloaded_files/v1/query/{format}
```

Path parameters:

- `format`
  - Defines the POST body format. Supported values: `xml` and `json`.
  - Required

Request body:

``` json
{
  "rl": {
    "query": {
      "domain": "string",
      "response_format": "string",
      "limit": 3,
      "extended": "string",
      "classification": "string"
    }
  }
}
```

- `domain`
  - The domain for which to retrieve a list of files.
  - Required
- `response_format`
  - Defines the POST body format. Supported values: `xml` and `json`.
  - Optional
- `limit`
  - The number of files to return in the response. Default value: **1000**
  - Optional
- `extended`
  - Allows choosing between `true` - extended, and `false` - non-extended data set (default)
  - Optional
- `classification`
  - If this parameter is provided in the request, the response will contain only samples that match the requested classification. Supported values are: `KNOWN`, `SUSPICIOUS`, `MALICIOUS`, `UNKNOWN`
  - Optional

### Response

The response will contain metadata for files downloaded from the submitted domain. Empty fields are not included in the response.

```json
{
  "rl": {
    "next_page": "string",
    "requested_domain": "string",
    "downloaded_files": []
  }
}
```

- `next_page`
  - This value can be used with the `page` parameter in the next request to retrieve the next page of records
- `requested_domain`
  - The submitted domain
- `downloaded_files`
  - A list of files and their metadata

----------------------------------------------------------------------

`rl.downloaded_files[]`

```json
{
  "first_download": "string",
  "malware_type": "string",
  "classification": "string",
  "platform": "string",
  "subplatform": "string",
  "sample_type": "string",
  "sample_size": 0,
  "last_download_url": "string",
  "threat_name": "string",
  "sample_available": 0,
  "sha1": "string",
  "sha256": "string",
  "last_download": "string",
  "md5": "string",
  "first_seen": "string",
  "threat_level": 0,
  "trust_factor": 0,
  "malware_family": "string",
  "last_seen": "string"
}
```

- `sha1`
  - The SHA1 hash of the file
- `last_download_url`
  - The URL from which the file was last downloaded
- `classification`
  - File classification. Can be one of the following: KNOWN, MALICIOUS, SUSPICIOUS, UNKNOWN
- `md5`
  - MD5 of the file
- `sha256`
  - SHA256 of the file
- `first_download`
  - Time when the file was first downloaded from the requested domain (UTC)
- `last_download`
  - Time when the file was last downloaded from the requested domain (UTC)
- `sample_available`
  - Indicates whether the sample is present in the ReversingLabs storage and available for download (true) or not (false).
- `trust_factor`
  - Trustworthiness indicator for known samples, expressed as an integer between 0 and 5, where 0 indicates the most trusted samples (highest confidence). **Applies to known samples only**
- `threat_name`
  - Complete malware threat name. Conforms to the [ReversingLabs malware naming standard](/General/AnalysisAndClassification/MalwareNamingStandard): *platform-subplatform.type.familyname*. **Applies to malicious and suspicious samples only**
- `threat_level`
  - Malware severity indicator for suspicious and malicious samples, expressed as an integer between 0 and 5, where 5 indicates the most dangerous threats (highest severity). **Applies to malicious and suspicious samples only**
- `malware_type`
  - The *type* part of the full threat name detected for the sample (for example, Trojan, Adware, Rootkit...). Conforms to the [ReversingLabs malware naming standard](/General/AnalysisAndClassification/MalwareNamingStandard). **Applies to malicious and suspicious samples only**
- `malware_family`
  - The *familyname* part of the full threat name detected for the sample (for example, Marsdaemon, Orcus, Androrat...).. **Applies to malicious and suspicious samples only**
- `platform`
  - The platform targeted by the malware
- `subplatform`
  - The subplatform targeted by the malware
- `sample_type`
  - File type, as detected by [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis)
- `sample_size`
  - File size (in bytes)
- `first_seen`
  - Time when the sample was first seen in the ReversingLabs system (UTC)
- `last_seen`
  - The last time when the file received impactful changes that updated its threat intelligence report. (UTC)

### Examples

#### Retrieve files downloaded from a domain with extended metadata

Get extended metadata about malicious files downloaded from *530908.selcdn.ru* using a JSON request. Request the response in JSON, and limit it to 1 item.

Request:

```
/api/networking/domain/downloaded_files/v1/query/json
```

``` json
{
  "rl": {
    "query": {
      "domain": "530908.selcdn.ru",
      "limit": 1,
      "extended": true,
      "classification": "MALICIOUS",
      "response_format": "json"
    }
  }
}
```

Response:

``` json
{
  "rl": {
    "next_page": "7727ef8156fa0f9c013b7525c26bfc42c08fc8bc",
    "requested_domain": "530908.selcdn.ru",
    "downloaded_files": [
      {
        "first_download": "2021-07-31T12:53:36",
        "threat_level": 5,
        "classification": "MALICIOUS",
        "threat_name": "Script-JS.Trojan.Cryxos",
        "subplatform": "JS",
        "last_seen": "2022-07-10T14:37:15",
        "sample_type": "Text/JavaScript",
        "last_download_url": "http://530908.selcdn.ru/0utllook-vvebs/kevn.htm",
        "sample_size": 111196,
        "sample_available": true,
        "sha1": "489712811cf611dfe4c8e8a6e3f7d57850021847",
        "platform": "Script",
        "last_download": "2021-07-31T12:53:36",
        "malware_type": "Trojan",
        "first_seen": "2021-07-31T05:24:58",
        "sha256": "ac582ad332d42964245da72ef5a240f54d96874d0bf044d6ce09ed8c0029a036",
        "trust_factor": 5,
        "malware_family": "Cryxos",
        "md5": "6e327edde38e71dc1196e743217010e9"
      }
    ]
  }
}
```

## Domain URLs

This service provides a list of URLs associated with the requested domain.

### Request

```
POST /api/networking/domain/urls/v1/query/{format}
```

Path parameters:

- `format`
  - Defines the POST body format. Supported values: `xml` and `json`.
  - Required

Request body:

``` json
{
  "rl": {
    "query": {
      "domain": "string",
      "response_format": "string",
      "limit": 3
    }
  }
}
```

- `domain`
  - The domain for which to retrieve the URLs.
  - Required
- `response_format`
  - Defines the response format. Supported values: `xml` and `json`.
  - Optional
- `limit`
  - The number of files to return in the response. Default value: **1000**
  - Optional

### Response

The endpoint will return a list of maximum **limit** records. If the **limit** value is not provided in the request, the maximum of 1000 records will be returned by default.

```json
{
  "rl": {
    "next_page": "string",
    "requested_domain": "string",
    "urls": []
  }
}
```

- `requested_domain`
  - submitted domain
- `next_page`
  - This value can be used with the `page` parameter in the next request to retrieve the next page of domain resolutions
- `urls`
  - List of URLs

### Examples

#### Retrieve URLs for a domain with paging

Retrieving three records in JSON format, and providing the next page parameter `0030a7528573ce306ea2d0d9d66128b915bc95b1`.

Request:

```
/api/networking/domain/urls/v1/query/json
```

``` json
{
  "rl": {
    "query": {
      "domain": "530908.selcdn.ru",
      "limit": 3,
      "response_format": "json",
      "page": "03c123eeca9351c35a7ac3f14832e58e20ccf35a"
    }
  }
}
```

Response:

``` json
{
  "rl": {
    "next_page": "05755cfc6fc64a755e3201f1c2b32af8f9e02752",
    "requested_domain": "530908.selcdn.ru",
    "urls": [
      {
        "url": "http://530908.selcdn.ru/sharepoint-thunder-nasal-newsboy/index1.html/"
      },
      {
        "url": "https://530908.selcdn.ru/0utlook-bookcook-blue-confused-territory/r.html?email=john.jones@jjrichards.com.au"
      },
      {
        "url": "http://530908.selcdn.ru/general-vveb-online/gen.html"
      }
    ]
  }
}
```

## Domain resolutions

This service provides a list of domain-to-IP mappings for the requested domain.

### Request

```
POST /api/networking/domain/resolutions/v1/query/{format}
```

Path parameters:

- `format`
  - Defines the POST body format. Supported values: `xml` and `json`.
  - Required

Request body:

``` json
{
  "rl": {
    "query": {
      "domain": "string",
      "response_format": "string",
      "limit": 3
    }
  }
}
```

- `domain`
  - The domain for which to retrieve the resolved IP addresses.
  - Required
- `response_format`
  - Defines the response format. Supported values: `xml` and `json`.
  - Optional
- `limit`
  - The number of files to return in the response. Default value: **1000**
  - Optional

### Response

The endpoint will return a list of maximum **limit** records. If the **limit** value is not provided in the request, the maximum of 1000 records will be returned by default.

```json
{
  "rl": {
    "requested_domain": "string",
    "resolutions": [],
    "next_page": "string"
  }
}
```

- `requested_domain`
  - submitted domain
- `next_page`
  - This value can be used with the `page` parameter in the next request to retrieve the next page of domain resolutions
- `resolutions`
  - List of domain resolutions

----------------------------------------------------------------------

`rl.resolutions[]`

```
{
  "record_type": "string",
  "answer": "string",
  "last_resolution_time": "string",
  "provider": "string"
}
```

- `record_type`
  - type of DNS record
- `answer`
  - DNS query answer
- `provider`
  - resolution source
- `last_resolution_time`
  - last time the requested domain was resolved to this IP (UTC)

### Examples

#### Retrieve resolutions for a domain with paging

Retrieving five records in JSON format, and providing the next page parameter `1d083566ec3ce77ff4f5c033366de0ec2f1fe853`.

Request:

```
/api/networking/domain/urls/v1/query/json
```

``` json
{
  "rl": {
    "query": {
      "domain": "google.com",
      "response_format": "json",
      "limit": 5,
      "page": "1d083566ec3ce77ff4f5c033366de0ec2f1fe853"
    }
  }
}
```

Response:

``` json
{
  "rl": {
    "resolutions": [
      {
        "record_type": "A",
        "answer": "172.217.168.196",
        "last_resolution_time": "2020-09-28T15:00:02",
        "provider": "ReversingLabs"
      },
      {
        "record_type": "A",
        "answer": "142.251.141.36",
        "last_resolution_time": "2024-03-01T01:02:19",
        "provider": "ReversingLabs"
      },
      {
        "record_type": "A",
        "answer": "76.76.21.123",
        "last_resolution_time": "2023-12-08T17:32:05",
        "provider": "ReversingLabs"
      },
      {
        "record_type": "A",
        "answer": "178.16.128.20",
        "last_resolution_time": "2024-01-16T20:55:25",
        "provider": "ReversingLabs"
      },
      {
        "record_type": "A",
        "answer": "172.217.23.164",
        "last_resolution_time": "2021-01-21T10:42:40",
        "provider": "ReversingLabs"
      }
    ],
    "requested_domain": "google.com",
    "next_page": "1dfe7cf222f4f4369e74cfc6e90c640a357382f2"
  }
}
```

## Domain related domains

This service provides a list of domains that have the same top parent domain as the requested domain. If the requested domain is a top parent domain, the API will return all subdomains.

### Request

```
POST /api/networking/domain/related_domains/v1/query/{format}
```

Path parameters:

- `format`
  - Defines the POST body format. Supported values: `xml` and `json`.
  - Required

Request body:

``` json
{
  "rl": {
    "query": {
      "domain": "string",
      "response_format": "string",
      "limit": 3
    }
  }
}
```

- `domain`
  - The domain for which to retrieve the list of related domains.
  - Required
- `response_format`
  - Defines the response format. Supported values: `xml` and `json`.
  - Optional
- `limit`
  - The number of files to return in the response. Default value: **1000**
  - Optional

### Response

The endpoint will return a list of maximum **limit** records. If the **limit** value is not provided in the request, the maximum of 1000 records will be returned by default.

```json
{
  "rl": {
    "next_page": "string",
    "requested_domain": "string",
    "related_domains": []
  }
}
```

- `requested_domain`
  - submitted domain
- `next_page`
  - This value can be used with the `page` parameter in the next request to retrieve the next page of domain resolutions
- `related_domains`
  - List of related domains

----------------------------------------------------------------------

`rl.related_domains[]`

```json
{
  "domain": "string"
}
```

----------------------------------------------------------------------

### Examples

#### Retrieve related domains for a domain with paging

Retrieving five records in JSON format, and providing the next page parameter `07c9693a82ee38525a7d75727abfae1bf03d9e31`.

Request:

```
/api/networking/domain/urls/v1/query/json
```

``` json
{
  "rl": {
    "query": {
      "domain": "google.com",
      "response_format": "json",
      "limit": 5,
      "page": "07c9693a82ee38525a7d75727abfae1bf03d9e31"
    }
  }
}
```

Response:

``` json
{
  "rl": {
    "next_page": "115b4399bbf7e431773694592c5b6cb5b2d6e749",
    "requested_domain": "google.com",
    "related_domains": [
      {
        "domain": "mw1.google.com"
      },
      {
        "domain": "r5---sn-5uaezne6.c.pack.google.com"
      },
      {
        "domain": "script.google.com"
      },
      {
        "domain": "442206.drive.google.com"
      },
      {
        "domain": "lh3.google.com"
      }
    ]
  }
}
```
