查找可用电话号码

选择单个前缀

先调用国家和覆盖区域查询接口，再以不分组的方式调用 getprefixes。复制所选前缀的 uuid。如果 returns_numbers 为 0，则该前缀会在下单时分配号码；请使用返回的 next_function，而不要强求获取逐个号码的列表。

浏览数量受限的一批结果

进行常规搜索时，请使用 compact=1，并在路径和 quantity 查询参数中都填写期望的批次大小，如下所示。此接口没有页码或游标参数。精简结果只是一个样本；重复请求并不能保证得到与此前结果不重叠的下一页。不要将空结果或少量结果解读为库存总量。

查找易记的数字组合

请提供 number_filter_mode=contains 或 ends_with，同时提供 number_filter_value。该值必须包含 1–15 位数字。搜索可能先获取有限的候选批次，再应用筛选条件，因此可能遗漏其他符合条件的库存。如果需要由支持此搜索的来源执行强制筛选，请获取一个 pid 选择器（由 MultiTEL 提供），并使用 filter_required=1；未选择来源或所选来源不受支持时，将返回 API 错误。

核查所选号码

读取 number、info.uuid、所选的 price[].uuid、可用功能名称及注册要求，以上信息均须从同一结果中读取。price 数组可能提供多个方案，其通道数量和费率各不相同。金额字段和数量可能以字符串形式编码。可选元数据（包括 info.state）因来源而异；不要要求所有来源的州或地区信息都采用统一结构，也不要根据 ID 推断价格。

在非流式处理路径中，会先对候选号码去重，并在各来源之间分配名额，然后按首个方案的月费对选出的批次排序。其他处理路径可能更早开始流式输出，因此无法保证每个请求都经过全局排序或去重。排序也不能证明返回的样本包含整个目录中最便宜的号码。

另行下单并确认结果

搜索不会购买或预留任何号码。请保留返回的号码和方案标识符，以便在同一账户下的下单流程中使用。提交订单前，请核查实际方案、相关要求和费用。注册要求可能导致激活延迟；搜索结果并不确定任何固定的激活期限。

请求

请使用已启用的 MultiTEL API 账户：密码账户使用 HTTP Basic 凭据，令牌账户使用 Authorization: Bearer。账户权限及其 IP 限制均适用。请参阅通用身份验证指南。

参数通过路径和 URL 查询参数传递。公开的搜索流程使用 GET。处理程序也接受部分表单或请求参数值，但这并不是使用 JSON 请求体的搜索 API。

curl --fail-with-body --get \
  --user "${MULTITEL_API_USERNAME}:${MULTITEL_API_PASSWORD}" \
  --data-urlencode "compact=1" \
  --data-urlencode "quantity=10" \
  "https://api.multitel.net/v3/getnumbers/${PREFIX_ID}/10"

路径参数
名称	类型	是否必填	说明
`prefix_id`	string	是	未分组的 getprefixes 响应所返回的单个前缀 ID。请原样复制；不要用国家、覆盖区域、分组前缀或资费方案的 ID 替代。
`quantity`	integer	否	目标获取数量，默认值为 1。非正数值会变为 1。仅靠路径中的 quantity 无法可靠地限制整体结果数量：未固定来源且没有 quantity 查询参数的搜索可能扩大获取范围，在其他处理之前，每个来源最多返回 50 条记录。进行常规的限量浏览时，请使用 compact=1，并像示例一样在查询参数中再次填写期望数量。

查询参数
名称	类型	是否必填	说明
`quantity`	integer	否	请求的最终批次大小。非空值会转换为整数，最小值为 1。在未固定来源的非流式处理路径中，此参数限制最终分配数量。它不会强制服务找到这么多号码。固定到某一来源的精简搜索可能返回该来源的精简批次，而不受此数量限制。
`compact`	string	否	使用 1、true 或 on 可获取较小的非流式响应，在最终分配之前，每个来源最多提供 10 条记录。结果只是当前获取库存的样本，并非完整目录。
`number_filter_mode`	string	否	可选的数字组合匹配模式：contains 或 ends_with。还须提供 number_filter_value。筛选时会检查规范化后的电话号码数字；搜索不会遍历全部库存，因此无法保证找出所有可能的匹配项。
`number_filter_value`	string	否	由 1 至 15 位数字组成，不含空格、+ 或标点符号。开头的零有意义；请以文本形式发送。
`filter_required`	string	否	高级选项：设置为 1、true、yes 或 on 时，必须明确选择一个支持该筛选模式的库存来源。否则 API 返回的 status.code 为 422。常规目录浏览无需使用此选项。
`pid`	string	否	由 MultiTEL 提供的高级库存选择器。接受数字形式及受支持的 32 字符十六进制形式；无法识别的值会被静默忽略。常规使用时请省略。不要从价格 ID 推导选择器，也不要认为任意选择器都能将库存严格限定为某一来源。

