API-referentie voor detectie van onmogelijke reizen

POST/v1/risk/check

Vergelijkt de herleide locatie van een opgegeven IP met een opgeslagen baseline per gebruiker en classificeert de daaruit voortvloeiende reissnelheid. Een ruw signaal voor je eigen fraudeworkflow, geen definitief oordeel — neem contact met ons op om de beschikbaarheid te bevestigen voordat je dit integreert; onafhankelijke handhaving van het risicoplan en de gereedheid voor checkout zijn niet geverifieerd.

Authenticatie

Geef een geheime sleutel mee via Authorization: Bearer YOUR_SECRET_KEY, hetzelfde sleuteltype als de lookup-endpoints. Stuur een JSON-body met userId, ip en een optionele boolean commit (standaard true; zet op false voor een speculatieve controle die de opgeslagen baseline niet mag verplaatsen).

Antwoordvelden

risk: low, medium of high.
impossibleTravel: Boolean-samenvatting van of de daaruit voortvloeiende snelheid tussen de vorige en huidige locatie een plausibele reissnelheid overschrijdt.
distanceKm, impliedSpeedKmh, elapsedSeconds: De afstand en tijd tussen de vorige en huidige waarneming, en de snelheid die dat impliceert. Null bij de allereerste controle van een gebruiker, wanneer er geen vorige locatie is om mee te vergelijken.
previousLocation: country, latitude, longitude en observedAt voor de opgeslagen baseline vóór deze aanroep. Null wanneer dit de allereerste controle voor deze userId is.
currentLocation: country, latitude en longitude voor het ip dat je bij deze aanroep hebt opgegeven.

Foutmeldingen

400: Onjuist geformatteerd IP-adres of ontbrekende userId.
401: Ontbrekende of ongeldige API-sleutel.
403: Er is een publiceerbare sleutel gebruikt in plaats van een geheime sleutel.
422: Het opgegeven IP kon niet naar een locatie worden herleid.
429: Rate limit overschreden voor het huidige venster van één minuut.

Voorbeeld

Verzoek

curl https://api.watch-ip.com/v1/risk/check \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userId": "u_123", "ip": "203.0.113.1"}'

Antwoord

{
  "risk": "high",
  "impossibleTravel": true,
  "distanceKm": 8843.2,
  "impliedSpeedKmh": 4421.6,
  "elapsedSeconds": 7200,
  "previousLocation": { "country": "FR", "latitude": 48.8566, "longitude": 2.3522, "observedAt": "2026-09-06T12:00:00.000Z" },
  "currentLocation": { "country": "US", "latitude": 30.2672, "longitude": -97.7431 }
}

Limieten

v1 slaat alleen de meest recente locatie per gebruiker op, geen geschiedenisvenster — verwacht valse positieven door snel wisselende VPN's of IP-verloop op mobiele netwerken, aangezien er nog geen VPN-/datacenterbewuste onderdrukking is. Behandel het resultaat als een ruw signaal, geen definitief oordeel. Omdat dit endpoint een aan een userId gekoppelde locatie opslaat voorbij een enkele verzoek/antwoord-cyclus, maakt het gebruik ervan Watch-IP tot een verwerker van die gegevens namens jou — zie het Addendum voor gegevensverwerking.