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

> Query TCA-0406 for IP address reports with reputation, WHOIS, GeoIP, hosted files, and domain resolutions from Spectra Intelligence.

This service returns threat intelligence data for the submitted IP address. The reports contain IP address reputation from various reputation sources, the maliciousness of files found on the submitted IP address, and other metadata like related URLs and IP address resolutions.

Information about the hosted files, related URLs, and IP address resolutions comes from our internal databases and URLs submitted for analysis using the TCA-0404 Analyze URL service.

### Privacy and Data Handling

IPs 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:

[**IP report**](#ip-report) and [**IP bulk report**](#ip-bulk-report)

These endpoints return:

- Third-party IP address reputation and categorization.
- Counters of samples downloaded from the IP address, mapped to their classification status (malicious, suspicious, known, unknown)
- The most common threats (malware type, family) hosted on the submitted IP address
- WHOIS registration and ownership data, if available and if `extended` is set to `true`
- GeoIP data, if available and if `extended` is set to `true`

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

Provides a list of hashes and classifications for files found on the submitted IP address.

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 URLs endpoint**](#ip-urls)

Returns a list of URLs hosted on the submitted IP address.

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

Provides a list of IP-to-domain mappings.

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

## IP report

This service returns threat intelligence data for the submitted IP. The report contains IP reputation from various reputation sources, classification statistics for files downloaded from the IP, and the top threats hosted on the submitted IP. If available, WHOIS data about the submitted IP is also included in the response, as well as GeoIP data.

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

### Request

```
POST /api/networking/ip/report/v1/query/{format}?[extended=true|false]
```

#### Path parameters

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

#### Query parameters

- `extended`
  - Boolean; if set to true, the response will include WHOIS registration and ownership data for the IP address associated with the submitted URL, along with GeoIP data.
  - Default value: `false`

#### Request body

``` json
{
    "rl": {
        "query": {
            "ip": "192.168.1.1",
            "response_format": "json"
        }
    }
}
```

- `ip`
  - The IP for which to retrieve the report.
  - Required
- `response_format`
  - Defines the response format. Supported values: `xml` and `json`.
  - Optional
- `extended`
  - Boolean; if set to true, the response will include WHOIS registration and ownership data for the submitted IP address, along with GeoIP data
  - Default value: `false`

### Response

The returned report contains third party reputation and statistics, counters of downloaded samples mapped to their classification status (malicious, suspicious, known, unknown), the top threats hosted on the submitted IP address, 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_ip": "string",
    "third_party_reputations": {},
    "downloaded_files_statistics": {},
    "top_threats": [],
    "last_seen": "string",
    "modified_time": "string"
  }
}
```

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

`rl.third_party_reputations.statistics`

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

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

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

`rl.third_party_reputations.sources[]`

```json
{
  "source": "string",
  "update_time": "string",
  "detect_time": "string",
  "detection": "string",
  "category": "string"
}
```

- `source`
  - Name of the third party source
- `detection`
  - Detection for the submitted IP. The possible values are **malicious/suspicious/clean/undetected**. If the source does not have any information about the IP, the value will be undetected.
- `categories`
  - IP 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 IP was last detected or given a category by the source.

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

`rl.downloaded_files_statistics`

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

- `total`
  - The total number of files downloaded from the IP
- `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.top_threats`

List of top 5 threats found at a given IP. Threats are ranked first by files_count and then by threat_level.

```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.third_party_reputations.whois`

If requested and available, the response will include WHOIS data in the `rl.third_party_reputations.whois` array. These records contain registration and allocation details retrieved from regional WHOIS providers (such as RIPE or ARIN).

Returned WHOIS records vary by source. The structure is not fixed, but typical fields may include:

- `route` or `CIDR`: IP range.

- `netname` or `NetName`: Name of the netblock.

- `descr`: Description of the network entity.

- `org`, `organisation`, or `Organization`: Owning organization.

- `country`, `created`, `last-modified`, `source`, and others.

**Note: Users should not assume a fixed schema. Always check field existence before processing.**


**Example - WHOIS Format A (RIPE-style)**

```json
{
  "rl": {
    "third_party_reputations":{
      "whois": [
        {
          "route": "153.128.64.0/18",
          "descr": "Some Company d.d",
          "origin": "AS37235",
          "mnt-by": "MIMECAST-MNT",
          "created": "2004-05-01T10:20:23Z",
          "last-modified": "2012-11-13T14:23:20Z",
          "source": "RIPE"
        },
        {
          "inetnum": "153.128.64.0 - 153.128.127.255",
          "netname": "SC",
          "descr": "Some Company d.d.",
          "country": "HR",
          "org": "ORG-IA28-RIPE",
          "admin-c": "NP1462-RIPE",
          "tech-c": "II385-RIPE",
          "remarks": [
            "This information has been partially mirrored by APNIC from",
            "RIPE. To obtain more specific information, please use the",
            "RIPE WHOIS Gateway."
          ],
          "last-modified": "2020-07-14T19:02:03Z",
          "source": "JPNIC"
        }
      ]
    }
  }
}
```

**Example - WHOIS Format B (ARIN-style)**

```json
{
  "rl": {
    "third_party_reputations":{
      "whois": [
        {
          "NetRange": "153.128.64.0 - 153.128.127.255",
          "CIDR": "153.128.64.0/18",
          "NetName": "FOOGLE",
          "NetHandle": "NET-153-128-64-0-1",
          "Parent": "NET1153 (NET-153-128-64-0-0)",
          "NetType": "Direct Allocation",
          "OriginAS": "AS15169",
          "Organization": "Foogle LLC (FOGL)",
          "RegDate": "2012-05-24",
          "Updated": "2012-05-24",
          "Ref": "https://rdap.arin.net/registry/ip/153.128.64.0"
        },
        {
          "OrgName": "Foogle LLC",
          "OrgId": "FOGL",
          "Address": "1600 Foo Parkway",
          "City": "Mountain View",
          "StateProv": "CA",
          "PostalCode": "94043",
          "Country": "US",
          "RegDate": "2000-03-30",
          "Updated": "2019-10-31",
          "Comment": [
            "Please note that the recommended way to file abuse complaints are located in the following links.",
            "To report abuse and illegal activity: https://www.foogle.com/contact/",
            "Regards,",
            "The Foogle Team"
          ],
          "Ref": "https://rdap.arin.net/registry/entity/FOGL"
        }
      ]
    }
  }
}
```

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

`rl.geoip`

If requested and available, the response will include GeoIP data in the `rl.geoip` object. This contains geographic location information for the submitted IP address.

- `as`
  - Autonomous System Number for the IP address
- `as_org`
  - Organization name associated with the Autonomous System
- `network`
  - CIDR notation of the network block containing the IP
- `location.city`
  - City where the IP is geographically located
- `location.country.iso_code`
  - ISO 3166-1 alpha-2 country code
- `location.latitude`
  - Geographic latitude coordinate
- `location.longitude`
  - Geographic longitude coordinate

**Example - GeoIP**

```json
{
  "rl": {
    "geoip": {
      "as": "16625",
      "as_org": "Akamai Technologies, Inc.",
      "network": "92.123.36.0/22",
      "location": {
        "city": "Vienna",
        "country": {
          "iso_code": "AT"
        },
        "latitude": 48.2082,
        "longitude": 16.3738
      }
    }
  }
}
```

### Examples - report retrieval

#### Retrieve a report (JSON)

Retrieving an IP report in JSON format, using a JSON POST body

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

``` json
{
  "rl": {
    "query": {
      "ip": "216.239.34.36",
      "response_format": "json"
    }
  }
}
```

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

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

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

``` json
{
  "rl": {
    "query": {
      "ip": "149.28.54.212",
      "response_format": "json"
    }
  }
}
```

## IP bulk report

This service returns threat intelligence data for the submitted IPs. The report for each contains IP reputation from various reputation sources, classification statistics for files downloaded from the IP, and the top threats hosted on the submitted IP. The limit is 100 IPs per request.

<Button title="View OpenAPI Specification" href="" />

### Request

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

#### Path parameters

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

#### Request body

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

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

### Response

```json
{
  "rl": {
    "entries": [
      {
        "requested_ip": "string",
        "third_party_reputations": {},
        "downloaded_files_statistics": {},
        "top_threats": [],
        "first_seen": "string",
        "last_seen": "string"
      }
    ]
  }
}
```

## IP downloaded files

This service returns a list of files downloaded from the submitted IP address.

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

### Request

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

#### Path parameters

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

#### Request body

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

- `ip`
  - The IP for which to retrieve a list of files.
  - Required
- `response_format`
  - Defines the response format. The following values are supported: `xml` (default) 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 IP. Empty fields are not included in the response.

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

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

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

`rl.downloaded_files[]`

```json
{
  "first_download": "string",
  "threat_level": 0,
  "classification": "string",
  "last_seen": "string",
  "last_download_url": "string",
  "sample_size": 0,
  "sample_available": 0,
  "sha1": "string",
  "last_download": "string",
  "first_seen": "string",
  "sha256": "string",
  "trust_factor": 0,
  "md5": "string"
}
```

- `sha1`
  - The SHA1 hash of the file
- `last_download_url`
  - 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 IP (UTC)
- `last_download`
  - Time when the file was last downloaded from the requested IP (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 using pagination

Get basic metadata about files downloaded from *37.34.248.24*, starting from page *54d1ec4a661e374661f04c2db29e1736dac62ff8*, using a **json** request. Limit the response to 2 items.

Request:

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

Response:

``` json
{
  "rl": {
    "requested_ip": "37.34.248.24",
    "next_page": "5bbf9eb85c388624b367e46205dc62244544f33b",
    "downloaded_files": [
      {
        "last_download_url": "http://rgyui.top/dl/build.exe",
        "sha1": "54d1ec4a661e374661f04c2db29e1736dac62ff8",
        "classification": "MALICIOUS"
      },
      {
        "last_download_url": "http://acacaca.org/test3/get.php?first=true&pid=54CDD75ABCEFFD43CB02140E4B4CC293",
        "sha1": "596da184fb7a232c38144ebfd158af1e83224478",
        "classification": "KNOWN"
      }
    ]
  }
}
```

#### Retrieve files downloaded from an IP address with extended metadata

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

Request:

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

``` json
{
  "rl": {
    "query": {
      "ip": "37.34.248.24",
      "limit": 1,
      "extended": true,
      "classification": "MALICIOUS",
      "response_format": "json"
    }
  }
}
```

Response:

``` json
{
  "rl": {
    "requested_ip": "37.34.248.24",
    "next_page": "54d1ec4a661e374661f04c2db29e1736dac62ff8",
    "downloaded_files": [
      {
        "first_download": "2022-03-23T23:14:01",
        "threat_level": 5,
        "classification": "MALICIOUS",
        "threat_name": "Win32.Ransomware.StopCrypt",
        "last_seen": "2022-09-24T20:10:31",
        "sample_type": "PE/Exe",
        "last_download_url": "http://zerit.top/dl/build2.exe",
        "sample_size": 659968,
        "sample_available": true,
        "sha1": "1d61784e581389bfbb73fb6c3fdc9eb7af9af9b9",
        "platform": "Win32",
        "last_download": "2022-03-23T23:14:01",
        "malware_type": "Ransomware",
        "first_seen": "2022-03-21T19:42:44",
        "sha256": "082bf5ea5ae40e0328401f3e74b516e362ddc57c60ab194e1d2afd297ddf6e5e",
        "trust_factor": 5,
        "malware_family": "StopCrypt",
        "md5": "467f161440e8fac46258178e1b0784ca"
      }
    ]
  }
}
```

## IP URLs

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

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

### Request

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

#### Path parameters

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

#### Request body

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

- `ip`
  - The IP 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": {
    "requested_ip": "string",
    "next_page": "string",
    "urls": []
  }
}
```

