ScreenlyyIDDocs
Docs › Guides

Add device and IP intelligence to your app

View as Markdown

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 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.
  • 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).
Shell
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. 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) and 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: 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"
}
FieldTypeMeaningExample
IpAdressstringip-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
VPNLookupbooleanip-blocklist-verify only: also check whether the IP is a VPN.true
Hoststringhost-reputation-verify: the host name or IP. Required.example.com
ListRatingintegerhost-reputation-verify: minimum blocklist rating to count. Default 3.3
UserAgentstringua-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
}
FieldTypeMeaningExample
IsVpnboolean★ ip-probe-verify: the IP belongs to a VPN.false
IsProxyboolean★ The IP is a proxy.false
IsHostingboolean★ A hosting or data-centre IP (not a typical home user).false
IsBogonboolean★ A reserved or unroutable address.false
CountryCodestringCountry of the IP, ISO 3166 alpha-2.US
IsListedboolean★ ip-blocklist-verify and host-reputation-verify: appears on a blocklist.false
IsTor / IsBot / IsSpamBot / IsMalware / IsExploitBotboolean★ ip-blocklist-verify: the kind of listing.false
ListCountintegerNumber of blocklists that list it.0
IsMobile / IsWebview / Typeboolean / stringua-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#

StatusWhenBody
400A required field is missing or the body is not valid JSONA problem-details object: {"type": "...", "title": "One or more validation errors occurred.", "status": 400, "errors": {"<Field>": ["The <Field> field is required."]}}
401x-api-key is missing or malformed, or the product is not activated on the accountEmpty body with a WWW-Authenticate header
409The same x-correlation-id was already used for this product{"error": "duplicate_correlation_id", "message": "Duplicate correlation id received."}
500The 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.

InputExpected result
ip-probe-verify 8.8.8.8CountryCode US, IsHosting true, ProviderType hosting, IsVpn false, IsProxy false, IsBogon false.
ip-blocklist-verify 8.8.8.8IsListed false, IsTor false, IsVpn false.
host-reputation-verify example.comHostInfos[] with IsListed false for each list checked.
ua-lookup-verify an iPhone Safari user agentDeviceModel 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