# IPQualityScore

> Detect fraud with IPQualityScore (IPQS): score how risky an IP address, email address, phone number, link, file or whole transaction is, spot proxies, VPNs, bots, disposable emails, VOIP numbers, phishing and malware, and check for credentials leaked on the dark web. Manage your allowlist and blocklist, report fraud, record conversions, run bulk validations and Fraud Flows, and read your lookup history and credit usage. Needs an IPQualityScore account; the free plan includes 1,000 lookups a month.

App · Compliance & Security · 32 actions. Web page: https://docs.lodol.com/docs/integrations/ipqualityscore

## Actions

### Add to allowlist

Allowlist an IP address or range, an ISP, a device, an email address, a domain or a phone number, so IPQS always scores it 0 and never flags it, for trusted customers or partners.

**Inputs**

- Applies to (`lookup_type`, text, required): Which lookups the entry applies to. One of: `proxy` (IP address checks), `email` (Email address checks), `phone` (Phone number checks), `url` (URL scans), `devicetracker` (Device fingerprints (website)), `mobiletracker` (Device fingerprints (mobile app)).
- Value (`value`, text, required): The value: an IP address, a CIDR range like 203.0.113.0/24, an ISP name, a device ID, an email address, a domain or a phone number, to suit what it applies to.
- Value type (`value_type`, text): What kind of value it is. Leave it empty to work it out: an IP address or range, and for IP checks anything else as an ISP name. Choose it for a device ID. One of: `ip` (IP address), `cidr` (IP range (CIDR)), `isp` (ISP name), `deviceid` (Device ID), `email` (Email address), `domain`, `phone` (Phone number).
- Reason (`reason`, text): Why the value is on the list, for your own records.

**Outputs**

- `lookup_type` (text): Which lookups the entry applies to: proxy (IP addresses), email, phone, url, devicetracker or mobiletracker.
- `message` (text): IPQS's confirmation, in its words.
- `reason` (text): The reason given, when one was.
- `request_id` (text): IPQS's ID for this change.
- `value` (text): The value, as it was sent.
- `value_type` (text): What kind of value it is: ip, cidr, isp, deviceid, vendorid, email, domain or phone.

**Example output**

```json
{
  "lookup_type": "proxy",
  "message": "Successfully inserted Allow List entry.",
  "reason": "Office network",
  "request_id": "CXSWDmbNcw",
  "value": "1.1.1.1",
  "value_type": "ip"
}
```

### Add to blocklist

Blocklist an IP address or range, an ISP, a device, an email address, a domain or a phone number, so IPQS always scores it 100 and flags it as risky, for known fraudsters.

**Inputs**

- Applies to (`lookup_type`, text, required): Which lookups the entry applies to. One of: `proxy` (IP address checks), `email` (Email address checks), `phone` (Phone number checks), `url` (URL scans), `devicetracker` (Device fingerprints (website)), `mobiletracker` (Device fingerprints (mobile app)).
- Value (`value`, text, required): The value: an IP address, a CIDR range like 203.0.113.0/24, an ISP name, a device ID, an email address, a domain or a phone number, to suit what it applies to.
- Value type (`value_type`, text): What kind of value it is. Leave it empty to work it out: an IP address or range, and for IP checks anything else as an ISP name. Choose it for a device ID or a mobile app's vendor ID. One of: `ip` (IP address), `cidr` (IP range (CIDR)), `isp` (ISP name), `deviceid` (Device ID), `email` (Email address), `domain`, `phone` (Phone number), `vendorid` (Mobile app vendor device ID).
- Reason (`reason`, text): Why the value is on the list, for your own records.

**Outputs**

- `lookup_type` (text): Which lookups the entry applies to: proxy (IP addresses), email, phone, url, devicetracker or mobiletracker.
- `message` (text): IPQS's confirmation, in its words.
- `reason` (text): The reason given, when one was.
- `request_id` (text): IPQS's ID for this change.
- `value` (text): The value, as it was sent.
- `value_type` (text): What kind of value it is: ip, cidr, isp, deviceid, vendorid, email, domain or phone.

**Example output**

```json
{
  "lookup_type": "email",
  "message": "Successfully inserted Block List entry.",
  "reason": "Chargeback",
  "request_id": "CXSWDmbNcw",
  "value": "fraud.signup@example.com",
  "value_type": "email"
}
```

### Check for leaked data

Check the dark web and known data breaches for an email address, a username or a password, or an email or username together with its password: whether it was exposed, in which breaches, and since when. A password is hashed before it leaves Lodol. Use it to stop account takeovers or to warn users with compromised credentials.

**Inputs**

- Email address (`email`, text): An email address to look for in leaks. With a password, the two are checked as a pair.
- Username (`username`, text): A username to look for in leaks, instead of an email address. With a password, the two are checked as a pair.
- Password (`password`, text): A password to look for in leaks. It is hashed with SHA-256 before it leaves Lodol; an MD5, SHA-1 or SHA-256 hash is sent as it is.

**Outputs**

- `checked` (text): What was checked: email, username, password, emailpass (an email address and password together) or userpass (a username and password together).
- `exposed` (true/false): Whether it was found in a data breach or leak.
- `first_seen` (object): When IPQS first saw it in a leak. Its fields are null when unknown.
- `plain_text_password` (true/false): Whether a password was found leaked in plain text.
- `request_id` (text): IPQS's ID for this lookup. Pass it to Report fraud to report the lookup as fraudulent, or to Get past lookup to read it again.
- `sources` (list): The breached websites or databases it was found in, e.g. Exploit Antipublic.

**Example output**

```json
{
  "checked": "email",
  "exposed": true,
  "first_seen": {
    "human": "1 year ago",
    "iso": "2023-04-10T10:37:29-04:00",
    "timestamp": 1681137449
  },
  "plain_text_password": true,
  "request_id": "DXdRw3mvSm",
  "sources": [
    "example.com",
    "example.com"
  ]
}
```

### Check IP address

Check how risky an IP address is with IPQS's Proxy and VPN Detection: a fraud score from 0 to 100, whether it is a proxy, a VPN, Tor, a bot or a crawler, any recent abuse, its connection type, ISP and location. Pass the visitor's user agent too for bot and device checks. A score of 90 or more is the usual point to block a sign up, login or payment.

**Inputs**

- IP address (`ip_address`, text, required): The public IPv4 or IPv6 address to check, such as the one a visitor signed up, logged in or paid from.
- Strictness (`strictness`, number): How deep the check goes, 0 to 3. IPQS recommends starting at 0 and moving to 1 if fraud gets through: 2 and 3 are very strict and flag honest users too. From 0 to 3. Default: `0`.
- User agent (`user_agent`, text): The visitor's browser user agent. With it IPQS also checks for bots and fills in the device, browser and operating system.
- User language (`user_language`, text): The visitor's browser language header, e.g. en-US,en;q=0.9, which IPQS weighs into the score.
- Allow public access points (`allow_public_access_points`, true/false): Go easier on schools, universities, offices and public hotspots, whose shared addresses would otherwise score as risky. IPQS recommends it, so it is on unless turned off. Default: `true`.
- Lighter penalties (`lighter_penalties`, true/false): Score addresses of mixed quality lower, if honest users are being flagged. Default: `false`.
- Mobile device (`mobile`, true/false): Score the lookup as a mobile device. Use it for mobile visitors when there is no user agent; it gives odd results for other devices. Default: `false`.
- Fast (`fast`, true/false): Skip some slower forensic checks for a quicker answer, at a small cost in accuracy. Default: `false`.
- Custom variables (`custom_variables`, object): Your own tracking variables to record with the lookup, such as userID or transactionID, so you can find it again in your history and IPQS can spot patterns per user. Each must first be set up in your IPQS account settings.

**Outputs**

- `abuse_events` (list): Enterprise data point: the kinds of abuse IPQS has recently seen from the address, and when each was last seen. Empty when there are none, or when the plan does not include them.
- `abuse_velocity` (text): How often the address takes part in abuse across IPQS's network: high, medium, low or none.
- `active_tor` (true/false): Whether the address is an active Tor exit.
- `active_vpn` (true/false): Whether the address is an active VPN connection of a popular VPN service or a private VPN server.
- `asn` (number): The autonomous system number, when known.
- `bot_status` (true/false): Whether bots or other non-human traffic have recently used the address for automated fraud.
- `browser` (text): The browser and its version, e.g. Chrome 80.0. Read from the user agent, so null without one.
- `city` (text): The city the address is in, when known.
- `connection_type` (text): What kind of connection the address is: Residential, Corporate, Education, Mobile or Data Center.
- `country_code` (text): Two-letter code of the country the address is in, e.g. US.
- `device_brand` (text): The device's brand, e.g. Apple. Read from the user agent, so null without one.
- `device_model` (text): The device's model, e.g. iPad. Read from the user agent, so null without one.
- `dynamic_connection` (true/false): Enterprise data point: whether the provider assigns addresses dynamically, so its user will likely have a different address soon. Null when the plan does not include it.
- `fraud_score` (number): IPQS's fraud score for the address, 0 to 100. 75 and above is suspicious, often a proxy or VPN user rather than a fraudster; 85 and above is high risk; 90 and above has shown recent or frequent abuse, and is the usual point to block.
- `frequent_abuser` (true/false): Enterprise data point: whether the address has a consistent history of abuse over six months or more. Null when the plan does not include it.
- `high_risk_attacks` (true/false): Enterprise data point: whether the address has taken part in attacks such as phishing, brute forcing, DDoS, credential stuffing, scraping or form spam. Null when the plan does not include it.
- `host` (text): The address's host name, when it has one.
- `ip_address` (text): The IP address that was checked.
- `is_crawler` (true/false): Whether the address is a confirmed crawler of a search engine or service, such as Google, Bing, Baidu, Yandex, DuckDuckGo, Facebook, UptimeRobot or AppleBot.
- `isp` (text): The internet service provider, when known.
- `latitude` (number): The address's latitude, when known.
- `longitude` (number): The address's longitude, when known.
- `mobile` (true/false): Whether the user agent is a mobile browser. Always false when no user agent was given.
- `operating_system` (text): The device's operating system and version, e.g. Mac 10.6. Read from the user agent, so null without one.
- `organization` (text): The organization using the address, when known: the ISP itself, its parent company or one of its customers.
- `proxy` (true/false): Whether the address is suspected to be a proxy of any kind: SOCKS, elite, anonymous, VPN or Tor.
- `recent_abuse` (true/false): Whether IPQS has verified abuse from the address in the past few days: a chargeback, account takeover, compromised device, fake sign up, bot attack and the like.
- `recent_data_matches` (list): How often IPQS has seen the values sent in this lookup over the last 7 days, one entry per value. Empty when it has none to report.
- `recent_unique_user_values` (list): For your own tracking variables sent with the lookup (such as a user ID), how many different values of each kind IPQS has seen with them recently. Empty when none were sent.
- `region` (text): The region or state the address is in, when known.
- `request_id` (text): IPQS's ID for this lookup. Pass it to Report fraud to report the lookup as fraudulent, or to Get past lookup to read it again.
- `security_scanner` (true/false): Enterprise data point: whether the address is a verified security scanner of a trusted vendor, such as Tenable or Qualys. Null when the plan does not include it.
- `shared_connection` (true/false): Enterprise data point: whether the address likely has many users at once, such as a mobile network, an office, a library, a hotel or a company VPN. Null when the plan does not include it.
- `timezone` (text): The address's time zone, e.g. America/New_York, when known.
- `tor` (true/false): Whether the address is suspected to be a Tor connection, including past Tor nodes and exits. proxy is always true when this is.
- `trusted_network` (true/false): Enterprise data point: whether the address is on a company network with low abuse rates and strong security. Null when the plan does not include it.
- `vpn` (true/false): Whether the address is suspected to be a VPN connection, including data center ranges that can become VPNs at any time. proxy is always true when this is.
- `zip_code` (text): The address's postal code, when known. One address can span several postal codes in a city.

