登录注册账号
版本：v1https://lookupyou.com/api/v1下载 OpenAPI

API 文档

通过 API 可以编程方式提交查询并获得结构化结果。基础地址 — https://lookupyou.com/api/v1，交换格式为 JSON，响应中的日期均为 ISO 8601（UTC）。下方是实时参考：它由服务本身提供的同一份 OpenAPI 架构生成，与真实行为一致。

密钥、余额、套餐和请求历史在控制台中。 打开控制台

认证

每个请求在 Authorization 头中携带访问密钥。密钥在控制台创建且只显示一次 — 请立即保存，无法恢复。之后界面只显示形如 lp_live_a7f3…9c21 的片段。

Authorization: Bearer lp_live_a7f3f0c98b1d4e7aa2b5c8d19c21

密钥可以限制有效期和 IP 地址列表。若密钥泄露，请在控制台吊销 — 访问立即终止：请求返回 401 且不扣费。 管理密钥

第一个请求

快速模式下的最简查询 — 程序在同一连接中等待结果。通常 6–12 秒返回；排队时更长。

curl -X POST https://lookupyou.com/api/v1/search \
  -H "Authorization: Bearer lp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product":"ssn_bg","first_name":"John","last_name":"Miller","hint":"1026 Maple Lane","mode":"sync"}'

响应 · 200 OK

{
  "request_id": "req_8f21c4",
  "client_ref": "order-1187",
  "product": "ssn_bg",
  "mode": "sync",
  "status": "completed",
  "query": { "first_name": "John", "last_name": "Miller", "hint": "1026 Maple Lane", "dob": null },
  "charged": true,
  "charge": { "source": "package", "amount_cents": 0, "requests": 1 },
  "cached": false,
  "error": null,
  "queue_position": 0,
  "duration_ms": 7840,
  "created_at": "2026-08-17T11:07:12Z",
  "finished_at": "2026-08-17T11:07:20Z",
  "result_expires_at": "2026-11-15T11:07:20Z",
  "result": {
    "found": true,
    "matches_count": 1,
    "records": [{ "full_name": "MILLER, JOHN A", "ssn": "445-72-4417", "dob": "3/14/1979", "age": 47, "addresses": [ … ], "phones": [ … ] }]
  }
}

product、first_name 和 last_name 必填，另需至少一项限定信息：hint（不含邮编的街道、城市或州）或 dob（出生日期 MM/DD/YYYY）。无限定信息时数据源不查询 — 返回 422，不扣费。

同步与异步模式

数据源只允许一个活动会话，因此查询顺序执行。mode 字段决定你如何获取结果：

  • sync（默认）— 保持连接直到结果就绪。适合用户操作触发的单次查询。我们这边的超时为 5 分钟。
  • async — API 立即返回 202 Accepted 和队列位置，结果以 search.completed 或 search.failed 事件投递到你的 Webhook。也可随时通过 GET /requests/{id} 获取。批量请求的唯一便捷方式。

队列与等待

202 响应包含 queue_position 和 eta_seconds — 前面有多少请求和大约等待时间；同步响应头中有 X-Queue-Position。当前队列长度由 GET /queue 提供。队列公平：任何套餐都没有优先权。

同时进行中的请求不超过 8 个；超出 — 429 too_many_running。对批量场景这不是问题：收到响应或通知后再发送下一个。

对已找到者的加购

如果 SSN + DOB 查询找到了人，驾照（DL）和 MVR 可从同一记录获取，无需再次访问数据源 — 更便宜且即时：POST /requests/{id}/addons，字段 addon。若记录缺少该部分，响应状态为 not_found 且不扣费。重复加购同一项从已保存结果免费返回。

加购在哪个产品之后响应内容价格
dl_after_ssnssn_bg驾照号码与签发州$1.00
mvr_after_ssnssn_bg驾照签发与到期日期，有时含性别、种族、身高$7.50
mvr_after_dldl同上 — 针对已购买的驾照号码$5.00
信用报告（CR and CS）暂不通过 API 提供 — 409 addon_unavailable。由支持团队处理。

接口

