Malware File Scanner API Documentation

Malware File Scanner API

IPQualityScore's Malware File Scanner API scans files in real-time to detect viruses and malicious files. Accurately detect ransomware, trojans, keyloggers, adware, rootkits, spyware, and all sorts of unwanted software with our live file malware scanning.

Virus File Scanning

Detect viruses and suspicious software with real-time malware file scanning. IPQS's file virus scanning API can accept a file, which is analyzed in a live sandbox environment to identify ransomware, trojans, keyloggers, viruses, and similar malicious files. Retrieve additional details like file size, file type, file hash, etc. through the file scanning API results.

Malware File Scanning API Use Cases

Scan Email Attachments - Identify suspicious files and risky attachments, using a live scanning approach that can determine email attachment risk and verify if the files are safe to open.
Filter Message Content - Scan user generated content and live messages for suspicious URLs and files that contain viruses or malware.
Detect High Risk URLs - Detect suspicious URLs designed to steal credentials or upload malicious files, using our URL scanner API.
Phishing Detection - Keep your team safe with advanced phishing detection using our live URL scanner service. Enrich risk signals around a URL or domain with live phishing and malware detection.
Threat Intelligence Enrichment - Full support for detecting rootkits, viruses, phishing, malware, adware, spyware, trojans, worms, keyloggers, ransomware, and even business email compromise (BEC).

File Scanner API Private Key

Please login or create a free account to access your API Key.

NOTE: Do not share this key with anyone. It's like a password and can be used to make queries using our API.

Malware File Scanner Request URLs

The URLs below can be used to fetch the result using cURL or another utility in most languages. Please see the usage example at the bottom of the page. Simply replace "TYPE" with the type of scan and provide a URL or file.

JSON:

XML:

The "type" can be populated with "scan" or "lookup". The "lookup" value will only check our database of file scans in the last 24 Hours for the same file, while "scan" executes a full malware file virus scan. Please use the "file" field to submit the file by POST with each API request. You can optionally pass a file URL instead of the entire file, as shown in our example code.

JSON Success Response Example

{
    "success": true,
    "message": "Success",
    "file_hash": "e53c379d95e95706c5a2c4d6cd609857368a3bf14f28d7e67f6e3f8dfce6d486",
    "type": "scan",
    "status": "completed",
    "result": [
        {
            "name": "IPQS Threat Defender",
            "detected": false,
            "error": false
        },
        {
            "name": "IPQS Emerging Threats",
            "detected": true,
            "error": false
        },
        {
            "name": "IPQS Foreign Entity Checker",
            "detected": false,
            "error": false
        },
        {
            "name": "IPQS Byte Checks",
            "detected": false,
            "error": false
        },
        {
            "name": "IPQS Malicous Network Activity",
            "detected": false,
            "error": false
        },
        {
            "name": "IPQS Internet Security Suite",
            "detected": false,
            "error": false
        },
        {
            "name": "IPQS Malicious Code Scanner",
            "detected": false,
            "error": false
        }
    ],
    "update_url": "https://ipqualityscore.com/api/json/postback/YOUR_API_KEY_HERE?request_id=H7snPYbZrb",
    "request_id": "H7snPYbZrb"
}

NOTE: For a description of each field listed above, please consult the response documentation below.

JSON Error Response Examples

Example errors that you may encounter when accessing our API due to an exhausted credit balance or an invalid URL.

{
    "success":false,
    "message":"You have insufficient credits to make this query. Please contact IPQualityScore support if this error persists.",
                    "request_id":"4OTORR352FU0p"
                    }

Further Details on File Scanning API Results

The following definitions explain each of the malware file scanner API's data points.

Field	Description	Possible Values
success	Indicates if the api request was successful	boolean
message	potential error message	string
file_hash	sha256 of the provided file	string
type	Type of scan	string
status	Depends on type of scan, possible values include: "completed", "cached", or "pending"	string
result	Result of the scan, which lists if any threat engines detected a virus, rootkit, ransomware, keylogger, or similar type of malicious file	json
update_url	if the status is pending, request this url to fetch the result	string
request_id	A unique identifier for this request that can be used to lookup the request details or send a postback conversion notice.	string
errors	Array of errors which occurred while attempting to process this request.	array of strings

    <?php
// Your API Key
$key = 'YOUR_API_KEY_HERE';

// Type of API request (scan or lookup)
$type = 'scan';

// Create API URL
$url = sprintf(
	'%25s.html',
	$type,
	$key
);

// The file you want to scan
$file_to_scan = 'eicar.com';

// Fetch The Result
$timeout = 5;

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, $timeout);
curl_setopt($curl, CURLOPT_POSTFIELDS, [
    'file' => new CURLFile($file_to_scan),
]);
$json = curl_exec($curl);
curl_close($curl);

// Decode the result into an array.
$result = json_decode($json, true);

// Check to see if our query was successful.
if(isset($result['success']) && $result['success'] === true){
    return $result;
}

import requests
import json
import time
def HandleResult(data):
    if data.status_code != 200:
        raise Exception("Error: " + str(data.status_code))
    data = json.loads(data.text)
    if data["status"] != "pending":
        return data["result"]
    while True:
        time.sleep(1)
        data = requests.post(data["update_url"])
        return HandleResult(data)

def ScanUrl(apikey,url):
    data = requests.post("https://ipqualityscore.com/api/json/malware/scan/" + apikey, data = {'url': url})
    return HandleResult(data)
def ScanFile(apikey,file):
    data = requests.post("https://ipqualityscore.com/api/json/malware/scan/" + apikey, files = {'file': open(file,"rb")})
    return HandleResult(data)

print(ScanUrl("YOUR_API_KEY_HERE","https://secure.eicar.org/eicar.com"))
print(ScanFile("YOUR_API_KEY_HERE","eicar.com"))