**Example output**

```json
{
  "abuse_events": [],
  "abuse_velocity": "medium",
  "active_tor": false,
  "active_vpn": false,
  "asn": 30036,
  "bot_status": false,
  "browser": "Chrome 122.0",
  "city": "Houston",
  "connection_type": "Residential",
  "country_code": "US",
  "device_brand": "Apple",
  "device_model": "iPad",
  "dynamic_connection": false,
  "fraud_score": 25,
  "frequent_abuser": false,
  "high_risk_attacks": false,
  "host": "192-0-2-110.client.mchsi.com",
  "ip_address": "8.8.8.8",
  "is_crawler": false,
  "isp": "Mediacom Cable",
  "latitude": 29.7079,
  "longitude": -95.401,
  "mobile": false,
  "operating_system": "Mac 10.6",
  "organization": "Mediacom Cable",
  "proxy": false,
  "recent_abuse": true,
  "recent_data_matches": [],
  "recent_unique_user_values": [],
  "region": "Texas",
  "request_id": "0w8WYS",
  "security_scanner": false,
  "shared_connection": true,
  "timezone": "America Matamoros",
  "tor": false,
  "trusted_network": false,
  "vpn": false,
  "zip_code": "77001"
}
```

### Download bulk validation results

Download a finished bulk validation's results as a CSV file, every record or only the clean, bad or pristine ones, for a later step to save, send or read.

**Inputs**

- Bulk validation ID (`bulk_validation_id`, number, required): The id Start bulk validation returned. At least 1.
- Results (`results`, text): Which records to download. One of: `all` (Every record), `clean` (Only the clean records), `bad` (Only the bad, invalid or unclean records), `pristine` (Only the extremely clean records). Default: `all`.

**Outputs**

- `bulk_validation` (object): The bulk validation the results are from.
- `byte_size` (number): The file's size in bytes.
- `content_type` (text): The file's type, text/csv.
- `document_ref` (text): The stored file's reference, for a later step.
- `documents` (list): The results file, ready to attach to a later step.
- `filename` (text): The file's name.
- `url` (text): A link that serves the stored file.

**Example output**

```json
{
  "bulk_validation": {
    "aborted": false,
    "file_name": "test.csv",
    "finished": true,
    "id": 827750,
    "invalid_records": 0,
    "list_type": "proxy",
    "request_id": "HE1BDCGjmf",
    "status": "FINISHED",
    "strictness": 0
  },
  "byte_size": 131,
  "content_type": "text/csv",
  "document_ref": "doc_5c0e2b7a9d4f4e1b8a6c3d2e1f0a9b8c",
  "documents": [
    {
      "content_type": "text/csv",
      "document_ref": "doc_5c0e2b7a9d4f4e1b8a6c3d2e1f0a9b8c",
      "filename": "example.csv",
      "size_bytes": 131,
      "url": "/actions/core/serve-document/doc_5c0e2b7a9d4f4e1b8a6c3d2e1f0a9b8c?teamId=6876e08ad6296a1d681d3c7c"
    }
  ],
  "filename": "example.csv",
  "url": "/actions/core/serve-document/doc_5c0e2b7a9d4f4e1b8a6c3d2e1f0a9b8c?teamId=6876e08ad6296a1d681d3c7c"
}
```

### Get average fraud score

Get the average fraud score of your past IP checks, or of one device tracker's fingerprints, for a country, a date range, a conversion status or a custom variable such as a user or a campaign. Use it to compare the quality of traffic sources.

**Inputs**

- Tracker ID (`tracker_id`, number): A device tracker's number, to average its fingerprints instead of IP checks. At least 1.
- Country (`country`, text): Only lookups from this country, e.g. US.
- Start date (`start_date`, date): Only from this day on.
- End date (`end_date`, date): Only up to this day.
- Conversion status (`conversion_status`, text): Only lookups with this conversion status. One of: `true` (Converted), `false` (Denied), `not_marked` (Not marked).
- Custom variables (`find_by`, object): Only lookups made with these custom variables, such as a userID or campaignID.

**Outputs**

- `found` (true/false): Whether any lookups matched.
- `fraud_average` (number): The average fraud score of the matching lookups, 0 to 100. Null when there are none.
- `of` (text): What was averaged: ip_checks, or tracker for one device tracker.
- `statistics` (object): Any other figures IPQS answered with, such as totals of devices and page views, in its own names.

**Example output**

```json
{
  "found": true,
  "fraud_average": 23.5,
  "of": "ip_checks",
  "statistics": {}
}
```

### Get bulk validation

Check how far a bulk validation has got, whether it is finished, and which result files it has to download.

**Inputs**

- Bulk validation ID (`bulk_validation_id`, number, required): The id Start bulk validation returned. At least 1.

**Outputs**

- `aborted` (true/false): Whether processing was cancelled before it finished.
- `file_name` (text): The list's file name.
- `finished` (true/false): Whether processing is finished, so the results can be downloaded.
- `id` (number): The bulk validation's ID. Pass it to Get bulk validation and to Download bulk validation results.
- `invalid_records` (number): How many records in the list were invalid, so far.
- `list_type` (text): What the list holds: email, phone, proxy (IP addresses) or url.
- `request_id` (text): IPQS's ID for this request.
- `results_available` (list): The result files that can be downloaded: all, clean, bad or pristine. Empty until it is finished.
- `status` (text): Where processing is: NEW, PROCESSING, UNIQUE_RESULTS (removing repeats), FINALIZING or FINISHED.
- `strictness` (number): The strictness the list is checked at, 0 to 3; 0 is IPQS's default.

**Example output**

```json
{
  "aborted": false,
  "file_name": "test.csv",
  "finished": true,
  "id": 827750,
  "invalid_records": 0,
  "list_type": "proxy",
  "request_id": "HE1BDCGjmf",
  "results_available": [
    "all"
  ],
  "status": "FINISHED",
  "strictness": 0
}
```

### Get credit usage

Get the account's available credits and how many this billing period's lookups have used, API by API. Costs no credits; good for a scheduled low-credit alert.

**Inputs**: None.

**Outputs**

- `credits` (number): The account's available credits for this billing period.
- `email_usage` (number): Credits used on email address checks.
- `fingerprint_usage` (number): Credits used on device fingerprints from websites.
- `mobile_sdk_usage` (number): Credits used on device fingerprints from mobile apps.
- `phone_usage` (number): Credits used on phone number checks.
- `proxy_usage` (number): Credits used on IP address checks.
- `request_id` (text): IPQS's ID for this lookup. Pass it to Report fraud to report the lookup as fraudulent, or to Get past lookup to read it again.
- `url_usage` (number): Credits used on URL scans.
- `usage` (number): Credits used this billing period, as IPQS totals them. IPQS's own examples count only IP and email checks in it, so add the figures below for every API.

**Example output**

```json
{
  "credits": 3004522,
  "email_usage": 472,
  "fingerprint_usage": 0,
  "mobile_sdk_usage": 22,
  "phone_usage": 1231,
  "proxy_usage": 6,
  "request_id": "3ift1XN",
  "url_usage": 211,
  "usage": 478
}
```

### Get device fingerprint result

Get a device fingerprint result from the server side, by the request ID your site or app received, or the latest one for a user by custom variables. It is the trusted way to act on a fingerprint, and the only way to see the reasons behind its fraud chance. The fingerprint itself is taken by IPQS's tracker on your site or in your app. Costs no credits.

**Inputs**

- Request ID (`request_id`, text): The lookup's request_id, as an earlier step returned it. Leave it empty to find the lookup by its custom variables instead.
- Find by custom variables (`find_by`, object): Instead of a request ID, the custom variables the lookup was made with, such as userID, to find the latest lookup that has them.
- Device source (`device_source`, text): Where the fingerprint was taken, when finding it by custom variables. One of: `devicetracker` (A website (the JavaScript tracker)), `mobiletracker` (A mobile app (the mobile SDK)). Default: `devicetracker`.
- Tracker ID (`tracker_id`, number): The device tracker's number, from IPQS's tracker settings, to search that tracker only. At least 1.

**Outputs**

- `active_tor` (true/false): Premium: whether it is an active Tor exit.
- `active_vpn` (true/false): Premium: whether the VPN is an active one.
- `adblock` (true/false): Premium: whether an ad blocker is in use.
- `bot_status` (true/false): Whether the device is a bot, a spoofed device or otherwise not human.
- `brand` (text): The device's brand.
- `browser` (text): The browser and version.
- `browser_fingerprint` (text): Premium: a hash of the browser and its settings.
- `canvas_hash` (text): A hash of the device's canvas profile.
- `city` (text): The city, when known.
- `click_date` (text): Premium: when this request was made, as IPQS writes it.
- `connection_type` (text): The connection: Residential, Corporate, Education, Mobile or Data Center.
- `cookies` (true/false): Premium: whether cookies are enabled.
- `country` (text): Two-letter code of the IP address's country.
- `cpu_cores` (number): Premium: the number of CPU cores.
- `device_id` (text): The device's ID, a hash of its hardware and settings, for spotting the same device on several accounts.
- `device_timezone` (text): Premium: the time zone the device itself reports.
- `first_seen` (text): Premium: when IPQS first saw the device, as IPQS writes it.
- `fraud_chance` (number): How likely the device is to commit fraud, 0 to 100; 25 is the median. 85 and above is suspicious and 90 and above is the usual point to block.
- `graphics_card` (text): Premium: the graphics card.
- `guid` (text): A hardware ID that devices with the same hardware can share; see guid_confidence.
- `guid_confidence` (number): How sure IPQS is that the guid matches other users, 0 to 100.
- `high_risk_device` (true/false): Premium: whether the device is very likely fraudulent, such as an emulator, a virtual device or one spoofing its location.
- `hostname` (text): Premium: the device's host name.
- `iframe_detected` (true/false): Premium: whether the page was loaded in a frame, a sign of clickjacking.
- `ip_address` (text): The device's IP address.
- `is_crawler` (true/false): Whether the device is a confirmed search engine crawler.
- `isp` (text): The internet service provider.
- `language` (text): Premium: the device's language, e.g. en-US.
- `last_seen` (text): Premium: when IPQS last saw the device, as IPQS writes it.
- `latitude` (number): Premium: the latitude, when known.
- `longitude` (number): Premium: the longitude, when known.
- `memory` (number): Premium: the memory the device reports, in GB.
- `mobile` (true/false): Whether it is a mobile device.
- `model` (text): The device's model.
- `operating_system` (text): The operating system and version.
- `organization` (text): Premium: the organization behind the IP.
- `proxy` (true/false): Whether the device is on a proxy, VPN or Tor.
- `reasons` (list): Premium: codes explaining the fraud chance, such as FR_BOT or FR_LOCATION_SPOOF. List device risk reasons describes each.
- `recent_abuse` (true/false): Whether the device has been tied to verified abuse in the past few days.
- `recent_data_matches` (list): How often IPQS has seen the values sent in this lookup over the last 7 days, one entry per value. Empty when it has none to report.
- `recent_unique_user_values` (list): For your own tracking variables sent with the lookup (such as a user ID), how many different values of each kind IPQS has seen with them recently. Empty when none were sent.
- `region` (text): The region or state, when known.
- `request_id` (text): IPQS's ID for this lookup. Pass it to Report fraud to report the lookup as fraudulent, or to Get past lookup to read it again.
- `ssl_fingerprint` (text): Premium: a hash of the TLS ciphers the device supports.
- `timezone` (text): The IP address's time zone, when known.
- `tor` (true/false): Whether the device is on Tor.
- `true_os` (text): Premium: the operating system the device really runs, e.g. Windows.
- `unique` (true/false): False when the device ID has been seen on several IP addresses.
- `user_agent` (text): Premium: the device's user agent.
- `vpn` (true/false): Whether the device is on a VPN.
- `webgl_hash` (text): A hash of the device's WebGL profile.

**Example output**