所有路径相对于基础地址。所有接口需要 Authorization: Bearer <密钥> 头。

POST/searchRun a search

Sync mode holds the connection until the source answers (usually 6–12 seconds, longer under queue). Async mode returns 202 immediately; the result is delivered to your webhook and stays available via GET /requests/{id}. Only a completed search is charged: a validation error, an unavailable source or a rate-limit rejection cost nothing.

请求体

字段类型说明示例
product必填ssn_bg | dl | mvrssn_bg — SSN + DOB (package or balance), dl / mvr — balance only
first_name必填stringJohn
last_name必填stringMiller
hintstringStreet without ZIP, city or state. Required unless dob is given1026 Maple Lane
dobstringMM/DD/YYYY. Required unless hint is given03/14/1979
modesync | async (default: sync)
client_refstringYour identifier, echoed back in responses and webhooks

响应

200Search finished (found or not found)Request
202Accepted into the queue (async mode)Accepted
401Missing, invalid, revoked or expired API keyError
402Not enough funds: no package requests left and balance is below the product priceError
403IP address is not allowed for this key, or the account is suspendedError
422Validation error — the search was not sent to the sourceError
429Rate limit: 60 requests per minute per account, or too many requests running at onceError
503Source did not answer; nothing was chargedError
GET/requestsList recent requests

参数

名称位置类型说明
limitqueryinteger
beforequerystringReturn requests created before this ISO timestamp (pagination)
statusqueryqueued | running | completed | not_found | failed | rejected

响应

200Requests without result bodies
401UnauthorizedError
GET/requests/{id}Get a request with its result

参数

名称位置类型说明
id必填pathstring

响应

200RequestRequest
401UnauthorizedError
404Unknown request idError
GET/requests/{id}/reportFull report as plain text

参数

名称位置类型说明
id必填pathstring

响应

200text/plain reporttext/plain
404No result for this request (not finished, failed, or expired)Error
POST/requests/{id}/addonsBuy an add-on from a saved result

Driver licence or MVR taken from the record already found — no second call to the source, so it is cheaper and instant. If the record has no such data, the answer is `not_found` and nothing is charged. Already bought add-ons are returned again for free.

参数

名称位置类型说明
id必填pathstring

请求体

字段类型说明示例
addon必填dl_after_ssn | mvr_after_ssn | mvr_after_dl

响应

200Add-on resultRequest
402Balance is below the add-on priceError
404Unknown request idError
409Add-on is not applicable to this request, or the credit report is not available via API yetError
GET/accountBalance, packages and prices

响应

200Account stateAccount
401UnauthorizedError
GET/queueQueue length at the source

响应

200Queue

对象

响应对象的字段。类型遵循 JSON Schema；可为 null 的字段可能没有数据。

