场景：云呼叫中心、外呼SaaS、营销短信平台前置风控
一、业务背景
对于云外呼服务商、金融回访、房产邀约、教培获客等具备批量外呼、营销短信触达能力的企业，骚扰投诉一直是一个高频风险点。一旦用户提交投诉，企业可能面临呼出限流，严重时还会影响码号与通信相关资质。
二、接口能力说明
运营商防骚扰名单查询API，传入手机号，可识别有历史投诉记录、存在投诉意向的号码。开发者可以根据自身业务风险容忍度，自主选择筛查严格等级。
请求参数
| 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|
| key | 是 | string | 接口密钥，在服务商个人中心获取 |
| phone | 是 | string | 待筛查11位手机号 |
| level | 是 | string | 拦截等级，可选值：1、2、3 |
重点区分：
level不是号码自带的风险标签，是调用方配置的筛查策略，数值越大规则越严格，拦截号码越多。
- 1 一般：宽松模式，仅拦截极少数极高风险号码。适合售后回访、调研通知这类低投诉业务，尽可能保留有效线索。
- 2 敏感：中等模式，只要号码存在历史投诉记录就拦截。绝大多数营销外呼、营销短信场景推荐使用该等级。
- 3 高危：严格模式，同时拦截有投诉记录、存在投诉意向的号码。适合线路资源宝贵、管控严格的云外呼平台、金融类回访业务。
返回结果示例
{
"code": 1,
"msg": "操作成功",
"data": {
"phone": "18577111111",
"msg": "非风险号码",
"forbid": 0,
"province": "广西",
"city": "南宁市",
"zipcode": "530000"
}
}
返回字段说明：
forbid：拦截标识，0=建议放行；1=建议拦截，不进行营销触达province/city/zipcode：手机号号段归属地附加信息，可按需展示，不参与风控判断
三、开发接入示例
接口请求方式为 POST，下面提供 Python、PHP 两段常用后端调用代码。
Python 示例
import requests
url = "https://api.tanshuapi.com/api/phone_black/v1/index"#接口地址
params = {
"key": "你的key",
"phone": "待查询手机号",
"level": "等级"
}
resp = requests.post(url, data=params)
print(resp.json())
PHP 示例
<?php
$url = "https://api.tanshuapi.com/api/phone_black/v1/index";
$postData = [
'key' => '你的key',
'phone' => '待查询手机号',
'level' => '2'
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);
var_dump(json_decode($result,true));
?>
四、典型集成方案
- 实时外呼校验（云呼叫/CRM）：坐席发起呼叫前自动调用接口，
forbid=1时拦截呼出，弹窗提示风险。 - 批量线索清洗：导入号码池批量预处理，把风险号码过滤，生成可拨打清单；批量调用注意控制QPS，避免超限。
- 106短信平台前置过滤：营销短信任务提交前筛查；验证码、纯通知短信推荐使用 level=1。
五、常见FAQ
Q1：个人开发者可以申请接入吗？
A1：不支持个人接入，仅面向完成企业实名审核的客户开放，仅限企业自身业务风控使用。
Q2：是否需要持久化保存查询日志？
A2：建议留存查询日志，记录手机号、查询时间、选用的level、返回结果。当运营商或者监管核查时，日志可以作为企业落实前置风控的凭证。
Q3：接口返回非风险号码，外呼之后仍然产生投诉是什么原因？
A3：名单存在数据同步延迟，用户有可能刚刚提交拒收申请，数据还未更新；也存在用户本次通话临时反感而投诉的情况。保留风控筛查记录，在核查场景下可以证明企业已经主动做好风险管控。
