Residential proxy detection: Best practices

A residential proxy response looks like this:

{
    "ip": "203.0.113.34",
    "hostname": "203-0-113-34.dyn.example-broadband.net",
    "asn": 12345,
    "isp": "Example Broadband",
    "countryCode": "US",
    "countryName": "United States",
    "block": 1, Residential proxy
    "blockReason": "Residential proxy",
    "proxyType": {
        "proxy": false,
        "tor": false,
        "hosting": false,
        "relay": false,
        "residentialProxy": true,PRO
        "cloudGaming": false
    }
}

Every field discussed on this page appears above. Look up any IP address free.

1. What the signal means

A residential proxy hit (block=1 with residentialProxy=true) means we have seen that IP address take part in a residential proxy network. A residential proxy sends other people's traffic through an ordinary home connection. That is a real observation - it is not a guess, an opinion, or a probability score.

It does not mean:

• The current request is fraudulent. Someone may be routing traffic through that address, or the visitor may be its normal user.
• The proxy is still on that address. Home and mobile addresses are reassigned, so it may now belong to a different customer.
• The device making the request is running the proxy. The flag applies to the public IP address. One device is enough to flag a household, an office or campus, or other customers who share that address.

Used with your other checks, it catches fraud that VPN and datacenter detection miss, because the address looks like a normal home connection. Used as a hard ban, it will sometimes block the proxy user's housemates, other customers on the same shared address, or the next person that address is assigned to.

2. block=1 vs block=2 for residential proxy

"block": 1,
"proxyType": {
    "residentialProxy": true
}

"block": 2,
"proxyType": {
    "residentialProxy": true
}

residentialProxy stays true in both cases. block=2 is not a different kind of proxy - it is an older observation. Treat block=1 as a strong signal and block=2 as a weaker one. Section 4 maps each one to a response.

3. Where false positives come from

Even a block=1 hit with residentialProxy=true does not mean the current request is fraudulent. A legitimate user shows up on a flagged address in a few ordinary ways:

• Someone else on the connection. Someone in the household, or a device on the network, installed an app that joins the connection to a residential proxy service, often a bandwidth-sharing or "earn money from your internet" app, a free VPN, software bundled inside a free app or game, or an app on a smart TV or other connected device.
• A previous customer. The address was used by a previous customer of the internet provider before it was assigned to the person you are checking, which is common because many home connections use dynamic addresses that get reused. Mobile connections change address often, so an address flagged a few minutes ago may already belong to someone else.
• A shared address. The internet provider may put many customers behind one public IPv4 address (CGNAT) or share a single IPv6 address the same way, so one of those other customers running a residential proxy is enough for the shared address to be flagged, including for the person you are checking.

This is not a fault in the detection. We did see the address in a residential proxy network, and providers share addresses and reuse them. Keep the check, and match your response to the cost of a false positive.

This is specific to residential proxies. Other block=1 results (hosting, VPN, Tor, open proxy) mean the address belongs to that service.

4. Recommended response patterns

For most products - e-commerce, SaaS, marketplaces - match the strength of your response to what the visitor is about to do.

Match the response to the stakes of the action

Adjusting for your use case

The stakes ladder above is the default. A few products need a different balance.

5. Handling a user who says they are not using a proxy

A customer will eventually write to say they were blocked, and that they are not using a proxy. A few things help:

• Take it seriously. They may be right. Someone in the household may have installed a bandwidth-sharing app, the address may have belonged to a previous customer, or the provider may be sharing that address across many customers.
• Have a manual override. A way to allow a specific account or session through, so a legitimate user is not stuck waiting for the address to clear.
• Suggest they check their devices. Phones, computers, TVs, and other devices can be running a bandwidth-sharing app, a free VPN, or an app they do not recognize. Why is my IP address classified as a residential proxy? explains this for them. If that activity stops, the flag fades on its own as those observations get older.

6. Caching

These addresses change hands often, so a long cache works against you. You can keep a stale "is a proxy" result on an address that now belongs to someone else, or miss an address that has only just joined a residential proxy network. Cache for a short window, such as a minute, or 1-10 seconds for fraud-sensitive checks. For less sensitive use, see the caching FAQ.