Error
字段类型说明
errorstring · 示例: payment_required
messagestring
charged"false"
retry_afterintegerseconds, only with 429
SearchInput
字段类型说明
product必填ssn_bg | dl | mvrssn_bg — SSN + DOB (package or balance), dl / mvr — balance only
first_name必填string · 示例: John
last_name必填string · 示例: Miller
hintstringStreet without ZIP, city or state. Required unless dob is given · 示例: 1026 Maple Lane
dobstringMM/DD/YYYY. Required unless hint is given · 示例: 03/14/1979
modesync | async
client_refstringYour identifier, echoed back in responses and webhooks
Accepted
字段类型说明
request_idstring · 示例: req_8f21c4
status"queued"
queue_positioninteger
eta_secondsinteger
Request
字段类型说明
request_idstring
client_refstring | null
productstring
modesync | async
statusqueued | running | completed | not_found | failed | rejected
queryobject
query.first_namestring
query.last_namestring
query.hintstring | null
query.dobstring | null
chargedboolean
chargeobject
charge.sourcepackage | balance | none
charge.amount_centsinteger
charge.requestsinteger
charge.reasonstring | null
cachedbooleanSame query within 5 minutes — served from the saved answer for free
errorobject | null
error.codestring
error.messagestring | null
queue_positioninteger | null
duration_msinteger | null
created_atstring
finished_atstring | null
result_expires_atstring | nullResults are kept for 90 days
resultResult | null
Result
字段类型说明
foundboolean
matches_countinteger
recordsPerson[]
PersonFor ssn_bg: identity, addresses, phones, emails, relatives, civil records. For dl: name and licence numbers. For mvr: licences with dates.
字段类型说明
full_namestring
ssnstring | null
dobstring | null · 示例: 3/14/1979
ageinteger | null
genderstring | null
akastring[]
addressesobject[]
addresses[].rawstring
addresses[].citystring | null
addresses[].statestring | null
addresses[].zip_codestring | null
addresses[].date_fromstring | null
addresses[].date_tostring | null
addresses[].is_currentboolean
phonesobject[]
phones[].numberstring
phones[].formattedstring
phones[].phone_typestring | null
phones[].carrierstring | null
emailsstring[]
relativesobject[]
relatives[].full_namestring
relatives[].relationship_typestring | null
relatives[].dob_yearstring | null
relatives[].current_ageinteger | null
civil_recordsobject | null
civil_records.bankruptciesinteger
civil_records.liensinteger
civil_records.judgmentsinteger
driver_licensesobject[]
driver_licenses[].numberstring
driver_licenses[].statestring | null
driver_licenses[].issue_datestring | null
driver_licenses[].expiration_datestring | null
driver_licenses[].genderstring | null
driver_licenses[].racestring | null
driver_licenses[].heightstring | null
Account
字段类型说明
nicknamestring
balance_centsinteger
available_centsintegerbalance minus reservations of running searches
package_requests_leftinteger
packagesobject[]
packages[].idstring
packages[].namestring
packages[].requests_leftinteger
packages[].requests_totalinteger
packages[].expires_atstring
pricesobjectyour price per product/add-on, cents
limitsobject
limits.requests_per_minuteinteger
limits.concurrent_requestsinteger

响应码

所有错误体格式相同：error（机器可读代码）、message（文本）、charged: false。429 时另有 retry_after（秒）和 Retry-After 头。

代码error含义是否扣费
200—查询完成：status 为 completed（已找到）或 not_found（无匹配）是 — 查询已执行
202—已加入队列（mode: async）否 — 执行时扣费
401unauthorized无密钥、密钥错误、已吊销或已过期否
402payment_required套餐无剩余且余额低于产品价格否
403forbiddenIP 不在密钥允许列表中，或账号已暂停否
404not_found未知 request_id否
409addon_unavailable加购不适用于此请求，或暂未通过 API 提供否
422validation_error参数被拒绝：无限定信息、地址含邮编、非拉丁字母、日期错误否
429rate_limited / too_many_running每账号每分钟超过 60 次请求，或进行中的请求过多否
503source_unavailable数据源无响应否
特殊情况 — 找到了人但记录缺少所需部分（SSN 无完整出生日期、DL 无号码、MVR 无日期）。此类响应为 not_found 且永不扣费。

Webhook 通知格式

地址和密钥在控制台设置。通知是带 JSON 体的 POST：与 GET /requests/{id} 返回的 Request 对象相同，外加 event 字段。2xx 响应视为投递成功，否则重试。请快速响应 — 超时 5 秒，处理放到后台。

事件

  • search.completed — 查询完成，结果就绪（包括 not_found）
  • search.failed — 查询未执行，未扣费
  • package.low — 剩余查询低于通知设置中的阈值
  • package.expiring — 套餐即将到期

头部：X-Signature — 签名，X-Event — 事件，X-Delivery-Id — 投递标识（用于去重），X-Request-Id，X-Timestamp。

POST https://your-service.com/hooks/search
Content-Type: application/json
X-Signature: sha256=6b1c…f0a2
X-Event: search.completed
X-Delivery-Id: 4c1d0e9a-…
X-Request-Id: req_8f21c4
X-Timestamp: 1786901240

{
  "event": "search.completed",
  "request_id": "req_8f21c4",
  "client_ref": "order-1187",
  "product": "prod_ssn_bg",
  "status": "completed",
  "charged": true,
  "error": null,
  "finished_at": "2026-08-17T11:07:20Z",
  "result": { "found": true, "matches_count": 1, "records": [ … ] }
}

