管理你的电话号码

号码分配到你的工作区后，号码 API 允许你列出持有的号码、通过任意标识查找某个号码、为其设置名称和自定义引用，以及在不再需要时取消或释放号码。读取操作需要一个具有 numbers 作用域读取级别的 API 密钥；更改、取消或释放号码需要写入级别。

控制台中的 Numbers 页面显示相同的号码。

列出你持有的所有号码

GET /v1/numbers 返回当前分配到你工作区的号码，按最新优先排列，专用和共享号码均包含在内。每页默认显示 25 个号码，可通过 limit 设置为最多 100 个。

列表通过游标分页。将页面的 next_cursor 作为 starting_after 传回以读取下一页，当 next_cursor 为 null 时停止。SDK 会自动为你跟踪游标。以下示例将列表筛选为 country_code: "GB"；去掉筛选条件可遍历你持有的所有号码：

for await (const allocated of bird.numbers.list({ country_code: "GB" })) {
  console.log(allocated.number, allocated.kind, allocated.status);
}

for allocated in client.numbers.list(country_code="GB"):
    print(allocated.number, allocated.kind, allocated.status)

for allocated, err := range client.Numbers.List(context.Background(), bird.NumbersListParams{
	CountryCode: "GB",
}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(allocated.Number, allocated.Kind, allocated.Status)
}

$page = $bird->numbers->list(['country_code' => 'GB']);
foreach ($page as $allocated) {
    echo $allocated->getNumber(), ' ', $allocated->getKind(), ' ', $allocated->getStatus(), "\n";
}

curl "https://us1.platform.bird.com/v1/numbers?country_code=GB" \
  -H "Authorization: Bearer bk_us1_..."

使用与你密钥的 bk_{region}_ 前缀匹配的区域主机：https://us1.platform.bird.com 或 https://eu1.platform.bird.com。

列表不包含总数。要统计你的号码数量，请遍历所有页面并计算条目数。传递 include_total 会被拒绝，返回 422 和 E01029。

每个条目包含其 status 和 ownership。如果某个国家/地区不要求所有权证明文件，ownership 为 null。号码概览解释了每种状态的含义。要提交号码正在等待的证明文件，请参阅提交号码的所有权证明文件。

每个条目还包含 pricing，即你的组织为该号码支付的费用（不含税）：

• recurring_price 是你按 recurring_period 计的费率，以该号码的计费货币计价。该货币就是你的账单货币，除非该号码的订阅开始于你的账单货币变更之前；这类号码保留其订阅自身的货币，由 currency_code 标明。
• intervals_per_charge 表示一次续费收取多少个 recurring_period。税前周期费用为 recurring_price 乘以 intervals_per_charge。固定价格的号码覆盖整个周期，因此其 intervals_per_charge 为 1。

对于 shared 号码以及没有有效订阅的号码，pricing 为 null。当号码的订阅没有适用价格时，其价格为 null，且 pricing.error: null；请联系销售为其定价。如果无法读取价格，pricing.error 包含 E14009，价格为 null。使用指数退避重试 GET /v1/numbers/{number_id}。号码仍可继续管理；不要为了刷新价格而重复已完成的更新或取消操作。

控制台和 API 使用相同的价格解析逻辑。固定价格保留其现有条款；否则显示的是当前费率，续费前可能会变动。它不会显示之前订单的收费金额。设置了 releases_at 的号码在释放前保留其 pricing，之后不再续费。

在列表中查找号码

列表筛选条件可以组合使用，因此国家或功能筛选条件会与其他条件同时生效。

number 可以查找单个号码，无论你的记录中使用哪种格式。+31612345678 和 0031612345678 会解析为同一个号码。类似 0612345678 这样的本地格式仅在 country_code 指定了国家时才能解析：

curl "https://us1.platform.bird.com/v1/numbers?number=0612345678&country_code=NL" \
  -H "Authorization: Bearer bk_us1_..."

当你传入完整号码，或带有 country_code 的本地格式，且不附加其他筛选条件时，空的 data 数组表示该号码未分配到你的工作区，包括你已释放的号码。不带 country_code 的本地格式（例如单独使用 0612345678）也会返回空列表，因此不能以此证明该号码不属于你。

search 对号码、名称或引用进行部分匹配，不区分大小写。reference 返回具有完全匹配引用的号码，区分大小写：

curl "https://us1.platform.bird.com/v1/numbers?reference=STORE-042" \
  -H "Authorization: Bearer bk_us1_..."

prefix 返回以你给定数字开头的号码，这些数字的含义取决于 country_code：

• 带有 country_code 时，数字为本地号码，匹配位置紧跟在国际区号之后。prefix=6&country_code=NL 返回以 +31 6 开头的荷兰号码。
• 不带 country_code 时，数字从完整号码的开头开始匹配。单独使用 prefix=6 会返回国际区号以 6 开头的号码（例如澳大利亚的 +61 号码），因此不会找到你的荷兰手机号码。它也会匹配以这些数字开头的短码。