```json
{
  "active_tor": false,
  "active_vpn": false,
  "adblock": null,
  "bot_status": false,
  "brand": "Apple",
  "browser": "Chrome 128.0",
  "browser_fingerprint": null,
  "canvas_hash": "757a7b7455a2e163c9ca5a8bed646d87017d24a65e3531ef6910b7638d354fc6",
  "city": "Houston",
  "click_date": null,
  "connection_type": "Residential",
  "cookies": null,
  "country": "US",
  "cpu_cores": null,
  "device_id": "97bf540d96b26c3afc612df213ced691510ad714a4563a2201b65442dfa610e5",
  "device_timezone": "America/New_York",
  "first_seen": null,
  "fraud_chance": 71,
  "graphics_card": null,
  "guid": "7c02c9cb41624a34d4b1d0fddaa34198899865464f7d3a9e997486f311860a4e",
  "guid_confidence": 100,
  "high_risk_device": false,
  "hostname": null,
  "iframe_detected": null,
  "ip_address": "8.8.8.8",
  "is_crawler": false,
  "isp": "Mediacom Cable",
  "language": null,
  "last_seen": null,
  "latitude": 43.45,
  "longitude": -283.15,
  "memory": null,
  "mobile": false,
  "model": "iPad",
  "operating_system": "Mac 10.6",
  "organization": "ISP-Provider USA",
  "proxy": false,
  "reasons": [],
  "recent_abuse": false,
  "recent_data_matches": [],
  "recent_unique_user_values": [],
  "region": "Texas",
  "request_id": "0v1Vbz",
  "ssl_fingerprint": "l7koJkPziVVkZThY75b3OXIhT4qpzlcfs696wiQhsdQx1o2Sbqkr9l4t2cdrYpUh",
  "timezone": "America Matamoros",
  "tor": false,
  "true_os": null,
  "unique": false,
  "user_agent": null,
  "vpn": false,
  "webgl_hash": "034c532c2df0b5aedc169801075f56d36d15e872cc36d8b6df9b14bc0bf024ce"
}
```

### Get file scan result

Check on a malware scan that was still pending, by its request ID, and get its verdict once it has one. Costs no credits.

**Inputs**

- Scan request ID (`request_id`, text, required): The request_id Scan file for malware returned.

**Outputs**

- `detected` (true/false): Whether any engine found a virus, ransomware, trojan, spyware or other malware.
- `detected_scans` (number): How many engines found a threat.
- `engines` (list): Each of IPQS's scanning engines and what it found.
- `file_hash` (text): The file's SHA-256 hash.
- `file_name` (text): The file's name.
- `file_size` (number): The file's size in bytes.
- `file_type` (text): The file's type, e.g. application/pdf.
- `flagged_by` (list): The names of the engines that found a threat.
- `md5` (text): The file's MD5 hash.
- `request_id` (text): IPQS's ID for the scan. Pass it to Get file scan result to check on a pending scan.
- `scan_type` (text): scan for a full scan, lookup for a check of recent scans.
- `sha1` (text): The file's SHA-1 hash.
- `status` (text): The scan's status, as IPQS gives it: completed, cached (a recent scan of the same file) or pending.
- `total_scans` (number): How many engines scanned the file.
- `verdict` (text): What the scan concluded: malicious (an engine found a threat), clean (engines scanned it and none did), pending (still scanning; ask again with Get file scan result) or unknown (no engine has scanned it, as when a recent-scans lookup finds none).

**Example output**

```json
{
  "detected": true,
  "detected_scans": 1,
  "engines": [
    {
      "detected": false,
      "error": false,
      "name": "IPQS Threat Defender"
    },
    {
      "detected": true,
      "error": false,
      "name": "IPQS Emerging Threats"
    },
    {
      "detected": false,
      "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"
    }
  ],
  "file_hash": "e53c379d95e95706c5a2c4d6cd609857368a3bf14f28d7e67f6e3f8dfce6d486",
  "file_name": null,
  "file_size": null,
  "file_type": null,
  "flagged_by": [
    "IPQS Emerging Threats"
  ],
  "md5": null,
  "request_id": "H7snPYbZrb",
  "scan_type": "scan",
  "sha1": null,
  "status": "completed",
  "total_scans": 7,
  "verdict": "malicious"
}
```

### Get fraud flow results

Check how far a user got through a Fraud Flow sent with Send fraud flow, and what each step found: their form answers and the IP, email, phone, device and ID checks.

**Inputs**

- Link request ID (`link_request_id`, text, required): The link_request_id Send fraud flow returned.

**Outputs**

- `completed` (true/false): Whether the user has completed the flow.
- `flow_id` (text): The flow's ID.
- `flow_name` (text): The flow's name.
- `link_request_id` (text): The link's ID.
- `sessions` (list): Each session started from the link, oldest first.
- `state` (text): Where the user is: NOT_STARTED (the link is not opened yet), IN_PROGRESS, COMPLETED or EXPIRED, for the latest session.

**Example output**

```json
{
  "completed": true,
  "flow_id": "ABCDE12345",
  "flow_name": "Example Flow",
  "link_request_id": "BCDEF23456",
  "sessions": [
    {
      "results": [
        {
          "details": {},
          "form_data": {
            "field1": "value1",
            "field2": "value2"
          },
          "request_date": "2026-01-01 12:00:00",
          "request_id": "CDEFG34567",
          "request_type": "CUSTOM_FORM",
          "success": true
        },
        {
          "details": {},
          "form_data": {},
          "request_date": "2026-01-01 12:00:00",
          "request_id": "DEFGH45678",
          "request_type": "PROXY_VPN",
          "success": true
        },
        {
          "details": {},
          "form_data": {
            "field3": "value1"
          },
          "request_date": "2026-01-01 12:00:00",
          "request_id": "EFGHI56789",
          "request_type": "CUSTOM_FORM",
          "success": true
        }
      ],
      "state": "COMPLETED"
    }
  ],
  "state": "COMPLETED"
}
```

### Get IP abuse feed

Get the IP addresses IPQS has recently seen in bot attacks, credential stuffing, brute forcing, proxies and other abuse, from its IP Address Abuse Feed, for a time range, to block them at your firewall. The New range gets only what is new since you last asked. The feed is a separate IPQS product: ask IPQS for access.

**Inputs**

- Time range (`time_range`, text): Which entries to get. One of: `latest` (The newest entry), `new` (Everything new since this key last asked for new entries), `hour` (Since the start of the current hour), `last24hours` (The last 24 hours), `today` (Today, from midnight UTC), `yesterday` (Yesterday, midnight to midnight UTC), `week` (This week, from Sunday midnight UTC), `month` (This month, from the 1st at midnight UTC), `custom` (Between two dates). Default: `latest`.
- Start date (`start_date`, date): For a custom range, its first day.
- End date (`end_date`, date): For a custom range, its last day.
- Maximum entries (`limit`, number): The most entries to return, up to 10,000. From 1 to 10000. Default: `1000`.

**Outputs**

- `count` (number): How many came back.
- `entries` (list): The abusive IP addresses, up to the maximum asked for.
- `time_range` (text): The time range asked for.
- `total` (number): How many entries the feed had for the range.
- `truncated` (true/false): Whether there were more entries than the maximum, so some were left out.

**Example output**

```json
{
  "count": 2,
  "entries": [
    {
      "abuse_events": [
        {
          "last_seen": "2026-10-02T04:40:34-04:00",
          "name": "Brute Force Attacks"
        },
        {
          "last_seen": "2026-10-01T22:10:02-04:00",
          "name": "VPN Networks"
        }
      ],
      "abuse_velocity": "high",
      "active_tor": false,
      "active_vpn": true,
      "asn": 64500,
      "city": "Ashburn",
      "connection_type": "Data Center",
      "country_code": "US",
      "dynamic_ip": false,
      "fraud_score": 100,
      "frequent_abuser": true,
      "hostname": "host-23.example.net",
      "ip_address": "198.51.100.23",
      "is_bot": true,
      "is_crawler": false,
      "is_proxy": true,
      "is_tor": false,
      "is_vpn": true,
      "isp": "Example Hosting",
      "latitude": 39.04,
      "longitude": -77.49,
      "organization": "Example Hosting",
      "public_access_point": false,
      "recent_abuse": true,
      "region": "Virginia",
      "shared_ip": false,
      "timezone": "America/New_York",
      "zip_code": null
    },
    {
      "abuse_events": [
        {
          "last_seen": "2026-10-02T03:00:00-04:00",
          "name": "Bot Attacks"
        }
      ],
      "abuse_velocity": "medium",
      "active_tor": false,
      "active_vpn": false,
      "asn": null,
      "city": "Berlin",
      "connection_type": "Residential",
      "country_code": "DE",
      "dynamic_ip": true,
      "fraud_score": 88,
      "frequent_abuser": false,
      "hostname": null,
      "ip_address": "203.0.113.77",
      "is_bot": false,
      "is_crawler": false,
      "is_proxy": true,
      "is_tor": false,
      "is_vpn": false,
      "isp": "Example Telecom",
      "latitude": 52.52,
      "longitude": 13.4,
      "organization": null,
      "public_access_point": false,
      "recent_abuse": true,
      "region": "Berlin",
      "shared_ip": false,
      "timezone": "Europe/Berlin",
      "zip_code": "10115"
    }
  ],
  "time_range": "last24hours",
  "total": 2,
  "truncated": false
}
```

### Get login history

List the logins and login attempts to your IPQS account, with where each came from and its fraud score, to audit access. IPQS enables this API on request: ask its support to turn it on.

**Inputs**: None.

**Outputs**

- `count` (number): How many came back.
- `logins` (list): Each login and login attempt.
- `request_id` (text): IPQS's ID for this lookup. Pass it to Report fraud to report the lookup as fraudulent, or to Get past lookup to read it again.
- `total` (number): How many logins IPQS has on record.

**Example output**

```json
{
  "count": 1,
  "logins": [
    {
      "attempts": 0,
      "browser": "Mozilla/5.0",
      "country_code": "US",
      "deleted": false,
      "email": "user@gmail.com",
      "fraud_score": 7.0,
      "hostname": "syn-096-041-136-092.res.spectrum.com",
      "id": "31656582",
      "ip_address": "192.0.2.55",
      "isp": "Spectrum",
      "logged_in_at": "2025-05-30T04:05:34Z",
      "successful": true,
      "user_id": "123456",
      "validated": true
    }
  ],
  "request_id": "aNjZAE7P8g",
  "total": 1
}
```

### Get past lookup

Get a past IP, email or device fingerprint lookup again, by its request ID, or the latest one made with given custom variables, with everything IPQS answered at the time. Costs no credits.

**Inputs**

- Request ID (`request_id`, text): The lookup's request_id, as an earlier step returned it. Leave it empty to find the lookup by its custom variables instead.
- Lookup type (`lookup_type`, text): Which lookups to search when finding one by its custom variables. One of: `proxy` (IP address checks), `email` (Email address checks), `devicetracker` (Device fingerprints (website)), `mobiletracker` (Device fingerprints (mobile app)).
- Find by custom variables (`find_by`, object): Instead of a request ID, the custom variables the lookup was made with, such as userID, to find the latest lookup that has them.

**Outputs**

- `lookup` (object): The past lookup, with the fields its API answered with at the time: fraud_score, country_code, ISP and the rest for an IP check, valid and deliverability for an email check, and so on, in IPQS's own names.
- `request_id` (text): The lookup's request ID.

**Example output**

```json
{
  "lookup": {
    "ASN": 30036,
    "IP": "192.0.2.110",
    "ISP": "Mediacom Cable",
    "abuse_velocity": "medium",
    "active_tor": false,
    "active_vpn": false,
    "bot_status": false,
    "city": "Houston",
    "connection_type": "Residential",
    "country_code": "US",
    "fraud_score": 25,
    "host": "192-0-2-110.client.mchsi.com",
    "is_crawler": false,
    "latitude": 29.7079,
    "longitude": -95.401,
    "mobile": false,
    "organization": "Mediacom Cable",
    "proxy": false,
    "recent_abuse": true,
    "region": "Texas",
    "request_id": "0w8WYS",
    "timezone": "America Matamoros",
    "tor": false,
    "vpn": false,
    "zip_code": "77001"
  },
  "request_id": "0w8WYS"
}
```

