提交号码的所有权材料

有些国家/地区要求在号码承载流量之前说明号码的持有人。在这些材料获得接受且号码注册完成之前，号码已分配给你并开始计费，但其 status 为 pending_ownership_registration：它不能接听或拨打语音电话，也不能发送 SMS。当号码的 status 为 active 且 ownership.blocked_at 为 null 时，号码即可承载流量。你可以在控制台或通过 API 提交材料，两种方式使用相同的要求、审核规则和注册流程。号码的 ownership.next 会列出每个步骤，包括何时需要提交新的申请。

你提交的答案是以你企业名义作出的法律陈述。答案获得接受后，会以其所描述企业的名义转交给该国家/地区的运营商或监管机构。因此，提交前请与负责这些信息的人员确认，不要让自动化任务提交无人核对过的答案。

开始之前

• 要在控制台中提交，你的工作区角色必须具有编辑合规信息的权限。没有该权限时，号码会显示所有权状态，但不显示提交按钮。
• 要通过独立的合规端点提交，需要一个具有 compliance 写入级别权限范围的 API 密钥。只有读取级别的密钥可以查看要求和审核进度，但不能提交。读取号码还需要 numbers 读取级别权限范围。在控制台的密钥选择器中，compliance 位于 Compliance 下。
• 号码的 nda_ 标识符，可从 GET /v1/numbers 获取。在列表中查找号码介绍了查找方法。

API 示例从 BIRD_API_KEY 读取密钥，从 BIRD_API_URL 读取其区域主机，从 NUMBER_ID 读取号码标识符。后续每个步骤都会注明它所设置的变量。jq 命令从响应中提取一个字段；如果不使用 jq，请手动读取该字段。

检查号码是否需要提交材料

使用 GET /v1/numbers/{number_id} 读取号码：

curl "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \
  --header "Authorization: Bearer $BIRD_API_KEY"

将号码的 country_code 保存为 COUNTRY_CODE；读取要求和提交材料时都需要它：

