IPSee DEVELOPER PLATFORM · V1

Commercial API documentation

Stable endpoints for batch intelligence, business risk workflows and white-label reports. API keys are shown once when created in the admin console.

Authentication

All commercial endpoints use header authentication. Never put a key in URLs, browser code or logs.

x-api-key: soip_xxxxxxxxxxxxxxxxxxxxx

Endpoints

MethodPathPurposeUnits
GET/api/v1/ip/{ip}单 IP 查询 / Single IP lookup1
POST/api/v1/ip/batch批量查询 / Batch lookupIP 数量
GET/api/v1/ip/{ip}/export?format=csvCSV 报告 / CSV report1
GET/api/v1/ip/{ip}/export?format=excelExcel 兼容报告 / Excel-compatible report1
GET/api/v1/account套餐与白标信息 / Account and branding0

Unified response

{
  "requestId": "1b36...",
  "data": { "effective": {}, "riskScore": 18 },
  "sources": [],
  "confidence": 76,
  "algorithmVersion": "risk-v2.3",
  "cache": true,
  "detectedAt": "2026-08-28T12:00:00Z",
  "branding": {}
}

When risk evidence is insufficient, riskScore and purityScore are null. Null must not be interpreted as low risk.

Batch request example

curl -X POST https://your-domain.example/api/v1/ip/batch \
  -H "content-type: application/json" \
  -H "x-api-key: soip_xxx" \
  -d '{"ips":["8.8.8.8","1.1.1.1"],"lang":"zh-CN"}'

The batch limit depends on the plan: Free 20, Pro 100, Enterprise 500.

Interactive API explorer

The key stays in this page's memory and is not written to browser storage. Use a test key only.

Webhook

Subscribe to ip.completed and batch.completed. Every delivery includes a timestamp and HMAC-SHA256 signature.

x-soip-event: ip.completed
x-soip-timestamp: 1787899200
x-soip-signature: v1=<hex hmac>

signed_payload = timestamp + "." + raw_body

Verify timestamp, sign the raw body and reject duplicate requestIds. A webhook is disabled after 10 consecutive failures.

Status and errors

400
Invalid parameters, IP or batch size
401
Invalid, expired or revoked API key
429
Minute rate limit or monthly quota exceeded
500
Internal error; provide requestId to support