### List allowlist

List everything on the account's allowlist.

**Inputs**

- Applies to (`lookup_type`, text): Only the entries for these lookups. Leave empty for all. One of: `proxy` (IP address checks), `email` (Email address checks), `phone` (Phone number checks), `url` (URL scans), `devicetracker` (Device fingerprints (website)), `mobiletracker` (Device fingerprints (mobile app)).

**Outputs**

- `count` (number): How many came back.
- `entries` (list): The entries on the list.
- `request_id` (text): IPQS's ID for this listing.

**Example output**

```json
{
  "count": 1,
  "entries": [
    {
      "lookup_type": "proxy",
      "reason": null,
      "value": "1.1.1.1",
      "value_type": "ip"
    }
  ],
  "request_id": "CXSSHXFZr5"
}
```

### List blocklist

List everything on the account's blocklist.

**Inputs**

- Applies to (`lookup_type`, text): Only the entries for these lookups. Leave empty for all. One of: `proxy` (IP address checks), `email` (Email address checks), `phone` (Phone number checks), `url` (URL scans), `devicetracker` (Device fingerprints (website)), `mobiletracker` (Device fingerprints (mobile app)).

**Outputs**

- `count` (number): How many came back.
- `entries` (list): The entries on the list.
- `request_id` (text): IPQS's ID for this listing.

**Example output**

```json
{
  "count": 1,
  "entries": [
    {
      "lookup_type": "proxy",
      "reason": null,
      "value": "1.1.1.1",
      "value_type": "ip"
    }
  ],
  "request_id": "CXSSHXFZr5"
}
```

### List bulk validations

List the account's bulk validations, newest first, 50 a page, with each one's status.

**Inputs**

- List type (`list_type`, text): Only lists of this kind. Leave empty for all. One of: `email` (Email addresses), `phone` (Phone numbers), `proxy` (IP addresses), `url` (URLs).
- Page (`page`, number): Which page. Page 1 is the newest. At least 1. Default: `1`.

**Outputs**

- `bulk_validations` (list): The bulk validations on this page, newest first.
- `count` (number): How many came back.
- `has_more` (true/false): Whether there is a later page.
- `page` (number): This page's number.
- `request_id` (text): IPQS's ID for this request.
- `total` (number): How many there are in all.
- `total_pages` (number): How many pages there are in all.

**Example output**

```json
{
  "bulk_validations": [
    {
      "aborted": false,
      "file_name": "example_email.csv",
      "finished": false,
      "id": 827748,
      "invalid_records": 0,
      "list_type": "email",
      "status": "NEW",
      "strictness": 0
    }
  ],
  "count": 1,
  "has_more": false,
  "page": 1,
  "request_id": "HDzXqjnJZ9",
  "total": 1,
  "total_pages": 1
}
```

### List countries

List the two-letter country codes IPQS uses, with each country's name, to turn a code from a lookup into a name. Free, and needs no credits.

**Inputs**: None.

**Outputs**

- `count` (number): How many came back.
- `countries` (list): Every country IPQS knows.

**Example output**

```json
{
  "count": 5,
  "countries": [
    {
      "code": "US",
      "name": "United States"
    },
    {
      "code": "CA",
      "name": "Canada"
    },
    {
      "code": "GB",
      "name": "United Kingdom"
    },
    {
      "code": "AF",
      "name": "Afghanistan"
    },
    {
      "code": "AX",
      "name": "Aland Islands"
    }
  ]
}
```

### List device risk reasons

List the reason codes a device fingerprint result can carry, such as FR_BOT, with what each means. Free, and needs no credits.

**Inputs**: None.

**Outputs**

- `count` (number): How many came back.
- `reasons` (list): Every reason code and what it means.

**Example output**

```json
{
  "count": 5,
  "reasons": [
    {
      "code": "FR_RECENT_ABUSE",
      "description": "User has engaged in recent abuse"
    },
    {
      "code": "FR_DEVICE_ABUSE",
      "description": "This device has engaged in recent abuse across the IPQS network"
    },
    {
      "code": "FR_MALICIOUS",
      "description": "Malicious browser settings detected"
    },
    {
      "code": "FR_BROWSER_SETTINGS",
      "description": "Abnormal browser settings detected"
    },
    {
      "code": "FR_SUSPECT_BROWSER",
      "description": "Suspicious browser configuration"
    }
  ]
}
```

### List past lookups

List your past lookups of one kind (IP checks, email or phone checks, URL or file scans, device fingerprints or leak checks) from a date range, newest first, up to 250 a page. Narrow them by IP address, device, fraud score or custom variables, to review a user's history or export results.

**Inputs**

- Lookup type (`lookup_type`, text, required): Which lookups to list. One of: `proxy` (IP address checks), `email` (Email address checks), `phone` (Phone number checks), `url` (URL scans), `devicetracker` (Device fingerprints (website)), `mobiletracker` (Device fingerprints (mobile app)), `malware_scan` (File scans), `leaked_email` (Email leak checks), `leaked_username` (Username leak checks), `leaked_password` (Password leak checks).
- Start date (`start_date`, date): Only from this day on. A week ago by default.
- End date (`end_date`, date): Only up to this day.
- IP address (`ip_address`, text): Only lookups of this IP address (IP checks and device fingerprints only).
- Device ID (`device_id`, text): Only device fingerprints of this device.
- Tracker ID (`tracker_id`, number): The device tracker's number, from IPQS's tracker settings, to search that tracker only. At least 1.
- Minimum fraud score (`min_fraud_score`, number): Only lookups scoring at least this, 0 to 100. From 0 to 100.
- Maximum fraud score (`max_fraud_score`, number): Only lookups scoring at most this, 0 to 100. From 0 to 100.
- Custom variables (`find_by`, object): Only lookups made with these custom variables, such as a userID.
- Page (`page`, number): Which page of lookups. Page 1 is the newest. At least 1. Default: `1`.
- Lookups per page (`limit`, number): How many lookups a page holds, up to 250. From 1 to 250. Default: `25`.

**Outputs**

- `count` (number): How many came back.
- `has_more` (true/false): Whether there is a later page.
- `lookups` (list): The past lookups on this page, each with the fields its API answered with, in IPQS's own names, request_id among them.
- `page` (number): This page's number.
- `per_page` (number): How many lookups a page holds.
- `request_id` (text): IPQS's ID for this listing.
- `total` (number): How many lookups match in all.
- `total_pages` (number): How many pages there are in all.

**Example output**

```json
{
  "count": 1,
  "has_more": false,
  "lookups": [
    {
      "ASN": "15169",
      "ISP": "Google",
      "bot_status": true,
      "city": "Mountain View",
      "country_code": "US",
      "fraud_score": 100,
      "host": "dns.google",
      "is_crawler": false,
      "latitude": 37.41,
      "longitude": -122.08,
      "mobile": false,
      "organization": "Google",
      "proxy": true,
      "recent_abuse": true,
      "region": "California",
      "request_id": "4JAer3sX6rH3Xl",
      "timezone": "America/Chicago",
      "tor": false,
      "transaction_details": [],
      "vpn": true
    }
  ],
  "page": 1,
  "per_page": 25,
  "request_id": "4JAer3sX6rH3bk",
  "total": 1,
  "total_pages": 1
}
```

### List transaction risk reasons

List the reason codes transaction scoring can give, such as TR_SUSPECT_EMAIL, with what each means. Free, and needs no credits.

**Inputs**: None.

**Outputs**

- `count` (number): How many came back.
- `reasons` (list): Every reason code and what it means.

**Example output**

```json
{
  "count": 5,
  "reasons": [
    {
      "code": "TR_SUSPECT_IP",
      "description": "IP address recently engaged in suspicious behavior."
    },
    {
      "code": "TR_ABUSIVE_IP",
      "description": "IP address is frequently associated with abusive behavior."
    },
    {
      "code": "TR_SKIPPED_IP",
      "description": "IP address was previously associated with suspicious activity."
    },
    {
      "code": "TR_EMAIL_SWAP",
      "description": "User is switching their email address."
    },
    {
      "code": "TR_BILLING_SWAP",
      "description": "User is switching their billing details."
    }
  ]
}
```

### Remove from allowlist

Take a value off the account's allowlist.

**Inputs**

- Applies to (`lookup_type`, text, required): Which lookups the entry applies to. One of: `proxy` (IP address checks), `email` (Email address checks), `phone` (Phone number checks), `url` (URL scans), `devicetracker` (Device fingerprints (website)), `mobiletracker` (Device fingerprints (mobile app)).
- Value (`value`, text, required): The value: an IP address, a CIDR range like 203.0.113.0/24, an ISP name, a device ID, an email address, a domain or a phone number, to suit what it applies to.
- Value type (`value_type`, text): What kind of value it is. Leave it empty to work it out: an IP address or range, and for IP checks anything else as an ISP name. Choose it for a device ID. One of: `ip` (IP address), `cidr` (IP range (CIDR)), `isp` (ISP name), `deviceid` (Device ID), `email` (Email address), `domain`, `phone` (Phone number).

**Outputs**

- `lookup_type` (text): Which lookups the entry applies to: proxy (IP addresses), email, phone, url, devicetracker or mobiletracker.
- `message` (text): IPQS's confirmation, in its words.
- `reason` (text): The reason given, when one was.
- `request_id` (text): IPQS's ID for this change.
- `value` (text): The value, as it was sent.
- `value_type` (text): What kind of value it is: ip, cidr, isp, deviceid, vendorid, email, domain or phone.

**Example output**

```json
{
  "lookup_type": "proxy",
  "message": "Successfully deleted Allow List entry.",
  "reason": null,
  "request_id": "CXScW08shC",
  "value": "1.1.1.1",
  "value_type": "ip"
}
```

### Remove from blocklist

Take a value off the account's blocklist.

**Inputs**

- Applies to (`lookup_type`, text, required): Which lookups the entry applies to. One of: `proxy` (IP address checks), `email` (Email address checks), `phone` (Phone number checks), `url` (URL scans), `devicetracker` (Device fingerprints (website)), `mobiletracker` (Device fingerprints (mobile app)).
- Value (`value`, text, required): The value: an IP address, a CIDR range like 203.0.113.0/24, an ISP name, a device ID, an email address, a domain or a phone number, to suit what it applies to.
- Value type (`value_type`, text): What kind of value it is. Leave it empty to work it out: an IP address or range, and for IP checks anything else as an ISP name. Choose it for a device ID or a mobile app's vendor ID. One of: `ip` (IP address), `cidr` (IP range (CIDR)), `isp` (ISP name), `deviceid` (Device ID), `email` (Email address), `domain`, `phone` (Phone number), `vendorid` (Mobile app vendor device ID).

**Outputs**

- `lookup_type` (text): Which lookups the entry applies to: proxy (IP addresses), email, phone, url, devicetracker or mobiletracker.
- `message` (text): IPQS's confirmation, in its words.
- `reason` (text): The reason given, when one was.
- `request_id` (text): IPQS's ID for this change.
- `value` (text): The value, as it was sent.
- `value_type` (text): What kind of value it is: ip, cidr, isp, deviceid, vendorid, email, domain or phone.

**Example output**

```json
{
  "lookup_type": "email",
  "message": "Successfully deleted Block List entry.",
  "reason": null,
  "request_id": "CXScW08shC",
  "value": "fraud.signup@example.com",
  "value_type": "email"
}
```

### Report fraud

Report an IP address, email address, phone number or past lookup as fraudulent, so IPQS trains your account's scoring on it, such as after a chargeback or a fake sign up. Give one or more; each is reported on its own. Something already reported comes back as already reported, not as an error. Only report data that is very likely abusive.

