号码标记查询

接口说明

号码标记查询用于聚合查询指定手机号在多家主流平台上的标记与认证情况，返回是否被标记、各平台状态及具体标记标签与标记量。

适合风控反欺诈、客服来电识别、电销号码过滤等场景使用。调用时需在 Query 中传入密钥。

调用地址

/apis/tmcheckmark

请求方式

GET

鉴权说明

调用本接口必须携带密钥，密钥通过 Query 参数传递，参数名为 key。

示例形式：/apis/tmcheckmark?key=后台KEY&phone=17264353835

密钥为接口调用凭证，请勿泄露给无关人员。密钥缺失或无效时，请求将被拒绝。

请求参数

参数取值说明

• key：使用本站签发的调用密钥，直接作为请求地址的查询参数附加。密钥缺失或无效时该请求无法受理。
• phone：仅支持中国大陆手机号，填写 11 位数字号码，无需添加国家码、区号或 +、空格、短横线等分隔符。

请求频率上限约为每分钟 60 次，超出后请求将被限流，请合理安排查询节奏。

成功响应示例

调用成功后，服务以 JSON 形式返回聚合查询结果，code 为 200，phone 为被查询号码，isMarked 表示是否命中任一平台的标记或认证，region 为号码归属地，results 为各平台的明细数组。

{
  "code": 200,
  "phone": "17264353835",
  "isMarked": true,
  "region": "重庆 移动",
  "results": [
    {
      "platform": "腾讯手机管家",
      "status": "被标记",
      "tags": [
        {
          "name": "快递送餐",
          "count": 6
        }
      ]
    },
    {
      "platform": "360手机卫士",
      "status": "被标记",
      "tags": [
        {
          "name": "快递送餐",
          "count": 13
        }
      ]
    },
    {
      "platform": "泰迪熊",
      "status": "被标记",
      "tags": [
        {
          "name": "快递外卖",
          "count": 20
        }
      ]
    },
    {
      "platform": "百事通",
      "status": "未标记"
    },
    {
      "platform": "移动",
      "status": "未标记"
    },
    {
      "platform": "电话邦",
      "status": "未标记"
    },
    {
      "platform": "小米",
      "status": "认证",
      "name": "京东快递"
    },
    {
      "platform": "搜狗",
      "status": "未标记"
    },
    {
      "platform": "联通",
      "status": "被标记",
      "tags": [
        {
          "name": "快递送餐",
          "count": 6
        }
      ]
    },
    {
      "platform": "百度",
      "status": "被标记",
      "tags": [
        {
          "name": "商业营销"
        }
      ]
    }
  ]
}

响应字段说明

说明：results 中各平台返回的字段并不完全一致，未标记的平台仅返回 platform 与 status；请以字段是否存在为准进行解析，不要假定每个平台都带有 tags 或 name。

错误响应示例

当请求未通过校验、密钥无效、积分不足或接口不可用时，统一以 JSON 形式返回错误信息，HTTP 状态码可能为 200，业务结果需以响应体中的 errcode 字段为准。

未提供调用密钥：

{
  "code": 0,
  "msg": "未提供调用密钥",
  "errcode": 11001
}

密钥错误：

{
  "code": 0,
  "msg": "密钥错误",
  "errcode": 11002
}

积分余额不足：

{
  "code": 0,
  "msg": "积分余额不足",
  "errcode": 11004
}

请求过于频繁（超过每分钟约 60 次的 QPM 限制）：

{
  "code": 0,
  "msg": "请求过于频繁",
  "errcode": 11005
}

接口维护中：

{
  "code": 0,
  "msg": "接口维护中",
  "errcode": 11006
}

请求方式不允许（该接口仅支持 GET）：

{
  "code": 0,
  "msg": "请求方式不允许",
  "errcode": 11018
}

当前 IP 不在白名单内：

{
  "code": 0,
  "msg": "当前IP不在白名单内",
  "errcode": 11019
}

密钥已过期：

{
  "code": 0,
  "msg": "密钥已过期",
  "errcode": 11023
}

接口不存在：

{
  "code": 0,
  "msg": "接口不存在",
  "errcode": 11013
}

服务暂不可用：

{
  "code": 0,
  "msg": "服务暂不可用",
  "errcode": 11017
}

以上示例仅展示响应结构，实际返回的 msg 文案可能随场景略有差异，请始终以 errcode 作为判断依据。

业务错误码说明

下表列出本站全部业务错误码及其含义，调用方应针对不同错误码做差异化处理，例如：11005 建议退避重试，11004 需充值后重试，11006、11009、11010、11017 属于临时性不可用，可稍后重试，其余多为请求侧问题，需修正参数或配置后再调用。

调用示例

终端 curl（bash）

curl "https://你的接口域名/apis/tmcheckmark?key=YOUR_KEY&phone=17264353835"

PHP

// PHP 示例：以 GET 方式请求，密钥通过 Query 参数 key 传递
$key   = 'YOUR_KEY';
$phone = '17264353835';

$url = 'https://你的接口域名/apis/tmcheckmark?' . http_build_query([
    'key'   => $key,
    'phone' => $phone,
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

注意事项

• 密钥通过 Query 参数 key 传递，属于首选且唯一的鉴权方式；请勿将密钥拼接到前端页面、公开仓库或客户端代码中，避免被他人抓取后消耗你的调用额度。
• 建议在服务端调用本接口，并对密钥做定期轮换；若怀疑泄露，请立即重置。
• 调用地址为 /apis/tmcheckmark，请求方式为 GET，请使用 HTTPS 访问，避免密钥与手机号在明文链路上被截获。
• phone 必须为有效手机号，请勿传入带空格、连字符或国际区号的格式，否则可能返回参数错误或空结果。
• 频率限制约为每分钟 60 次，超限会被拒绝；批量查询时请自行控制并发并在失败后做退避重试。
• 本接口按次计费，重复查询同一号码同样计费，建议对结果做本地缓存（号码标记短期内变化不大）。
• 返回的 status 有「认证」「被标记」「未标记」等取值，tags 仅在被标记时出现，且部分标签可能不含 count 字段，解析时请做兼容判断。
• 同一号码在不同平台上的结论可能不一致，请以 isMarked 作为整体判断依据，并结合具体平台标签做业务决策。
• 号码标记数据来自第三方平台，存在更新延迟，仅供风控参考，不建议作为唯一判断依据。