- `requested_ip`
  - submitted IP
- `next_page`
  - This value can be used with the `page` parameter in the next request to retrieve the next page of analyzed URLs
- `urls`
  - List of associated URLs

### Examples

#### Retrieve URLs for specified IP with paging

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

Request:

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

``` json
{
  "rl": {
    "query": {
      "ip": "104.19.138.57",
      "limit": 3,
      "response_format": "json",
      "page": "0030a7528573ce306ea2d0d9d66128b915bc95b1"
    }
  }
}
```

Response:

``` json
{
  "rl": {
    "next_page": "006ecec7f550cadfcbc0176ca2ace08ad1833d02",
    "requested_ip": "104.19.138.57",
    "urls": [
      {
        "url": "https://google.com/url?cad=rja&esrc=s&rct=j&sa=t&source=web&uact=8&url=https://procrackerz.org/hitmanpro-crack-full-download/&usg=AOvVaw2qNutd2-aIy96HjHtql3Ww&ved=2ahUKEwiP4v79xZrxAhWotIsKHUMODTcQFjAAegQIBhAD"
      },
      {
        "url": "https://google.com/maps/place/Vernier+Software+&+Technology/"
      },
      {
        "url": "https://google.com/cse/cse.js?cx=014672437645974190520:sx5qa5dqcmm"
      }
    ]
  }
}
```