**Inputs**

- IP address (`ip_address`, text): An IP address to report.
- Email address (`email`, text): An email address to report.
- Phone number (`phone_number`, text): A phone number to report, with Country below.
- Country (`country`, text): The phone number's country, as a two-letter code like US. Required with a phone number.
- Request ID (`request_id`, text): A past lookup's request_id, to report the lookup.

**Outputs**

- `already_reported_count` (number): How many it already had.
- `reported_count` (number): How many reports IPQS took.
- `reports` (list): One report for each value given.

**Example output**

```json
{
  "already_reported_count": 0,
  "reported_count": 1,
  "reports": [
    {
      "already_reported": false,
      "reported": true,
      "reported_as": "email",
      "request_id": "3ift1wF",
      "value": "fraud.signup@example.com"
    }
  ]
}
```

### Scan file for malware

Scan a file for viruses, ransomware, trojans, spyware and other malware with IPQS's scanning engines, in a live sandbox, and wait for the verdict: malicious, clean, pending or unknown, with each engine's finding. Each scan costs 10 credits. Good for checking email attachments and uploads before anyone opens them.

**Inputs**

- File (`file`, text, required): The file to scan: upload one, pick a file from an earlier step, or give a link to one for IPQS to fetch. Files up to 100 MB.
- Recent scans only (`recent_scans_only`, true/false): Only look for a scan of the same file in the last 24 hours, for an instant answer, instead of scanning it now. The verdict is unknown when there is none. Default: `false`.
- Wait for the verdict (`wait_seconds`, number): How many seconds to wait for a full scan's verdict, checking every 15 seconds, up to 600. A full scan usually takes a few minutes. A scan still running when the wait ends comes back pending, with its request ID for Get file scan result. From 0 to 600. Default: `120`.

**Outputs**

- `detected` (true/false): Whether any engine found a virus, ransomware, trojan, spyware or other malware.
- `detected_scans` (number): How many engines found a threat.
- `engines` (list): Each of IPQS's scanning engines and what it found.
- `file_hash` (text): The file's SHA-256 hash.
- `file_name` (text): The file's name.
- `file_size` (number): The file's size in bytes.
- `file_type` (text): The file's type, e.g. application/pdf.
- `flagged_by` (list): The names of the engines that found a threat.
- `md5` (text): The file's MD5 hash.
- `request_id` (text): IPQS's ID for the scan. Pass it to Get file scan result to check on a pending scan.
- `scan_type` (text): scan for a full scan, lookup for a check of recent scans.
- `sha1` (text): The file's SHA-1 hash.
- `status` (text): The scan's status, as IPQS gives it: completed, cached (a recent scan of the same file) or pending.
- `total_scans` (number): How many engines scanned the file.
- `verdict` (text): What the scan concluded: malicious (an engine found a threat), clean (engines scanned it and none did), pending (still scanning; ask again with Get file scan result) or unknown (no engine has scanned it, as when a recent-scans lookup finds none).

**Example output**

```json
{
  "detected": true,
  "detected_scans": 1,
  "engines": [
    {
      "detected": false,
      "error": false,
      "name": "IPQS Threat Defender"
    },
    {
      "detected": true,
      "error": false,
      "name": "IPQS Emerging Threats"
    },
    {
      "detected": false,
      "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"
    }
  ],
  "file_hash": "e53c379d95e95706c5a2c4d6cd609857368a3bf14f28d7e67f6e3f8dfce6d486",
  "file_name": "invoice.pdf",
  "file_size": null,
  "file_type": null,
  "flagged_by": [
    "IPQS Emerging Threats"
  ],
  "md5": null,
  "request_id": "H7snPYbZrb",
  "scan_type": "scan",
  "sha1": null,
  "status": "completed",
  "total_scans": 7,
  "verdict": "malicious"
}
```

### Scan URL

Scan a link or a domain for phishing, malware, spam, parked domains and adult content, with a risk score from 0 to 100, where it redirects to, the site's category, server, domain age and DNS records. IPQS loads the page itself, so nothing is opened from Lodol. A risk score of 100 is confirmed abuse.

**Inputs**

- URL (`url`, text, required): The link or domain to scan, e.g. https://example.com/login or example.com.
- Strictness (`strictness`, number): How strict the check is, 0 to 2. IPQS recommends starting at 0; stricter checks flag more, honest ones included. From 0 to 2. Default: `0`.
- Timeout (`timeout`, number): How many seconds to spend loading the page and following its redirects, 1 to 10; 2 by default. IPQS suggests 5 when the answer is not needed at once. From 1 to 10. Default: `2`.
- Fast (`fast`, true/false): Use lighter checks for a quicker answer. Default: `false`.
- Custom variables (`custom_variables`, object): Your own tracking variables to record with the lookup, such as userID or transactionID, so you can find it again in your history and IPQS can spot patterns per user. Each must first be set up in your IPQS account settings.

**Outputs**

- `a_records` (list): The domain's A (address) records.
- `adult` (true/false): Whether the site hosts dating or adult content.
- `category` (text): What the site is about, one of over 70 categories such as Video Streaming, Gaming, Advertising, Hacking, Malicious or Phishing. Null when unknown.
- `content_type` (text): The page's MIME type, e.g. text/html; charset=UTF-8. Null when unknown.
- `country_code` (text): Two-letter code of the country the server is in.
- `dmarc_record` (true/false): Whether the domain has a proper DMARC record.
- `dns_valid` (true/false): Whether the domain has valid DNS records.
- `domain` (text): The domain of the final address, with any subdomain.
- `domain_age` (object): When the domain was registered. Its fields are null when unknown.
- `domain_rank` (number): The site's estimated popularity rank worldwide, 0 when unranked or little visited.
- `domain_trust` (text): How trustworthy the domain is from its history: trusted, positive, neutral, suspicious, malicious or not rated.
- `final_url` (text): Where the address led after every redirect.
- `hosted_content` (true/false): Whether the page is on a free hosting service such as Weebly or Blogspot, which abusers favor.
- `ip_address` (text): The IP address of the site's server.
- `language_code` (text): Two-letter code of the language the page is written in.
- `malware` (true/false): Whether the address is tied to malware or viruses.
- `mx_records` (list): The domain's MX (mail server) records.
- `ns_records` (list): The domain's NS (name server) records.
- `page_size` (number): The size of the page in bytes, 0 when it could not be reached.
- `page_title` (text): The page's title.
- `parking` (true/false): Whether the domain is parked with a for sale notice.
- `phishing` (true/false): Whether the address is tied to phishing.
- `redirected` (true/false): Whether the address redirects to another domain in a browser.
- `request_id` (text): IPQS's ID for this lookup. Pass it to Report fraud to report the lookup as fraudulent, or to Get past lookup to read it again.
- `risk_score` (number): IPQS's risk score for the address, 0 to 100. 85 and above is high risk, and 100 is confirmed phishing, malware or similar abuse.
- `risky_tld` (true/false): Whether the domain ends in a top-level domain often used for malware, scams or phishing.
- `root_domain` (text): The domain of the final address without its subdomains.
- `scanned_url` (text): The address that was scanned, before any redirects.
- `server` (text): The server's banner, e.g. nginx/1.16.0. Null when unknown.
- `short_link_redirect` (true/false): Whether the address uses a link shortener, or its path redirected.
- `spamming` (true/false): Whether the domain is tied to email spam or abusive email addresses.
- `spf_record` (true/false): Whether the domain has a proper SPF record.
- `status_code` (number): The HTTP status the page answered with: 200 for a working page, 0 when it could not be reached.
- `suspicious` (true/false): Whether the address is suspected of phishing or other abuse.
- `technologies` (list): Technologies found on the page, such as WordPress, Shopify, Cloudflare or Google Analytics.
- `unsafe` (true/false): Whether the site is suspected to be unsafe: phishing, malware, spam or other abuse. risk_score says how confident IPQS is.

**Example output**

```json
{
  "a_records": [
    "172.67.151.40",
    "104.21.72.140"
  ],
  "adult": false,
  "category": "Search Engine",
  "content_type": "text/html; charset=UTF-8",
  "country_code": "US",
  "dmarc_record": true,
  "dns_valid": true,
  "domain": "google.com",
  "domain_age": {
    "human": "26 years ago",
    "iso": "1997-09-15T00:00:00-04:00",
    "timestamp": 874296000
  },
  "domain_rank": 1,
  "domain_trust": "trusted",
  "final_url": "http://google.com",
  "hosted_content": false,
  "ip_address": "172.217.7.206",
  "language_code": "EN",
  "malware": false,
  "mx_records": [
    "us-smtp-inbound-1.mimecast.com",
    "aspmx.l.google.com"
  ],
  "ns_records": [
    "finley.ns.cloudflare.com",
    "melinda.ns.cloudflare.com"
  ],
  "page_size": 68553,
  "page_title": "Google",
  "parking": false,
  "phishing": false,
  "redirected": false,
  "request_id": "4ZGSfWu9RDf3oH",
  "risk_score": 0,
  "risky_tld": false,
  "root_domain": "google.com",
  "scanned_url": "http://google.com",
  "server": "nginx",
  "short_link_redirect": false,
  "spamming": false,
  "spf_record": true,
  "status_code": 200,
  "suspicious": false,
  "technologies": [
    "Google Tag Manager",
    "Google Ads",
    "WordPress",
    "Shopify",
    "Cloudflare"
  ],
  "unsafe": false
}
```

### Score transaction

Score how risky a payment, order or new user is from whatever details you have: billing and shipping names, addresses, emails and phones, the card's BIN and last four, the order amount, the username and password. Returns a risk score, a recommended action (approve, review, 3ds or deny), the reasons, and checks of each detail. IPQS scores the transaction beside a check of the customer's IP address, email address or phone number, so give at least one of those (only some plans can do without); every other field is optional, and the more you give the better.

**Inputs**

- IP address (`ip_address`, text): The customer's IP address. With it IPQS scores the address too, and measures how far it is from the billing and shipping addresses.
- Billing first name (`billing_first_name`, text): The customer's first name, as billed.
- Billing last name (`billing_last_name`, text): The customer's last name, as billed.
- Billing company (`billing_company`, text): The billing company, if any.
- Billing email (`billing_email`, text): The customer's email address. Only lightly checked here.
- Billing phone (`billing_phone`, text): The customer's phone number, with its country code, e.g. 18007132618.
- Billing address line 1 (`billing_address_1`, text): The first line of the billing street address.
- Billing address line 2 (`billing_address_2`, text): The second line of the billing street address.
- Billing city (`billing_city`, text): The billing city.
- Billing region (`billing_region`, text): The billing state or region, e.g. FL.
- Billing postal code (`billing_postcode`, text): The billing ZIP or postal code.
- Billing country (`billing_country`, text): The billing country, as a name or a two-letter code like US.
- Shipping first name (`shipping_first_name`, text): The first name the order ships to.
- Shipping last name (`shipping_last_name`, text): The last name the order ships to.
- Shipping company (`shipping_company`, text): The company the order ships to, if any.
- Shipping email (`shipping_email`, text): The email address for the shipment.
- Shipping phone (`shipping_phone`, text): The phone number for the shipment, with its country code.
- Shipping address line 1 (`shipping_address_1`, text): The first line of the shipping street address.
- Shipping address line 2 (`shipping_address_2`, text): The second line of the shipping street address.
- Shipping city (`shipping_city`, text): The shipping city.
- Shipping region (`shipping_region`, text): The shipping state or region, e.g. FL.
- Shipping postal code (`shipping_postcode`, text): The shipping ZIP or postal code.
- Shipping country (`shipping_country`, text): The shipping country, as a name or a two-letter code like US.
- Username (`username`, text): The customer's username on your site.
- Password (`password`, text): The customer's password, to check against leaked credentials. It is hashed with SHA-256 before it leaves Lodol, and a SHA-256 hash is sent as it is.
- Order amount (`order_amount`, text): The order's total, without a currency symbol, e.g. 49.99.
- Order quantity (`order_quantity`, number): How many items the order has. At least 0.
- Payment method (`transaction_type`, text): How the customer is paying. One of: `credit_card` (Credit or debit card), `paypal`, `stripe`, `google` (Google Pay), `apple` (Apple Pay), `cash_app` (Cash App), `venmo`, `zelle`, `square`, `shopify`, and 14 more.
- Card BIN (`credit_card_bin`, text): The first 6 or 8 digits of the card number. Never the whole number.
- Card last four (`credit_card_last_four`, text): The card number's last 4 digits.
- Card expiry month (`credit_card_expiration_month`, number): The card's expiry month, 1 to 12. From 1 to 12.
- Card expiry year (`credit_card_expiration_year`, number): The card's expiry year, e.g. 2030 or 30. From 0 to 2099.
- AVS code (`avs_code`, text): The one-letter address verification code from the card's bank, or pass or fail.
- CVV result code (`cvv_code`, text): The one-letter CVV verification code from the card's bank, or pass or fail. Never the CVV itself.
- Account number (`account_number`, text): A bank account, SEPA or crypto wallet number. Never a card number, which is refused.
- Routing number (`routing_number`, text): The bank's routing number.
- Recurring (`recurring`, true/false): Whether the order rebills automatically.
- Times rebilled (`recurring_times`, number): For a recurring order, which billing this is: 1 for the first. At least 1.
- Transaction strictness (`transaction_strictness`, number): How heavily to weigh irregularities in the details, 0 to 2. Only with an IP address. From 0 to 2.
- Custom variables (`custom_variables`, object): Your own tracking variables to record with the lookup, such as userID or transactionID, so you can find it again in your history and IPQS can spot patterns per user. Each must first be set up in your IPQS account settings.