COUNTRY_CODE=$(curl -s "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \
  --header "Authorization: Bearer $BIRD_API_KEY" | jq -r .country_code)

如果号码所在国家不要求提交材料，ownership 为 null。如果我们无法读取材料的进度，且号码上没有记录任何封锁，它也为 null；此时请重新读取号码。其他情况下，它包含：

• status：needs_input 表示答案缺失或需要更正；under_review 表示你的答案正在审核；approval_pending 表示材料已被接受，但注册仍在进行中；设置了 blocked_at 时，通话和发出的 SMS 仍被封锁。approved 表示注册已获批准，但设置了 blocked_at 时，通话和发出的 SMS 仍被封锁。not_required 表示不再需要任何内容。rejected 表示提交已关闭或更正期限已过，不再接受更正。如需重新开启，请联系支持团队。unknown 表示无法读取状态；请重新读取号码。
• next：推进材料审核的各个步骤，按顺序排列。wait 步骤表示目前无需你做任何操作。每次变更后请重新读取。
• submission_id：该号码最近一次的提交，存在提交时才会出现。
• blocked_at：所有权封锁的开始时间；封锁解除后为 null。封锁期间，号码无法接打语音电话，也无法发出 SMS。

已分配号码的状态说明了 ownership 与号码自身 status 之间的关系。

通过控制台提交

1. 在 Numbers 页面打开该号码。其 Ownership 行会显示材料的状态和后续步骤。
2. 当状态为 Details needed 时，选择 Update ownership details。随后会打开 Prove ownership of this number 表单。
3. 选择持有该号码的企业，或填写一家新企业的信息，然后回答每一项并上传所要求的文件。如果某项提供空白表单，请下载、填写后再上传。
4. 选择 Submit answers。

Ownership 行会变为 Under review。如果审核人员拒绝了某个答案，该行会回到 Details needed：再次选择 Update ownership details，更正表单中显示的答案，然后选择表单末尾的 Update ownership details 提交。

如果该号码所在国家暂时没有表单，表单页面会显示 Ownership form unavailable。请联系支持团队，申请支持该国家。

通过 API 提交

要通过 API 提交，请先读取该国家的要求，上传每份文件，一次性提交所有答案，然后读取号码以跟进审核。

读取该国家的要求

使用 GET /v1/compliance/requirements 读取该号码的要求。将 subject_kind 设为 number，将 subject_id 设为号码的 nda_ 标识符，并将 country_code 设为号码自身的 COUNTRY_CODE：

curl "$BIRD_API_URL/v1/compliance/requirements?subject_kind=number&subject_id=$NUMBER_ID&country_code=$COUNTRY_CODE" \
  --header "Authorization: Bearer $BIRD_API_KEY"

响应会给出号码注册所用的 program，它取决于号码类型；请将其保存为 PROGRAM。响应在 fields 中按应展示的顺序列出每个需要回答的项目。对于每个字段：

• key 是提交答案时使用的名称。
• data_type 说明如何回答。document 字段接受上传的文件；其他所有类型都接受字符串，因此数字以 "1500" 形式发送，是或否以 "true" 形式发送。enum 字段接受其 options 中的一个值。
• required 表示审批是否需要等待该字段，help_text 说明合格答案的样子。
• 接受多个答案的字段会设置 max_items。
• 如果字段提供空白表单，template_url 会给出其链接，供你下载、填写后再上传。
• state 表示该项目的进展：回答前为 not_supplied，之后为 supplied、in_review、approved 或 rejected，被拒绝的项目附带审核人的 reason。已接受的回答之后可能显示为 expired，需要重新提供；not_applicable 表示该项目不适用于你。

在你提交之前，submission_id 为 null。只要还有项目等待你处理，needs_input 就为 true。

返回带有 E19001 的 422，表示我们尚无该国家的所有权表单。请联系支持团队申请。

上传每份文件

使用 POST /v1/compliance/attachments 上传 document 字段要求的每个文件，请求体为 multipart/form-data，文件字节放在 file 部分中。将响应中的 id（即附件的 tca_ 标识符）保存为 ATTACHMENT_ID：

curl --request POST "$BIRD_API_URL/v1/compliance/attachments" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --form "file=@registration-certificate.pdf"

接受不超过 10 MB 的 PNG、JPEG 和 PDF 文件，文件类型根据文件内容判断。201 响应返回新附件。再次上传同一文件会返回第一个附件并附带 200，因此重试上传不会产生重复附件。未被任何提交引用的附件会在七天后过期。

附件的 download_url 是一个签名链接，自你获取附件起 24 小时内有效。如需新链接，请使用 GET /v1/compliance/attachments 列出附件，或使用 GET /v1/compliance/attachments/{attachment_id} 直接下载文件字节。

提交全部回答

使用 POST /v1/compliance/submissions 提交回答。发送 subject_kind 和 subject_id、读取要求时返回的 program，以及号码的 country_code。在 answers 中，为每个 required 为 true 的字段发送一个条目，并为每个你有真实回答的可选字段发送一个条目；不要为可选字段编造值，直接省略即可。类型化字段使用 value，文件字段使用 attachment_id，带有 max_items 的字段使用 values 或 attachment_ids。将请求体保存为 submission.json，并用你的值替换 <NUMBER_ID>、<PROGRAM>、<COUNTRY_CODE> 和 <ATTACHMENT_ID>。示例展示了表单要求的其中三项回答：

{
  "subject_kind": "number",
  "subject_id": "<NUMBER_ID>",
  "program": "<PROGRAM>",
  "country_code": "<COUNTRY_CODE>",
  "answers": [
    { "key": "legal_entity_name", "value": "Goldcrest Communications Inc" },
    { "key": "business_registration_number", "value": "90012768" },
    { "key": "business_registration_certificate", "attachment_id": "<ATTACHMENT_ID>" }
  ]
}

附带 Idempotency-Key 发送该请求。仅在重试相同请求体时复用该键：被拒绝的结果可能会被保留并重放，因此收到 422 后，请修正请求体并使用新键发送。幂等性说明了会保留哪些内容。

curl --request POST "$BIRD_API_URL/v1/compliance/submissions" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ownership-$NUMBER_ID" \
  --data-binary @submission.json

不存在草稿：此请求会将回答提交审核，因此必须包含所有必填回答。如果遗漏必填字段，或表单拒绝某个回答，会返回带有 E01001 的 422，并在 details 中为每个字段列出一个条目，字段名见 param，且不会提交任何内容。201 响应返回包含全部回答的提交。将其中的 id（即提交的 csb_ 标识符）保存为 SUBMISSION_ID。

工作区描述的企业称为身份。可在控制台的 Identity Center 中创建，或使用 POST /v1/compliance/identities 创建，并发送其显示 name。号码提交也可以携带内联 identity，代替 identity_id。提交响应中的 identity_id 指明新身份，POST /v1/compliance/identities 会将其返回为 id；之后的号码请复用该身份，不要另建。要为某个身份提交，请添加其 identity_id，该身份已保存的回答会补全你省略的回答。GET /v1/compliance/identities 会列出各个企业身份。无论审核结果如何，你提交的单值回答都会写回该身份，因此下一次指定该身份的提交会以这些回答为起点；文件和多值回答每次都需重新提供。每个企业使用一个身份：如果你为多个终端客户提交，请为每个客户分别创建身份，否则一个客户已批准的回答会填入另一个客户的提交。

请跟进 ownership.next，不要重复提交。号码所在国家的表单每个版本只对应一份提交，因此在该提交仍处于开放状态时再次提交，会返回 409 和 E19009：请改为更正这份提交，具体做法见更正被拒绝的答案。如果表单变更后我们重新开放已关闭的提交，next 会要求向 POST /v1/compliance/submissions 提交一份新的提交。

跟进审核

每个答案都会单独审核。再次读取号码，检查 ownership.status 和 ownership.next，方法同检查号码是否需要提交材料。要查看每个答案的审核结果，可以用 GET /v1/compliance/submissions/{submission_id} 读取提交，或再次读取要求：每个字段都带有其 state，被拒绝时还带有 reason。

审核完成后，我们会通过电子邮件把结果发送给您组织的所有者，以及最近一次记录的提交或更正该提交的人（如有）。通过 API 密钥进行的首次提交，结果发送给所有者。之后通过 API 密钥进行的更正，仍会保留之前记录的人作为收件人。您的集成通过读取 ownership.status 获知结果。

更正被拒绝的答案

将替换答案发送到 POST /v1/compliance/submissions/{submission_id}/resupply。只需包含要替换的答案，其他答案保持不变。submission_id 可从号码的 ownership 或要求读取结果中获取：

curl --request POST "$BIRD_API_URL/v1/compliance/submissions/$SUBMISSION_ID/resupply" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ownership-fix-1-$NUMBER_ID" \
  --data '{"answers": [{"key": "business_registration_number", "value": "90012769"}]}'

200 响应会返回包含替换答案的提交，这些答案会重新进入审核。当不再有被拒绝、已过期或缺失的必填答案时，号码的 ownership.status 会恢复为 under_review。可替换 state 为 rejected、expired 或 not_supplied 的答案。如果我们在接受您的答案后要求更正，在该更正关闭之前，editable_for_verifier_repair 为 true 的答案也可以替换。处于其他状态的答案，例如仍在审核中，或在我们要求的更正之外已被接受的答案，会返回 422 和 E19003。替换文件需要重新上传：先上传，再发送其 attachment_id。

随订单一起提交材料

如果购买号码时已经知道答案，可以在 POST /v1/numbers/orders 的订单 compliance 块中发送，格式与提交使用的 answers 相同。要在持有号码之前了解该国家要求提供哪些内容，请在不带 subject_id 的情况下调用要求读取，并将 COUNTRY_CODE 和 NUMBER_TYPE 分别设为 GET /v1/numbers/available 中该号码的 country_code 和 number_type：

curl "$BIRD_API_URL/v1/compliance/requirements?subject_kind=number&country_code=$COUNTRY_CODE&program=$NUMBER_TYPE" \
  --header "Authorization: Bearer $BIRD_API_KEY"

带有 compliance 块的订单使用订单已有的写入级 numbers 权限范围。

订单一旦被接受，无论如何都会完成：即使 compliance 块中的提交被拒绝，号码仍归您所有，您可以按照提交所有答案中的方法通过 POST /v1/compliance/submissions 提交。答案提交后，新号码的读取结果会显示 under_review 及其 submission_id。订单本身的操作见购买和释放号码。

复用企业身份

使用 GET /v1/compliance/identities/{identity_id} 读取企业及其已保存的答案。已保存的答案可能包含审核 state、reason 和 decided_at；尚无审核结论的值可以省略其状态。使用 PATCH /v1/compliance/identities/{identity_id} 重命名企业，或使用 DELETE /v1/compliance/identities/{identity_id} 删除企业。读取需要 compliance:read；创建、重命名和删除需要 compliance:write。

要验证企业本身，请先创建身份。读取要求时传入 subject_kind=identity、作为 subject_id 的 cid_ 标识符、program=business 和 country_code=ZZ。然后针对同一身份提交。号码提交中的内联身份不能替代此身份验证流程。

审核依据你提交的企业信息、申报的联系人和验证证据。通过 API 密钥或控制台提交不会建立不同的业务关系。请保持联系方式准确，并提供表单要求的证据。

改为为 SMS 发送方提交材料

SMS 发送方的材料使用相同的要求、附件、提交和更正请求，只是以该发送方的注册作为对象。通过 API 注册 SMS 发送方介绍如何获取该注册以及如何事先查看其价格。

请求被拒绝时

错误介绍错误正文及其 remediation。

后续步骤

• 号码概览
• 购买和释放号码
• 管理您的电话号码
• 从 Telserv 迁移到 Bird