Risk Lookup API

A JSON API for checking customer details against moderator-approved fraud reports in Bangladesh.

Quick start

curl -X POST https://api.fraudfinderbd.com/api/b2b/v1/lookup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value": "+880 1700-000001"}'

Authentication

Send your key as a Bearer token. Keep keys on your server only.

Authorization: Bearer 12|xxxxxxxxxxxxxxxxxxxxxxxx

Endpoints

POST /lookup — Look up one value
POST /lookup/batch — Look up up to 50 values (each valid value counts once)

curl -X POST https://api.fraudfinderbd.com/api/b2b/v1/lookup/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"values": ["01700000001", "fb.com/some.page"]}'

Response

{
  "data": {
    "value": "01700000001",
    "detected_type": "phone",
    "risk": "high",
    "matches": [
      {
        "type": "phone",
        "provider": null,
        "risk": "high",
        "trust_status": "community_verified",
        "reports": 5,
        "distinct_reporters": 4,
        "total_amount_lost": 125000,
        "last_reported_at": "2026-10-11T09:30:00+06:00",
        "categories": ["f-commerce"],
        "profile_url": "https://…/en/p/01J…"
      }
    ]
  }
}

Risk levels

high: Several independent, phone-verified people reported it (community verified).
medium: Two or more reports, or the owner disputed a report and it is under review.
low: One approved report, or the matter was resolved.
none: No approved reports. This is not proof the customer is safe.

Accepted values

Phone and wallet numbers in any format (+880, spaces, Bangla digits), bank accounts, NIDs, Facebook/Instagram/Telegram/WhatsApp links or handles, websites and emails. Names are refused: they are not unique.

Sandbox

Sandbox keys are free and never counted. They return fixed answers:

01700000001	high
01700000002	medium
01700000003	low
…	none

Errors

{ "error": { "code": "quota_exceeded", "message": "…" } }

401	invalid_key
402	plan_inactive
403	suspended
422	invalid_value
429	rate_limited
429	quota_exceeded

Limits

Each plan has a per-minute limit (429 with Retry-After) and a monthly quota (429 quota_exceeded). Live responses carry X-Quota-Limit and X-Quota-Remaining headers.

Fair use

Use results to add checks (e.g. ask for cash on delivery), not as the only reason to refuse someone. Reports describe people's experiences and can be disputed.

OpenAPI specification →