**Outputs**

- `address_email_identity_match` (text): Enterprise feature: whether the billing address and email address belong to the same person: Match, No Match (they could not be paired), Mismatch (they belong to someone else) or Unknown (not checked).
- `avs` (text): The address verification (AVS) code the card's bank answered with.
- `avs_match_found` (true/false): Whether the AVS code is one that means the address matched: A, B, D, M, P, X or Y.
- `billing_address_distance` (object): How far the billing address is from where the IP address is. Its fields are null when either is unknown.
- `billing_phone_carrier` (text): The billing phone number's carrier, e.g. AT&T.
- `billing_phone_country` (text): Two-letter code of the billing phone number's country.
- `billing_phone_country_code` (number): The billing phone number's dialing code, e.g. 1.
- `billing_phone_line_type` (text): The billing phone number's line type, e.g. Wireless, Landline or VOIP.
- `bin_bank_name` (text): The bank or processor that issued the card, from its BIN.
- `bin_country` (text): The country of the card's issuer, from its BIN.
- `bin_type` (text): The kind of card, from its BIN: Credit, Debit, Prepaid or Virtual. Prepaid and virtual cards carry slightly more risk.
- `cvv` (text): The card verification (CVV) code the card's bank answered with.
- `cvv_match_found` (true/false): Whether the CVV code is one that means it matched: A, B, M, P, X or Y.
- `email_name_identity_match` (text): Enterprise feature: whether the billing email address and the name belong to the same person: Match, No Match (they could not be paired), Mismatch (they belong to someone else) or Unknown (not checked).
- `fraudulent_behavior` (true/false): Whether the details show high risk patterns and a high chance of fraud.
- `high_risk_billing_address` (true/false): Enterprise feature: whether IPQS flags the billing address, such as a drop shipper, a package forwarder or an empty lot.
- `high_risk_shipping_address` (true/false): Enterprise feature: whether IPQS flags the shipping address, such as a drop shipper, a package forwarder or an empty lot.
- `is_prepaid_card` (true/false): Whether the card is prepaid.
- `leaked_billing_email` (true/false): Whether the billing email address was in a recent data breach.
- `leaked_shipping_email` (true/false): Whether the shipping email address was in a recent data breach.
- `leaked_user_data` (true/false): Whether the customer's details, phone and address included, were in a recent data breach.
- `name_address_identity_match` (text): Enterprise feature: whether the name and the billing address belong to the same person: Match, No Match (they could not be paired), Mismatch (they belong to someone else) or Unknown (not checked).
- `phone_address_identity_match` (text): Enterprise feature: whether the billing phone number and address belong to the same person: Match, No Match (they could not be paired), Mismatch (they belong to someone else) or Unknown (not checked).
- `phone_email_identity_match` (text): Enterprise feature: whether the billing phone number and email address belong to the same person: Match, No Match (they could not be paired), Mismatch (they belong to someone else) or Unknown (not checked).
- `phone_name_identity_match` (text): Enterprise feature: whether the billing phone number and the name belong to the same person: Match, No Match (they could not be paired), Mismatch (they belong to someone else) or Unknown (not checked).
- `recent_data_matches` (list): How often IPQS has seen the values sent in this lookup over the last 7 days, one entry per value. Empty when it has none to report.
- `recent_unique_user_values` (list): For your own tracking variables sent with the lookup (such as a user ID), how many different values of each kind IPQS has seen with them recently. Empty when none were sent.
- `recommended_action` (text): What IPQS recommends doing, from the risk score or your own transaction rules: approve, review, 3ds (ask for 3-D Secure) or deny. By default up to 75 approves, 75 to 85 reviews, 85 to 95 asks for 3-D Secure and above 95 denies.
- `request_id` (text): IPQS's ID for this lookup. Pass it to Report fraud to report the lookup as fraudulent, or to Get past lookup to read it again.
- `results` (object): The full checks behind the score, as the dedicated actions return them. A check that was not run has every field null.
- `risk_factors` (list): Why the risk score is raised, in IPQS's words, e.g. Suspicious billing email address reputation.
- `risk_score` (number): IPQS's risk score for the transaction or user, 0 to 100. 75 and above is suspicious and 90 and above is high risk. It leans less on the IP address than an IP check's fraud score does.
- `risky_billing_phone` (true/false): Whether the billing phone number is tied to abuse.
- `risky_shipping_phone` (true/false): Whether the shipping phone number is tied to abuse.
- `risky_username` (true/false): Whether the username is often tied to fraud.
- `shipping_address_distance` (object): How far the shipping address is from where the IP address is. Its fields are null when either is unknown.
- `shipping_phone_carrier` (text): The shipping phone number's carrier.
- `shipping_phone_country` (text): Two-letter code of the shipping phone number's country.
- `shipping_phone_country_code` (number): The shipping phone number's dialing code.
- `shipping_phone_line_type` (text): The shipping phone number's line type.
- `user_activity` (text): How often this customer makes legitimate purchases and sign ups: high, medium, low or none. Higher plans only.
- `user_flagged_billing_address` (true/false): Enterprise feature: whether the billing address is on your own blocklist.
- `user_flagged_shipping_address` (true/false): Enterprise feature: whether the shipping address is on your own blocklist.
- `valid_billing_address` (true/false): Whether the billing address is valid and has a good reputation.
- `valid_billing_email` (true/false): A light check of the billing email address. Validate email address checks one in depth.
- `valid_billing_phone` (true/false): Whether the billing phone number is valid and active with its carrier.
- `valid_shipping_address` (true/false): Whether the shipping address is valid and has a good reputation.
- `valid_shipping_email` (true/false): A light check of the shipping email address.
- `valid_shipping_phone` (true/false): Whether the shipping phone number is valid and active with its carrier.

**Example output**

```json
{
  "address_email_identity_match": "Enterprise plan required.",
  "avs": null,
  "avs_match_found": null,
  "billing_address_distance": {
    "kilometers": null,
    "miles": null
  },
  "billing_phone_carrier": null,
  "billing_phone_country": null,
  "billing_phone_country_code": null,
  "billing_phone_line_type": "Unknown",
  "bin_bank_name": null,
  "bin_country": null,
  "bin_type": null,
  "cvv": null,
  "cvv_match_found": null,
  "email_name_identity_match": "Enterprise plan required.",
  "fraudulent_behavior": false,
  "high_risk_billing_address": false,
  "high_risk_shipping_address": null,
  "is_prepaid_card": null,
  "leaked_billing_email": true,
  "leaked_shipping_email": false,
  "leaked_user_data": true,
  "name_address_identity_match": "Enterprise plan required.",
  "phone_address_identity_match": "Enterprise plan required.",
  "phone_email_identity_match": "Enterprise plan required.",
  "phone_name_identity_match": "Enterprise plan required.",
  "recent_data_matches": [],
  "recent_unique_user_values": [],
  "recommended_action": "3ds",
  "request_id": "lIUyaAnYku",
  "results": {
    "billing_email": {
      "a_records": [
        "172.66.147.243",
        "104.20.23.154"
      ],
      "associated_names": {
        "names": [],
        "status": "Enterprise Plus or higher required."
      },
      "associated_phone_numbers": {
        "phone_numbers": [],
        "status": "Enterprise Plus or higher required."
      },
      "catch_all": false,
      "common": false,
      "deliverability": "low",
      "disposable": true,
      "dmarc_record": true,
      "dns_valid": true,
      "domain_age": {
        "human": "31 years ago",
        "iso": "1995-08-14T00:00:00-04:00",
        "timestamp": 808372800
      },
      "domain_trust": "Upgraded plan required.",
      "domain_velocity": "Enterprise Mini or higher required.",
      "email": "user@example.com",
      "first_name": "Corporate",
      "first_seen": {
        "human": "10 years ago",
        "iso": "2017-01-01T01:01:01-05:00",
        "timestamp": 1483250461
      },
      "fraud_score": 100,
      "frequent_complainer": true,
      "generic": true,
      "honeypot": true,
      "identity_data": null,
      "leaked": true,
      "mx_records": [],
      "overall_score": 0,
      "recent_abuse": true,
      "recent_data_matches": [],
      "recent_unique_user_values": [],
      "request_id": "lIUyaAnYku",
      "result_type": "live",
      "risky_tld": false,
      "sanitized_email": "user@example.com",
      "smtp_score": 0,
      "spam_trap_score": "high",
      "spf_record": true,
      "suggested_domain": null,
      "suspect": false,
      "timed_out": false,
      "user_activity": "Enterprise L4+ required.",
      "valid": false
    },
    "billing_phone": {
      "accurate_country_code": null,
      "active": null,
      "active_status": null,
      "associated_email_addresses": {
        "emails": [],
        "status": null
      },
      "carrier": null,
      "city": null,
      "country": null,
      "dialing_code": null,
      "do_not_call": null,
      "formatted": null,
      "fraud_score": null,
      "identity_data": null,
      "leaked": null,
      "line_type": null,
      "local_format": null,
      "mcc": null,
      "mnc": null,
      "name": null,
      "number_recycling": {
        "last_ported_date": null,
        "message": null,
        "ported": null,
        "recently_recycled": null
      },
      "phone_number": null,
      "prepaid": null,
      "recent_abuse": null,
      "recent_data_matches": [],
      "recent_unique_user_values": [],
      "region": null,
      "request_id": null,
      "risky": null,
      "sms_domain": null,
      "sms_email": null,
      "sms_pumping": {
        "message": null,
        "risk_score": null,
        "velocity": null
      },
      "spammer": null,
      "tcpa_blacklist": null,
      "timezone": null,
      "user_activity": null,
      "valid": null,
      "voip": null,
      "zip_code": null
    },
    "ip_address": {
      "abuse_events": [],
      "abuse_velocity": null,
      "active_tor": null,
      "active_vpn": null,
      "asn": null,
      "bot_status": null,
      "browser": null,
      "city": null,
      "connection_type": null,
      "country_code": null,
      "device_brand": null,
      "device_model": null,
      "dynamic_connection": null,
      "fraud_score": null,
      "frequent_abuser": null,
      "high_risk_attacks": null,
      "host": null,
      "ip_address": null,
      "is_crawler": null,
      "isp": null,
      "latitude": null,
      "longitude": null,
      "mobile": null,
      "operating_system": null,
      "organization": null,
      "proxy": null,
      "recent_abuse": null,
      "recent_data_matches": [],
      "recent_unique_user_values": [],
      "region": null,
      "request_id": null,
      "security_scanner": null,
      "shared_connection": null,
      "timezone": null,
      "tor": null,
      "trusted_network": null,
      "vpn": null,
      "zip_code": null
    },
    "shipping_email": {
      "a_records": [],
      "associated_names": {
        "names": [],
        "status": null
      },
      "associated_phone_numbers": {
        "phone_numbers": [],
        "status": null
      },
      "catch_all": null,
      "common": null,
      "deliverability": null,
      "disposable": null,
      "dmarc_record": null,
      "dns_valid": null,
      "domain_age": {
        "human": null,
        "iso": null,
        "timestamp": null
      },
      "domain_trust": null,
      "domain_velocity": null,
      "email": null,
      "first_name": null,
      "first_seen": {
        "human": null,
        "iso": null,
        "timestamp": null
      },
      "fraud_score": null,
      "frequent_complainer": null,
      "generic": null,
      "honeypot": null,
      "identity_data": null,
      "leaked": null,
      "mx_records": [],
      "overall_score": null,
      "recent_abuse": null,
      "recent_data_matches": [],
      "recent_unique_user_values": [],
      "request_id": null,
      "result_type": null,
      "risky_tld": null,
      "sanitized_email": null,
      "smtp_score": null,
      "spam_trap_score": null,
      "spf_record": null,
      "suggested_domain": null,
      "suspect": null,
      "timed_out": null,
      "user_activity": null,
      "valid": null
    },
    "shipping_phone": {
      "accurate_country_code": null,
      "active": null,
      "active_status": null,
      "associated_email_addresses": {
        "emails": [],
        "status": null
      },
      "carrier": null,
      "city": null,
      "country": null,
      "dialing_code": null,
      "do_not_call": null,
      "formatted": null,
      "fraud_score": null,
      "identity_data": null,
      "leaked": null,
      "line_type": null,
      "local_format": null,
      "mcc": null,
      "mnc": null,
      "name": null,
      "number_recycling": {
        "last_ported_date": null,
        "message": null,
        "ported": null,
        "recently_recycled": null
      },
      "phone_number": null,
      "prepaid": null,
      "recent_abuse": null,
      "recent_data_matches": [],
      "recent_unique_user_values": [],
      "region": null,
      "request_id": null,
      "risky": null,
      "sms_domain": null,
      "sms_email": null,
      "sms_pumping": {
        "message": null,
        "risk_score": null,
        "velocity": null
      },
      "spammer": null,
      "tcpa_blacklist": null,
      "timezone": null,
      "user_activity": null,
      "valid": null,
      "voip": null,
      "zip_code": null
    }
  },
  "risk_factors": [],
  "risk_score": 95,
  "risky_billing_phone": null,
  "risky_shipping_phone": null,
  "risky_username": null,
  "shipping_address_distance": {
    "kilometers": null,
    "miles": null
  },
  "shipping_phone_carrier": null,
  "shipping_phone_country": null,
  "shipping_phone_country_code": null,
  "shipping_phone_line_type": "Unknown",
  "user_activity": null,
  "user_flagged_billing_address": false,
  "user_flagged_shipping_address": null,
  "valid_billing_address": true,
  "valid_billing_email": false,
  "valid_billing_phone": false,
  "valid_shipping_address": null,
  "valid_shipping_email": false,
  "valid_shipping_phone": false
}
```