为号码命名并设置引用

每个号码包含两个由你自定义的标签。name 用于区分你的号码，例如 Support line。reference 用于存储你自己记录中的标识符，例如客户或门店 ID，且不要求唯一。两者均适用于专用和共享号码，最多 100 个字符。

使用 PATCH /v1/numbers/{number_id} 设置它们。省略的字段保留当前值，发送为 null 的字段会被清除。前后空白会被自动去除。

const allocated = await bird.numbers.update("nda_01krdgeqcxet5s7t44vh8rt9mg", {
  name: "Support line",
  reference: "STORE-042",
});
console.log(allocated.name, allocated.reference);

allocated = client.numbers.update(
    "nda_01krdgeqcxet5s7t44vh8rt9mg", name="Support line", reference="STORE-042"
)
print(allocated.name, allocated.reference)

allocated, err := client.Numbers.Update(ctx, "nda_01krdgeqcxet5s7t44vh8rt9mg", bird.NumbersUpdateParams{
	Name:      bird.Value("Support line"),
	Reference: bird.Value("STORE-042"),
})
if err != nil {
	log.Fatal(err)
}
if allocated.Name != nil {
	fmt.Println(*allocated.Name)
}
if allocated.Reference != nil {
	fmt.Println(*allocated.Reference)
}

$allocated = $bird->numbers->update(
    'nda_01krdgeqcxet5s7t44vh8rt9mg',
    (new \MessageBird\Wire\Model\NumberUpdate())->setName('Support line')->setReference('STORE-042'),
);
echo $allocated->getName(), ' ', $allocated->getReference(), "\n";

curl -X PATCH "https://{region}.platform.bird.com/v1/numbers/{number_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support line",
    "reference": "STORE-042"
  }'

响应为 200，包含更新后的号码。要清除引用并保留名称，请将引用设为 null，不传名称字段：

curl -X PATCH "https://us1.platform.bird.com/v1/numbers/nda_01krdgeqcxet5s7t44vh8rt9mg" \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{"reference": null}'

要在购买号码时设置引用，请在 POST /v1/numbers/orders 上传入 reference。如果订单需要等待运营商处理，引用会一直保留，直到号码分配完成，此后号码将一直携带该引用。

查找号码对应的语音记录

支持语音的号码有两个标识符。GET /v1/numbers 上的 id 以 nda_ 开头（专用号码）或以 nal_ 开头（共享号码），号码操作使用该标识符。语音操作（包括设置来电路由的操作）使用号码的语音记录，其 id 以 vnu_ 开头。将 nda_ 或 nal_ ID 传给语音操作会被拒绝，返回 422。

要在两者之间转换，请通过电话号码搜索语音号码。这需要 voice_management 作用域的读取权限：

curl "https://us1.platform.bird.com/v1/voice/numbers?search=%2B31612345678" \
  -H "Authorization: Bearer bk_us1_..."

条目的 id 是 vnu_ 标识符，其 provider.number_id 是同一号码的 nda_ 或 nal_ 标识符。接听来电介绍了如何从这里开始路由号码。

语音记录有自己的 name。通过 PATCH /v1/numbers/{number_id} 为号码命名不会更改语音记录的名称，反之亦然。

释放号码

你可以通过两种方式归还专用号码：

• 在已付费周期结束时。 DELETE /v1/numbers/{number_id} 会停止号码续费。号码在当前计费周期结束前继续工作，届时自动释放。202 响应返回号码，其中 releases_at 设为该时间，再次请求返回相同的 releases_at。取消操作不可撤销。没有订阅的号码（例如免费分配给你的号码）会立即释放，响应为 200，号码的 status 设为 released。
• 立即释放。 POST /v1/numbers/{number_id}/release 立即释放号码，包括已计划取消的号码。当前周期的剩余时间不予退款。购买和释放号码展示了每种 SDK 中的调用方式。

当号码的续费付款逾期时，两个请求都返回 409，直到完成付款。

无论选择哪种释放方式，发送请求时都应附带 Idempotency-Key，以确保重试安全：相同的键会重放首次响应并附带 Idempotency-Replay: true 响应头，而对已释放号码发起的新请求会返回 404 和 E01008。幂等性说明了键的保留时长。

在预定的取消生效之前，号码照常可读并携带 releases_at。释放之后：

• 你将无法再使用该号码，其订阅也不会续费。
• GET /v1/numbers/{number_id} 和该号码的语音记录返回 404，号码从 GET /v1/numbers 中移除。
• 该号码的订单保留在 GET /v1/numbers/orders 中，其 number_id 现在返回 404。
• 该号码需经过 30 天冷却期后才能重新出售，因此你无法立即回购同一号码。

后续步骤

• 接听来电将号码路由到 SIP 中继、转接或序列。
• 购买和释放号码演示通过 API 完成购买的流程。
• Numbers API 参考记录了每个操作和字段。