签名校验

X-Signature 为 sha256= 加上原始请求体的 HMAC-SHA256，密钥为控制台中的 Webhook 密钥。在解析 JSON 之前按请求体字节计算 HMAC，并以恒定时间比较。

投递重试

若你的端点返回非 2xx 或 5 秒内未响应，将在 1、5、15 和 60 分钟后重试 — 共四次。所有尝试在控制台可见，未投递的可在那里手动重发。连续三次失败后发送邮件。结果不会丢失 — 可通过 GET /requests/{id} 获取。

何时扣费

仅对完成的查询扣费：数据源已响应且结果已传递给你。无匹配也算完成的查询 — 工作已执行。参数错误、数据源不可用、频率限制拒绝和已吊销密钥均不扣费。每个响应都有 charged 字段和包含扣费来源的 charge 对象。

套餐请求即 ssn_bg 查询：先消耗最早到期的套餐，然后按零售价从余额扣。产品 dl、mvr 和加购始终从余额扣费。

5 分钟内的相同请求（产品和所有字段一致）从已保存结果返回：cached: true，不扣费。

结果保留 90 天（result_expires_at），之后删除；请求元数据保留在历史中。

频率限制

所有套餐统一限制 — 每账号每分钟 60 次请求，同时进行 8 个请求。不出售、不可付费提高，仅用于防止单个客户的循环程序占满队列。当前状态在每个响应的头中返回：

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 34
X-Request-Id: req_8f21c4
X-Queue-Position: 3

代码示例

三种语言的快速模式。替换为你自己的密钥和地址。

curl

curl -X POST https://lookupyou.com/api/v1/search \
  -H "Authorization: Bearer lp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product":"ssn_bg","first_name":"John","last_name":"Miller","hint":"1026 Maple Lane","mode":"sync"}'

Python

import requests

r = requests.post(
    "https://lookupyou.com/api/v1/search",
    headers={"Authorization": "Bearer lp_live_YOUR_KEY"},
    json={"product": "ssn_bg", "first_name": "John", "last_name": "Miller", "hint": "1026 Maple Lane"},
    timeout=300,
)
data = r.json()
if r.status_code == 200 and data["status"] == "completed":
    print(data["result"]["records"][0]["ssn"])
else:
    print(r.status_code, data.get("error"), data.get("message"))

Node.js

const res = await fetch("https://lookupyou.com/api/v1/search", {
  method: "POST",
  headers: { Authorization: "Bearer lp_live_YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ product: "ssn_bg", first_name: "John", last_name: "Miller", hint: "1026 Maple Lane" }),
});
const data = await res.json();
if (res.ok && data.status === "completed") console.log(data.result.records[0].ssn);
else console.log(res.status, data.error, data.message);

异步模式与 Webhook

提交到队列并在你的服务器上校验通知签名。

// 1. отправка в очередь
const accepted = await fetch("https://lookupyou.com/api/v1/search", {
  method: "POST",
  headers: { Authorization: "Bearer lp_live_YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ product: "ssn_bg", first_name: "John", last_name: "Miller", hint: "TX", mode: "async", client_ref: "order-1187" }),
}).then((r) => r.json());
// { request_id: "req_8f21c4", status: "queued", queue_position: 3, eta_seconds: 32 }

// 2. приём вебхука (Express)
import crypto from "node:crypto";
app.post("/hooks/search", express.raw({ type: "application/json" }), (req, res) => {
  const expected = "sha256=" + crypto.createHmac("sha256", WEBHOOK_SECRET).update(req.body).digest("hex");
  const given = req.get("X-Signature") ?? "";
  if (given.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))) return res.sendStatus(401);
  const event = JSON.parse(req.body);   // { event: "search.completed", request_id, client_ref, status, charged, result }
  res.sendStatus(200);                   // ответить сразу, обработку — фоном
  setImmediate(() => handle(event));
});

更新日志

  • v1.0 — ssn_bg / dl / mvr 的同步与异步查询、DL 和 MVR 加购、带签名和重试的 Webhook、请求历史、余额与套餐、OpenAPI 架构。