### Send fraud flow

Start one of your IPQS Fraud Flows for a user: a link to a hosted verification (their email, phone, IP, device or ID), returned for you to send, or emailed or texted by IPQS. Build the flow first in IPQS's Fraud Flows editor, then follow it with Get fraud flow results.

**Inputs**

- Flow ID (`flow_id`, text, required): The flow's ID, from IPQS's Fraud Flows page.
- Delivery (`delivery`, text): How the user gets the link. One of: `link` (Just return the link), `email` (Email the link), `text` (Text the link). Default: `link`.
- Email address (`email`, text): Where to email the link, when emailing it.
- Phone number (`phone_number`, text): Where to text the link, when texting it.
- Message (`message`, text): A message shown before the link, instead of the flow's own.
- Start the session now (`start_session`, true/false): Start the user's session at once rather than when they open the link. Default: `false`.
- Link lifetime (`link_lifetime`, number): How many seconds the link works for. It never expires by default. From 1 to 31536000.
- Session lifetime (`session_lifetime`, number): How many seconds the user has to come back to a started session; 600 by default. From 1 to 31536000.
- Link query (`link_query`, text): Text to add to the end of the link as its query, e.g. ref=signup&user=1234.

**Outputs**

- `delivery` (text): How the link was handed over: link, email or text.
- `flow_id` (text): The flow that was started.
- `link` (text): The verification link for the user, e.g. https://verify.is/... It is also emailed or texted when that was chosen.
- `link_request_id` (text): The link's ID. Pass it to Get fraud flow results.

**Example output**

```json
{
  "delivery": "link",
  "flow_id": "ABCDE12345",
  "link": "https://verify.is/ABCDE12345/BCDEF23456",
  "link_request_id": "BCDEF23456"
}
```

### Start bulk validation

Send a whole list of email addresses, phone numbers, IP addresses or URLs for IPQS to check in bulk: as values from an earlier step, or as a CSV file. IPQS processes it in the background; check on it with Get bulk validation, then use Download bulk validation results.

**Inputs**

- List type (`list_type`, text, required): What the list holds. One of: `email` (Email addresses), `phone` (Phone numbers), `proxy` (IP addresses), `url` (URLs).
- Values (`values`, list): The values to check: a list from an earlier step, or one on each line. Leave empty to send a file instead.
- CSV file (`file`, text): Instead of values, a CSV file of them: upload one, pick one from an earlier step, or give a link to one.
- Name (`file_name`, text): A name for the list in IPQS, e.g. signups.csv.

**Outputs**

- `aborted` (true/false): Whether processing was cancelled before it finished.
- `file_name` (text): The list's file name.
- `finished` (true/false): Whether processing is finished, so the results can be downloaded.
- `id` (number): The bulk validation's ID. Pass it to Get bulk validation and to Download bulk validation results.
- `invalid_records` (number): How many records in the list were invalid, so far.
- `list_type` (text): What the list holds: email, phone, proxy (IP addresses) or url.
- `request_id` (text): IPQS's ID for this request.
- `status` (text): Where processing is: NEW, PROCESSING, UNIQUE_RESULTS (removing repeats), FINALIZING or FINISHED.
- `strictness` (number): The strictness the list is checked at, 0 to 3; 0 is IPQS's default.

**Example output**

```json
{
  "aborted": null,
  "file_name": "sample_emails.csv",
  "finished": false,
  "id": 827746,
  "invalid_records": 0,
  "list_type": "email",
  "request_id": "HDOgXxgMHJ",
  "status": "NEW",
  "strictness": 0
}
```

### Update past lookup

Update a past IP, email or device fingerprint lookup: mark it converted or not (say, when a sign up turns into a paying customer) with the date, or correct its click date, user agent, language or custom variables, so IPQS can learn and rescore. Find it by request ID or by custom variables. Costs no credits.

**Inputs**

- Request ID (`request_id`, text): The lookup's request_id, as an earlier step returned it. Leave it empty to find the lookup by its custom variables instead.
- Lookup type (`lookup_type`, text): Which lookups to search when finding one by its custom variables. One of: `proxy` (IP address checks), `email` (Email address checks), `devicetracker` (Device fingerprints (website)), `mobiletracker` (Device fingerprints (mobile app)).
- Find by custom variables (`find_by`, object): Instead of a request ID, the custom variables the lookup was made with, such as userID, to find the latest lookup that has them.
- Conversion status (`conversion_status`, text): Whether the lookup led to a conversion. One of: `converted`, `not_converted` (Not converted).
- Conversion date (`conversion_date`, date and time): When it converted, in UTC.
- Click date (`click_date`, date and time): When the device was first seen, in UTC.
- User agent (`user_agent`, text): The browser user agent to record instead.
- Language (`language`, text): The browser language to record instead, e.g. en-US.
- Set custom variables (`set_variables`, object): Custom variables to set on the lookup, such as a new transactionID.

**Outputs**

- `lookup` (object): The past lookup as IPQS answered after the update, in its own names. Empty when it answered with no record.
- `request_id` (text): The request ID IPQS answered with.
- `updated` (true/false): True once IPQS accepted the update.
- `updates` (object): What was changed, by IPQS's name for each field, e.g. ConversionStatus: true.

**Example output**

```json
{
  "lookup": {
    "ASN": 30036,
    "IP": "192.0.2.110",
    "ISP": "Mediacom Cable",
    "abuse_velocity": "medium",
    "active_tor": false,
    "active_vpn": false,
    "bot_status": false,
    "city": "Houston",
    "connection_type": "Residential",
    "country_code": "US",
    "fraud_score": 25,
    "host": "192-0-2-110.client.mchsi.com",
    "is_crawler": false,
    "latitude": 29.7079,
    "longitude": -95.401,
    "mobile": false,
    "organization": "Mediacom Cable",
    "proxy": false,
    "recent_abuse": true,
    "region": "Texas",
    "request_id": "0w8WYS",
    "timezone": "America Matamoros",
    "tor": false,
    "vpn": false,
    "zip_code": "77001"
  },
  "request_id": "0w8WYS",
  "updated": true,
  "updates": {
    "ConversionDate": "2026-09-30 14:05:00",
    "ConversionStatus": "true"
  }
}
```

### Validate email address

Check whether an email address is real and safe to accept: whether it is valid and deliverable, disposable, a spam trap or honeypot, a catch-all, recently abusive or leaked, with a fraud score, its domain's age and trust, and a suggested domain for typos like gmai.com. Use it to clean a mailing list or screen sign ups.

**Inputs**

- Email address (`email`, text, required): The email address to check, e.g. someone@example.com.
- Timeout (`timeout`, number): How many seconds to wait for the mail server, 1 to 60; 7 by default. IPQS suggests 20 when the answer is not needed at once: a check that times out is less reliable. From 1 to 60. Default: `7`.
- Fast (`fast`, true/false): Skip asking the mail server, for a much quicker answer. The syntax, DNS, disposable and risk checks still run. Default: `false`.
- Suggest a domain (`suggest_domain`, true/false): Always check whether the domain is a typo of a popular mail service, such as gmai.com for gmail.com. Otherwise IPQS only checks invalid or abusive addresses. Default: `false`.
- Spam trap strictness (`strictness`, number): How readily to flag spam traps and honeypots, 0 to 2. 0 flags only those IPQS is very sure of; 2 catches the most. From 0 to 2. Default: `0`.
- Abuse strictness (`abuse_strictness`, number): How readily to mark the address as recently abusive, 0 to 2. IPQS suggests 1 or 2 for screening sign ups against determined fraudsters. From 0 to 2. Default: `0`.
- Custom variables (`custom_variables`, object): Your own tracking variables to record with the lookup, such as userID or transactionID, so you can find it again in your history and IPQS can spot patterns per user. Each must first be set up in your IPQS account settings.

**Outputs**

