查询来电者名称

查询来电者名称

获取某个电话号码可用的来电者名称查询结果。这是在生产环境中执行的查询，可能向您的账户收费，即使结果来自服务缓存也可能收费。此操作不会更改您所拥有号码的呼出显示名称。

返回的名称并不代表经过验证的身份、号码所有权或拨打电话的许可。名称可能缺失、过时或经过缩写，也可能是地理位置标签，或以电话号码作为回退值。

请求

请从获准的源 IP 地址使用已启用的 API 账户。将凭据保存在服务器端的机密存储中。示例使用环境变量和一个虚构的北美号码；请勿将凭据放入网址或公开的浏览器代码中。

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  https://api.multitel.net/v3/cnam/12025550123

请以纯数字形式提供包含国家代码的完整号码，例如北美号码为以 1 开头的十一位数字。请勿依赖处理程序对标点符号或加号进行规范化处理。无需提供请求正文或地区选择参数。请根据您的预期用途向 MultiTEL 确认支持的覆盖范围。

响应

数值仅供示例；其中的费用并非报价。

{
  "status": {
    "code": 200,
    "msg": ""
  },
  "response": {
    "number": "12025550123",
    "name": "EXAMPLE NAME",
    "cost": 0.0037,
    "balance": 9.9963
  }
}

收费与对账

返回名称的结果按账户配置的 CNAM 价格收费。重复查询或从缓存获取结果的查询可能再次产生费用；此接口未提供幂等键。启用自动查询前，请先查看账户当前费率。

对于缓存名称为空的情况，响应存在一个已知限制：处理程序可能返回 API 代码 200，同时返回空名称、非零费用以及扣减后计算出的余额，尽管该处理分支并未实际从账户扣款。请勿仅凭此响应认定已产生扣费。请结合账户账单记录和重新执行的余额查询进行对账；如果结果不明确，请联系支持团队。

目前，预付余额检查要求查询前的余额至少为 0.004，此要求与配置的单次查询价格无关。已禁用购买功能的账户也会被拒绝。这些检查并不意味着此端点是用于报价或限制支出的 API。

错误与重试

请同时检查 HTTP 状态和 JSON 中的 status.code/status.msg。API 代码 403 可能表示预付余额不足、禁止购买、账户授权存在问题，或未找到来电者名称。未找到名称的处理路径可能以字符串形式返回代码。请查看具体消息，不要将所有 403 都视为凭据错误。配置冲突可能返回 API 代码 500。

计费查询完成后仍可能发生超时。只有在适合您的应用时，才应采用带退避机制且次数有限的重试，并先对结果不确定的尝试进行对账。对于被拒绝的号码，或因账户权限、余额问题导致的失败，请勿反复重试。在遵守您的协议和准确性要求的前提下，在自己的应用中缓存响应可以减少重复请求。

其他号码操作

此读取操作与呼出显示名称或 LIDB 更新、电话号码簿登记或来电者注册是不同的操作。那些操作各有其必填字段、授权要求和费用。请使用号码分配覆盖范围查询检查号码前缀表，或使用号码搜索查找可订购的号码库存。这些操作均不能证明来电者就是其自称的身份。