Skip to content
Risk & Fraud

Fraud Detection

One rule-based fraud score from any mix of email, phone and IP signals.

POST/v1/fraud-detection
3 credits / checkBulk supportedGlobal
Request
curl -X POST https://api.1lookup.dev/v1/fraud-detection \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane.doe@example.com","phone_number":"+15125550142","ip":"203.0.113.42"}'
Response
{
  "success": true,
  "data": {
    "score": 72,
    "level": "high",
    "rules_fired": [
      {
        "rule": "voip_number",
        "signal": "phone",
        "detail": "Line type is VoIP."
      },
      {
        "rule": "datacenter_ip",
        "signal": "ip",
        "detail": "IP belongs to a hosting provider."
      },
      {
        "rule": "geo_mismatch",
        "signal": "phone_ip",
        "detail": "Phone country is US, IP country is NL."
      }
    ],
    "signals": {
      "email": {
        "address": "jordan.avery@example.com",
        "valid": true,
        "disposable": false,
        "role_account": false
      },
      "phone": {
        "phone_number": "+15125550142",
        "valid": true,
        "line_type": "voip",
        "country": "US"
      },
      "ip": {
        "address": "203.0.113.42",
        "country": "NL",
        "vpn": false,
        "proxy": false,
        "tor": false,
        "hosting": true
      }
    },
    "inputs_checked": [
      "email",
      "phone",
      "ip"
    ]
  },
  "meta": {
    "credits_used": 3,
    "credits_remaining": 999,
    "cached": false,
    "request_id": "req_8f3a2c1e9b7d"
  }
}

Authorization

Authorizationstring<bearer>required

Your API key as a Bearer token. Live keys start with 1lk_live_. Test keys start with 1lk_test_ and return this endpoint's sample response without spending credits. See authentication.

Body

Send the fields as a JSON object with Content-Type: application/json.

emailstring<email>

Email address. Example: jane.doe@example.com

phone_numberstring<E.164>

Phone number. Example: +15125550142

ipstring<ip>

IP address. IPv4 or IPv6 Example: 203.0.113.42

freshboolean

Skip the 7-day cache and run a new lookup. Charged as a normal lookup.

referencestring

Your own identifier, echoed back in meta and shown in lookup history.

Response

A 200 response carries the result in data and the cost of the call in meta. These are the fields most integrations read.

successboolean

true when the lookup ran.

data.scorenumber

0 to 100. Higher means more rules fired, or weightier ones did.

data.levelstring

low, medium or high: a banded reading of the score for simple branching.

data.rules_firedarray

Each rule that contributed, with the signal it came from and a plain-language detail.

data.signals.emailobject

Validity, disposable-domain and role-account findings for the email you sent.

data.signals.phone.line_typestring

mobile, landline or voip. VoIP numbers are a common trait of throwaway accounts.

data.signals.ip.hostingboolean

True when the address belongs to a hosting provider instead of a consumer network.

data.inputs_checkedarray

Which of email, phone and IP were present and evaluated in this check.

meta.credits_usednumber

Credits charged for this call.

meta.credits_remainingnumber

Your balance after the call.

meta.cachedboolean

true when the result came from the 7-day cache.

meta.request_idstring

Quote this when you contact support.

Errors

A failed request returns success: false with an error object, and is never charged. The full list is on the errors page.

HTTPCodeMeaning
401unauthorizedThe key is missing, malformed or revoked.
402insufficient_creditsYour credits are used up and pay as you go is off or at its limit.
422invalid_inputA field is missing or malformed. The field property names it.
429rate_limitedToo many requests for this key. Wait for the Retry-After interval.
500internal_errorSomething failed on our side. Safe to retry.
503source_unavailableAn upstream source did not answer in time. Safe to retry.

Billing

3 credits / check. Charged when the lookup runs and returns a result. Errors are never charged, and repeating the same input within 7 days is served from cache at no charge.

Product overview and use cases