- `a_records` (list): The domain's A (address) records.
- `associated_names` (object): First and last names linked to the address. Upgraded plans only.
- `associated_phone_numbers` (object): Phone numbers linked to the address. Upgraded plans only.
- `catch_all` (true/false): Whether the domain's mail server accepts every address, so this one cannot be confirmed.
- `common` (true/false): Whether the address is at a common free provider, such as gmail.com, yahoo.com or hotmail.com.
- `deliverability` (text): How likely mail is to reach the inbox: high, medium or low.
- `disposable` (true/false): Whether the address belongs to a temporary or disposable mail service, as fraudsters and scammers often use.
- `dmarc_record` (true/false): Whether the domain has a proper DMARC record.
- `dns_valid` (true/false): Whether the domain has valid DNS records.
- `domain_age` (object): When the domain was registered. Its fields are null when unknown.
- `domain_trust` (text): How trustworthy the domain is from its history: trusted, positive, neutral, suspicious, malicious or not rated.
- `domain_velocity` (text): How many legitimate users the domain has: high, medium, low or none. Upgraded plans only.
- `email` (text): The email address that was checked.
- `first_name` (text): The first name the address suggests. CORPORATE for a company address, UNKNOWN when there is none.
- `first_seen` (object): When IPQS first saw the address, an estimate of how old it is. Its fields are null when unknown.
- `fraud_score` (number): IPQS's fraud score for the address, 0 to 100, from its reputation and recent behavior. 75 and above is suspicious, 80 and above is suspicious for user scoring, and 90 and above is risky.
- `frequent_complainer` (true/false): Whether the address often unsubscribes or reports mail as spam.
- `generic` (true/false): Whether the address is a shared one for a domain, such as admin@, sales@ or contact@.
- `honeypot` (true/false): Whether the address is believed to be a honeypot or spam trap. Bulk mail sent to one risks getting a sender blocked.
- `identity_data` (object): An Enterprise add-on: identity details from authoritative sources such as credit bureaus and telecoms, one entry per person, with names, addresses, email addresses, phone numbers and age, exactly as IPQS sends them. Null when the account does not have the add-on.
- `leaked` (true/false): Whether the address was in a recent data breach, which puts its accounts at risk of takeover.
- `mx_records` (list): The domain's MX (mail server) records.
- `overall_score` (number): Overall validity, 0 to 4: 0 invalid, 1 the mail server cannot be reached, 2 a temporary rejection, 3 the server accepts all mail, 4 the address is verified. Above 1 can be a valid address.
- `recent_abuse` (true/false): Whether IPQS has verified abuse from the address in the past few days: a chargeback, fake sign up, compromised device and the like.
- `recent_data_matches` (list): How often IPQS has seen the values sent in this lookup over the last 7 days, one entry per value. Empty when it has none to report.
- `recent_unique_user_values` (list): For your own tracking variables sent with the lookup (such as a user ID), how many different values of each kind IPQS has seen with them recently. Empty when none were sent.
- `request_id` (text): IPQS's ID for this lookup. Pass it to Report fraud to report the lookup as fraudulent, or to Get past lookup to read it again.
- `result_type` (text): How the result was produced: live (a full check now), cached (from recent checks) or fast (a quicker, less accurate check).
- `risky_tld` (true/false): Whether the domain ends in a top-level domain often used for malware, scams or phishing.
- `sanitized_email` (text): The address with aliases and masking removed, such as the extra dots in a Gmail address.
- `smtp_score` (number): How the mail server answered, -1 to 3: -1 invalid address, 0 the server rejects all mail, 1 a temporary error, 2 the server accepts all mail, 3 the server confirmed the address.
- `spam_trap_score` (text): How confident IPQS is that the address is an active spam trap: high, medium, low or none. Scrub high (and, to be stricter, medium) from promotional mailings.
- `spf_record` (true/false): Whether the domain has a proper SPF record.
- `suggested_domain` (text): The domain the address was probably meant to have, when it looks like a typo of a popular mail service (gmai.com for gmail.com). Null when there is no suggestion.
- `suspect` (true/false): Whether the mail server gave a temporary error or a broken handshake, so valid may not be reliable. Also true for catch-all domains.
- `timed_out` (true/false): Whether checking with the mail server timed out. A timed-out lookup that says the address is not valid should not be trusted; raise the timeout and try again.
- `user_activity` (text): How often the address is used for legitimate purchases and sign ups: high, medium, low or none. High and medium are strong signs of a real user. Higher plans only.
- `valid` (true/false): Whether the address appears valid. For a mailing list, keep addresses that are valid, not disposable and whose spam_trap_score is not high.

**Example output**

```json
{
  "a_records": [
    "192.0.2.110"
  ],
  "associated_names": {
    "names": [],
    "status": "Enterprise Plus or higher required."
  },
  "associated_phone_numbers": {
    "phone_numbers": [],
    "status": "Enterprise Plus or higher required."
  },
  "catch_all": false,
  "common": true,
  "deliverability": "high",
  "disposable": false,
  "dmarc_record": true,
  "dns_valid": true,
  "domain_age": {
    "human": "3 months ago",
    "iso": "2019-09-09T16:40:34-04:00",
    "timestamp": 1568061634
  },
  "domain_trust": "trusted",
  "domain_velocity": "high",
  "email": "noreply@ipqualityscore.com",
  "first_name": "Unknown",
  "first_seen": {
    "human": "3 months ago",
    "iso": "2019-09-09T16:40:34-04:00",
    "timestamp": 1568061634
  },
  "fraud_score": 25,
  "frequent_complainer": false,
  "generic": false,
  "honeypot": false,
  "identity_data": null,
  "leaked": false,
  "mx_records": [
    "us-smtp-inbound-1.mimecast.com",
    "aspmx.l.google.com"
  ],
  "overall_score": 4,
  "recent_abuse": false,
  "recent_data_matches": [],
  "recent_unique_user_values": [],
  "request_id": "4JAer3sX6rF3PO",
  "result_type": "live",
  "risky_tld": false,
  "sanitized_email": "validated@example.com",
  "smtp_score": 3,
  "spam_trap_score": "none",
  "spf_record": true,
  "suggested_domain": null,
  "suspect": false,
  "timed_out": false,
  "user_activity": "medium",
  "valid": true
}
```

### Validate phone number

Check whether a phone number is real and safe to accept: whether it is valid and active, its line type (mobile, landline, VOIP, toll free), carrier and location, whether it is prepaid, risky, a spammer or recently abusive, with a fraud score. An invalid number comes back with valid false, not an error.

**Inputs**

- Phone number (`phone_number`, text, required): The phone number to check. Spaces, dashes and brackets are fine. With fewer than 10 digits it needs its country code after a +, or its country under Countries.
- Countries (`countries`, list): The countries the number is likely from, as two-letter codes like US, GB or DE. IPQS prefers them when reading the number, and needs one for a short number without a country code.
- Strictness (`strictness`, number): How strict the check is, 0 to 2. IPQS recommends starting at 0; stricter checks flag more, honest ones included. From 0 to 2. Default: `0`.
- Custom variables (`custom_variables`, object): Your own tracking variables to record with the lookup, such as userID or transactionID, so you can find it again in your history and IPQS can spot patterns per user. Each must first be set up in your IPQS account settings.

**Outputs**

- `accurate_country_code` (true/false): Whether the number's dialing code matches one of the countries given with the lookup.
- `active` (true/false): Whether the number is live and reachable. An add-on IPQS enables on request; null without it.
- `active_status` (text): The line's status, with enhanced line checks enabled: Active Line (with a High, Medium or Low Confidence when IPQS can tell), Disconnected Line, Phone Turned Off or Inconclusive Status. Null when unknown.
- `associated_email_addresses` (object): Email addresses linked to the number. Upgraded plans only.
- `carrier` (text): The carrier the number is assigned to, when known.
- `city` (text): The number's city, when known.
- `country` (text): Two-letter code of the number's country, e.g. US.
- `dialing_code` (number): The country dialing code, 1 to 4 digits, e.g. 1. Null when unknown.
- `do_not_call` (true/false): Whether the number is on a Do Not Call list. United States and Canada only; null when the feature is not enabled.
- `formatted` (text): The number in international format, e.g. +18007132618.
- `fraud_score` (number): IPQS's fraud score for the number, 0 to 100. 75 and above is suspicious, 85 and above is risky, and 90 and above has already been used for abuse.
- `identity_data` (object): An Enterprise add-on: identity details from authoritative sources such as credit bureaus and telecoms, one entry per person, with names, addresses, email addresses, phone numbers and age, exactly as IPQS sends them. Null when the account does not have the add-on.
- `leaked` (true/false): Whether the number was recently exposed in a data breach.
- `line_type` (text): The kind of line: Wireless, Landline, Toll-Free, VOIP, Satellite, Premium Rate or Pager. Null when unknown.
- `local_format` (text): The number as it is written in its own country, e.g. (800) 713-2618.
- `mcc` (text): The mobile country code, typically 3 digits. Null for landlines, toll free numbers and when unknown.
- `mnc` (text): The mobile network code of the carrier, typically 3 digits. Null for landlines, toll free numbers and when unknown.
- `name` (text): The name of the number's owner, a person or a business, when known. Several are separated by commas.
- `number_recycling` (object): An add-on: whether the number recently changed owners or carriers. Its fields are null without it.
- `phone_number` (text): The phone number that was checked, as sent.
- `prepaid` (true/false): Whether the number is on a prepaid plan.
- `recent_abuse` (true/false): Whether the number has been tied to recent or ongoing fraud.
- `recent_data_matches` (list): How often IPQS has seen the values sent in this lookup over the last 7 days, one entry per value. Empty when it has none to report.
- `recent_unique_user_values` (list): For your own tracking variables sent with the lookup (such as a user ID), how many different values of each kind IPQS has seen with them recently. Empty when none were sent.
- `region` (text): The number's region or state, when known.
- `request_id` (text): IPQS's ID for this lookup. Pass it to Report fraud to report the lookup as fraudulent, or to Get past lookup to read it again.
- `risky` (true/false): Whether the number is tied to fraud, scams, robocalls, fake accounts or other unfriendly behavior.
- `sms_domain` (text): The carrier's domain for sending email to the phone as text, e.g. tmomail.net, when it has one.
- `sms_email` (text): The carrier's email address for texting the phone, e.g. 5555551234@tmomail.net, when it has one.
- `sms_pumping` (object): An add-on: how likely the number is to be used for SMS pumping fraud. Its fields are null without it.
- `spammer` (true/false): Whether the number has recently been reported for spam or harassing calls or texts.
- `tcpa_blacklist` (true/false): Whether the number belongs to, or is tied to, someone who often files TCPA lawsuits. An add-on; null without it.
- `timezone` (text): The number's time zone, when known.
- `user_activity` (text): How often the number is used for legitimate purchases and sign ups: high, medium, low or none. Higher plans only.
- `valid` (true/false): Whether the number is properly formatted and assigned to a carrier in its country.
- `voip` (true/false): Whether the number is a VOIP (internet) or other digital number.
- `zip_code` (text): The number's postal code, when known.

**Example output**

```json
{
  "accurate_country_code": true,
  "active": true,
  "active_status": "Active Line - High Confidence",
  "associated_email_addresses": {
    "emails": [
      "hello@ipqualityscore.com"
    ],
    "status": "Associated emails found."
  },
  "carrier": "Verizon Wireless",
  "city": "Las Vegas",
  "country": "US",
  "dialing_code": 1,
  "do_not_call": false,
  "formatted": "+18007132618",
  "fraud_score": 44,
  "identity_data": null,
  "leaked": false,
  "line_type": "Toll Free",
  "local_format": "(800) 713-2618",
  "mcc": null,
  "mnc": null,
  "name": "IPQualityScore",
  "number_recycling": {
    "last_ported_date": null,
    "message": null,
    "ported": null,
    "recently_recycled": null
  },
  "phone_number": "+18007132618",
  "prepaid": false,
  "recent_abuse": false,
  "recent_data_matches": [],
  "recent_unique_user_values": [],
  "region": "Nevada",
  "request_id": "4ZGSfWu9RDf3oH",
  "risky": true,
  "sms_domain": null,
  "sms_email": null,
  "sms_pumping": {
    "message": "Low risk of SMS pumping attack.",
    "risk_score": 0,
    "velocity": "low"
  },
  "spammer": false,
  "tcpa_blacklist": false,
  "timezone": "America/Los_Angeles",
  "user_activity": "high",
  "valid": true,
  "voip": false,
  "zip_code": "89132"
}
```