响应

返回一个包含 status 和 response 的 JSON 对象。成功时，status.code 为 200，response 为号码条目数组。status.results 表示返回数组中的条目数量；status.msg 可以是 Results: N，流式响应中也可以是 OK。未使用 compact=1 时，某些搜索会逐步写入 response 数组，并以 status 结束，因此请等待完整的 JSON 响应体。这不是以换行符分隔的 JSON。即使 HTTP 传输成功，也要检查 status.code。下方展示了典型字段；各来源的专有元数据和可选字段有所不同。请将每个标识符视为不透明值，不解读其内部含义，并将号码与为其选定的 price[].uuid 一起保存。

以下仅示意响应结构，并非实时账户数据或当前报价。

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "number": "12125550123",
      "info": {
        "uuid": "NUMBER_ID_FROM_RESPONSE",
        "prefix_uuid": "PREFIX_ID_FROM_RESPONSE",
        "area_uuid": "AREA_ID_FROM_RESPONSE",
        "country_uuid": "COUNTRY_ID_FROM_RESPONSE",
        "country_iso": "US",
        "prefix": "+1212",
        "name": "Example area",
        "state": "US"
      },
      "price": [
        {
          "uuid": "PRICE_PLAN_ID_FROM_RESPONSE",
          "per_minute": "0.01",
          "per_sms": "0",
          "per_mms": "0",
          "free_minutes": "0",
          "setup_price": "1.00",
          "monthly_price": "2.00",
          "yearly_price": "0",
          "channels": "2"
        }
      ],
      "contract": {
        "term": "1 month",
        "renewal": "monthly",
        "notice": "none"
      },
      "restrictions": {
        "needs_registration": "0",
        "restrictions": ""
      },
      "features": [
        "voice"
      ],
      "overflow": "0"
    }
  ]
}

错误

401：身份验证失败。凭据无效或缺失，或 API 账户访问被拒绝时，不会产生搜索结果。
404：Invalid prefix ID、Invalid country、Invalid area 或 No numbers found。请读取 status.msg；错误响应不是号码数组。
400：response.code 中的 NUMBER_FILTER_INVALID：模式无效、值并非由 1–15 位数字组成，或使用了 filter_required 却未同时提供模式和值。
422：response.code 中的 NUMBER_FILTER_UNSUPPORTED：该前缀在下单时才分配号码（reason=order_only_prefix，且 next_function 指明下单路由），或者明确选定的来源无法支持所要求的筛选。

可用性与副作用

此处理程序执行搜索并准备报价；它不会提交号码订单或扣除号码购买费用。它可能刷新目录缓存、移除过期的库存缓存、保存账户范围内的资费方案，以及写入搜索日志。
可用性只是某一时刻的查询结果，并不代表预留。后续订单可能失败，也可能返回不同的可用性信息。重新尝试购买前，请先核对订单结果。
价格因账户而异。请保留所选方案 ID，以供同一账户使用，并另行核查订单条款和费用；仅凭此接口无法证明某一价格会一直有效至日后下单时。
示例号码和价格均为用于展示响应结构的虚构数据，并非实时报价。功能、通道数量、合约期限及注册信息必须从实际选定的结果中读取。
某些注册说明包含带格式的文本或链接。在您自己的应用中渲染返回的字符串时，请将其视为不可信数据。
移动号码的可用性及相关标记取决于账户资格和库存。仅凭目录中的前缀或 is_mobile 标记，无法确定某个具体号码的移动通信功能。