## IP domain resolutions

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

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

### Request

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

#### Path parameters

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

#### Request body

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

- `ip`
  - The IP for which to retrieve domain resolutions.
  - 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_ip": "string",
    "next_page": "string",
    "resolutions": []
  }
}
```

- `requested_ip`
  - submitted IP
- `next_page`
  - This value can be used with the `page` parameter in the next request to retrieve the next page of analyzed URLs
- `resolutions`
  - List of associated resolutions

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

`rl.resolutions`

```json
{
  "last_resolution_time": "string",
  "host_name": "string",
  "provider": "string"
}
```

- `host_name`
  - The domain resolves to requested IP
- `last_resolution_time`
  - Most recent time IP has resolved to this domain
- `provider`
  - Provider of this resolution

### Examples

#### Retrieve domain resolutions for an IP with paging

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

Request:

```
/api/networking/ip/resolutions/v1/query/json
```

``` json
{
  "rl": {
    "query": {
      "ip": "37.34.248.24",
      "response_format": "json",
      "limit": 3,
      "page": "587196222d542cf07fbb337dc6c723810738214e"
    }
  }
}
```

Response:

``` json
{
  "rl": {
    "requested_ip": "37.34.248.24",
    "resolutions": [
      {
        "provider": "ReversingLabs",
        "host_name": "zerit.top",
        "last_resolution_time": "2022-03-23T23:14:01"
      },
      {
        "provider": "ReversingLabs",
        "host_name": "winnlinne.com",
        "last_resolution_time": "2022-10-07T00:29:41"
      },
      {
        "provider": "ReversingLabs",
        "host_name": "abababa.org",
        "last_resolution_time": "2022-06-17T10:49:43"
      }
    ],
    "next_page": "6f4226f6457c9e24364d56dd3c047acbc1b25fc8"
  }
}
```
