# Add device and IP intelligence to your app

> Add device and IP intelligence with ScreenlyyID: the instance call, the request, the response fields, the decision rule, working Node, Python and Next.js code, and a checklist.

Canonical URL: https://www.screenlyyid.com/docs/guides/device-ip-intelligence/

## Summary

Device and IP intelligence looks at the IP address, host name and browser (user agent) behind a request. Four endpoints cover where an IP is and whether it is a VPN or proxy (`ip-probe-verify`), whether it is on a blocklist (`ip-blocklist-verify`), a host's reputation (`host-reputation-verify`) and what device a user agent is (`ua-lookup-verify`).

## When to use it / when not to

**Use it for:**

- sign-up, login or checkout: is the visitor behind a VPN, proxy, Tor or a hosting provider, or on a blocklist
- you want the visitor's country, or whether the browser is a webview or mobile

**Do not use it for:**

- An IP is a signal, not an identity: many real people use VPNs. Use it to decide when to ask for more, not to block on its own.
- You want to check a card against an IP: use [BIN lookup](https://www.screenlyyid.com/docs/guides/bin-lookup/) with `CustomerIpAddress`.

## Before you start

- **API key:** read it from the environment variable `SCREENLYYID_API_KEY` on your **server only**. Use a `test_` key for the sandbox and a `prod_` key for live. Never put it in browser or mobile code. See [Get a test key](https://www.screenlyyid.com/docs/ai-quickstart/#get-a-test-key).
- **Base URL:** `https://api.screenlyyid.com`. HTTPS only.
- **Activation and plan:** The device and IP product code is `ipv`. In the current API code the four device endpoints do not enforce product activation (the check is switched off), but create the instance with `ipv` anyway so the checks are recorded against the customer.
- **Start with the Instance API.** Every flow starts with `POST /api/v1/instance/create`, listing this product's code (`ipv`) in `CustomerIntelligence`. It returns a `CorrelationId` that you send as `x-correlation-id` on the product call, along with `x-api-key`. A product call can be accepted only **once per correlation id**: repeating it with the same id can return `409 duplicate_correlation_id`. Create a new instance for each check (for example one per checkout or per sign-up).

```bash
curl --request POST --url 'https://api.screenlyyid.com/api/v1/instance/create' \
  --header "x-api-key: $SCREENLYYID_API_KEY" --header 'Content-Type: application/json' \
  --data '{"GlobalScreening": [], "CustomerIntelligence": ["ipv"]}'
# { "CorrelationId": "...", "webEnrolmentUrl": "..." }   (webEnrolmentUrl is only used by the hosted identity verification flow)
```

## Use it on its own or stacked

This product can be called on its own (one instance with just `ipv`, as above) or stacked with other products for the same customer: list several product codes in the one instance call and send the same `CorrelationId` on each product's call. See [Run several checks in one session](https://www.screenlyyid.com/docs/guides/stacking-checks/). Example pairing: BIN + IP + email at checkout (`CustomerIntelligence`: `["bin", "ipv", "emv"]`).

Document and selfie identity verification is **not** part of this product. It only goes through the Instance API and the hosted capture page: see [Identity verification (mobile)](https://www.screenlyyid.com/docs/guides/identity-verification-mobile/) and [Identity verification (web)](https://www.screenlyyid.com/docs/guides/identity-verification-web/). Do not use the direct identity verification endpoints.

## Implementation steps

1. **Create the instance** in your server code, right before the check. Keep the `CorrelationId` with your own record (the user, the order). Do this on the server.
2. **Call the endpoint** `POST /api/v1/ip-probe-verify` with `x-api-key`, `x-correlation-id` and a JSON body (next section). In a typical app this is the sign-up or form-submit handler, before you create the account.
3. **Read the response** and apply the [decision logic](https://www.screenlyyid.com/docs/guides/device-ip-intelligence/#decision-logic): the fields marked ★ are the ones to base a decision on.
4. **Act on the result:** accept, ask the customer to correct their input, flag for review, or block. Store the `CorrelationId` and the outcome: it is your audit trail, and the same id shows the check in the dashboard.
5. **Handle failures** (below) so a provider outage never breaks your flow.

## Request and response

### Request
```json
{
  "IpAdress": "8.8.8.8"
}
```

| Field | Type | Meaning | Example |
|---|---|---|---|
| `IpAdress` | string | ip-probe-verify and ip-blocklist-verify: the IP address to check. Required. (The name is spelled this way in the API.) | 8.8.8.8 |
| `VPNLookup` | boolean | ip-blocklist-verify only: also check whether the IP is a VPN. | true |
| `Host` | string | host-reputation-verify: the host name or IP. Required. | example.com |
| `ListRating` | integer | host-reputation-verify: minimum blocklist rating to count. Default 3. | 3 |
| `UserAgent` | string | ua-lookup-verify: the browser user-agent string. Required. | Mozilla/5.0 ... |

The other endpoints in this product: `POST /api/v1/ip-blocklist-verify`, `POST /api/v1/host-reputation-verify`, `POST /api/v1/ua-lookup-verify`. Each takes its own body (see the request table) and the same headers.

### Response
```json
{
  "RegionCode": "CA",
  "Country": "United States of America",
  "CountryCode": "US",
  "ProviderDomain": "cloud.google.com",
  "City": "Mountain View",
  "VpnDomain": "",
  "IsVpn": false,
  "AsCidr": "8.8.8.0/24",
  "Valid": true,
  "ProviderType": "hosting",
  "Hostname": "dns.google",
  "AsAge": 34,
  "ContinentCode": "NA",
  "IsBogon": false,
  "Ip": "8.8.8.8",
  "AsCountryCode": "US",
  "ProviderDescription": "Cloud Computing Services Google Cloud: Meet your business challenges head on with cloud computing services from Google, including data management, hybrid & multi-cloud, and AI & ML",
  "AsCountryCode3": "USA",
  "IsV4Mapped": false,
  "IsIsp": false,
  "ProviderWebsite": "https://cloud.google.com",
  "AsDescription": "Google LLC, Google, YouTube (for Google Fiber see AS16591 record), GOOGLE, US, GOGL",
  "IsHosting": true,
  "AsDomains": [
    "cloud.google.com",
    "about.google"
  ],
  "HostDomain": "dns.google",
  "IsProxy": false,
  "CurrencyCode": "USD",
  "Region": "California",
  "Asn": "15169",
  "CountryCode3": "USA",
  "IsV6": false
}
```

| Field | Type | Meaning | Example |
|---|---|---|---|
| `IsVpn` | boolean | ★ ip-probe-verify: the IP belongs to a VPN. | false |
| `IsProxy` | boolean | ★ The IP is a proxy. | false |
| `IsHosting` | boolean | ★ A hosting or data-centre IP (not a typical home user). | false |
| `IsBogon` | boolean | ★ A reserved or unroutable address. | false |
| `CountryCode` | string | Country of the IP, ISO 3166 alpha-2. | US |
| `IsListed` | boolean | ★ ip-blocklist-verify and host-reputation-verify: appears on a blocklist. | false |
| `IsTor / IsBot / IsSpamBot / IsMalware / IsExploitBot` | boolean | ★ ip-blocklist-verify: the kind of listing. | false |
| `ListCount` | integer | Number of blocklists that list it. | 0 |
| `IsMobile / IsWebview / Type` | boolean / string | ua-lookup-verify: the device type. | true |

★ = base your decision on this field.

## Decision logic

1. `IsBogon` is `true`: reject (not a real client address).
2. `IsListed`, `IsTor`, `IsBot`, `IsSpamBot`, `IsMalware` or `IsExploitBot` is `true`: block, or require stronger verification.
3. `IsVpn`, `IsProxy` or `IsHosting` is `true`: flag for review. Do not block on this alone.
4. Compare `CountryCode` with the country in the customer's other data (card, phone, address).

```javascript
function ipDecision(probe, blocklist) {
  if (probe.IsBogon) return { action: "reject", reason: "bogon" };
  if (blocklist && (blocklist.IsListed || blocklist.IsTor || blocklist.IsBot || blocklist.IsMalware)) return { action: "block", reason: "blocklisted" };
  const flags = [];
  if (probe.IsVpn) flags.push("vpn");
  if (probe.IsProxy) flags.push("proxy");
  if (probe.IsHosting) flags.push("hosting");
  return flags.length ? { action: "review", reason: flags } : { action: "accept" };
}
```

## Errors and limits

| Status | When | Body |
|---|---|---|
| `400` | A required field is missing or the body is not valid JSON | A problem-details object: `{"type": "...", "title": "One or more validation errors occurred.", "status": 400, "errors": {"<Field>": ["The <Field> field is required."]}}` |
| `401` | `x-api-key` is missing or malformed, or the product is not activated on the account | Empty body with a `WWW-Authenticate` header |
| `409` | The same `x-correlation-id` was already used for this product | `{"error": "duplicate_correlation_id", "message": "Duplicate correlation id received."}` |
| `500` | The upstream data provider failed | `{"error": "internal_error", "message": "An unexpected error occurred"}` |

No rate limit is documented. Use a short timeout (5 to 10 seconds) in a live path and fail open to review if it expires.

## Code

Minimal working server-side code. It creates the instance, makes the call with a timeout and throws on a non-`2xx` response with the status and error body attached. The key is read from `SCREENLYYID_API_KEY`.

### JavaScript (Node 18+, fetch)
```javascript
// server only: this reads your API key. Node 18 or later, no dependencies.
const API = "https://api.screenlyyid.com";
const apiKey = process.env.SCREENLYYID_API_KEY; // test_ while building, prod_ in production
if (!apiKey) throw new Error("SCREENLYYID_API_KEY is not set");

// Step 1: one instance per check. It lists this product's code and returns the CorrelationId.
export async function createInstance() {
  const r = await fetch(`${API}/api/v1/instance/create`, {
    method: "POST",
    headers: { "x-api-key": apiKey, "Content-Type": "application/json" },
    body: JSON.stringify({ GlobalScreening: [], CustomerIntelligence: ["ipv"] }),
  });
  if (!r.ok) throw new Error(`instance/create failed (HTTP ${r.status})`);
  const { CorrelationId } = await r.json(); // spelled exactly like this
  return CorrelationId;
}

// Step 2: Device and IP intelligence looks at the IP address, host name and browser (user agent) behind a request
export async function probeIp(ip) {
  const correlationId = await createInstance();
  const r = await fetch(`${API}/api/v1/ip-probe-verify`, {
    method: "POST",
    headers: { "x-api-key": apiKey, "x-correlation-id": correlationId, "Content-Type": "application/json" },
    body: JSON.stringify({ IpAdress: ip }),
    signal: AbortSignal.timeout(15000),
  });
  if (!r.ok) {
    const error = new Error(`/ip-probe-verify failed (HTTP ${r.status})`);
    error.status = r.status;
    error.body = await r.json().catch(() => null);
    throw error;
  }
  return { correlationId, result: await r.json() };
}
```

### Python (requests)
```python
# server only: this reads your API key. Python 3.9 or later, pip install requests
import os
import requests

API = "https://api.screenlyyid.com"
API_KEY = os.environ["SCREENLYYID_API_KEY"]  # test_ while building, prod_ in production


def create_instance():
    """Step 1: one instance per check. It lists this product's code and returns the CorrelationId."""
    r = requests.post(
        f"{API}/api/v1/instance/create",
        headers={"x-api-key": API_KEY},
        json={"GlobalScreening": [], "CustomerIntelligence": ["ipv"]},
        timeout=15,
    )
    r.raise_for_status()
    return r.json()["CorrelationId"]  # spelled exactly like this


def probe_ip(ip):
    """Step 2: Device and IP intelligence looks at the IP address, host name and browser (user agent) behind a request"""
    correlation_id = create_instance()
    r = requests.post(
        f"{API}/api/v1/ip-probe-verify",
        headers={"x-api-key": API_KEY, "x-correlation-id": correlation_id},
        json={"IpAdress": ip},
        timeout=15,
    )
    r.raise_for_status()  # a requests.HTTPError carries r.status_code and r.json() for the error body
    return correlation_id, r.json()
```

### Next.js route handler
```javascript
// app/api/probeIp/route.js (Next.js App Router). The key is read on the server only.
import { probeIp } from "@/lib/screenlyyid";

export const dynamic = "force-dynamic";

export async function POST(request) {
  const input = await request.json();
  try {
    const { result } = await probeIp(input);
    return Response.json(result); // send the browser only what it needs, never the API key or the CorrelationId
  } catch (e) {
    // a provider outage or timeout must not break your own flow: decide fail-open or fail-closed here
    return Response.json({ error: "check_unavailable", status: e.status ?? null }, { status: 502 });
  }
}
```

## Test it

The sandbox runs real lookups, so there are no special test values. 8.8.8.8 is a public DNS address, so it shows `IsHosting` `true`: use your own public IP for a typical home-user result.

| Input | Expected result |
|---|---|
| ip-probe-verify 8.8.8.8 | `CountryCode` `US`, `IsHosting` `true`, `ProviderType` `hosting`, `IsVpn` `false`, `IsProxy` `false`, `IsBogon` `false`. |
| ip-blocklist-verify 8.8.8.8 | `IsListed` `false`, `IsTor` `false`, `IsVpn` `false`. |
| host-reputation-verify example.com | `HostInfos[]` with `IsListed` `false` for each list checked. |
| ua-lookup-verify an iPhone Safari user agent | `DeviceModel` `iPhone`, `Os` `iOS 17`, `DeviceBrand` `Apple`. |

## Done when

- [ ] The API key is read only on the server
- [ ] The client IP comes from your server (the real remote address or your proxy's trusted header), never from a field the browser can set
- [ ] A new instance is created per check and its `CorrelationId` is sent
- [ ] VPN and proxy results lead to review, not an automatic block
- [ ] Errors and timeouts do not break sign-up or checkout
- [ ] A test call returns `200` with a `test_` key

## Related

- [Device verification (API reference)](https://www.screenlyyid.com/docs/api-reference/device-verification/)
- [Instance API](https://www.screenlyyid.com/docs/authentication/create-instance/)
- [Stacking checks](https://www.screenlyyid.com/docs/guides/stacking-checks/)
