通过API购买号码并注册短信功能

API可以搜索可购买的电话号码、购买它们，并为您的企业注册10DLC短信功能——其计费、要求和结果与在应用内操作完全相同。通过POST /v1/api/numbers购买的号码会立即显示在设置 → 号码中，通过API提交的注册会显示在短信设置卡片中，因此您可以随时从应用中介入管理。

开始之前

• 您的API密钥需要numbers:manage范围——即设置 → 开发者API中的购买号码和10DLC芯片。完全访问密钥会自动包含此范围。请参阅获取您的Ody API密钥。
• 与应用内规则相同：您的工作区需要活跃套餐才能购买，如果Ody要求您验证身份，则必须先完成验证——否则API将返回409 failed_precondition。
• 计费与应用内完全相同：您的套餐包含一个号码，每个额外号码将作为每月5美元的附加号码附加费计费。请参阅添加额外号码。

搜索可用号码

GET /v1/api/numbers/available搜索您可以购买的号码。可以使用country（默认为美国）、startsWith（例如区号）、contains、locality、state和limit（默认为20，最大50）进行筛选：

curl "https://api.ody.co/v1/api/numbers/available?startsWith=512&limit=5" \
  -H "Authorization: Bearer ody_live_…"

每个候选号码都包含其号码以及您实际需要支付给Ody的月费：

{
  "available": [
    {
      "phone_number": "+15125550123",
      "cost_information": { "monthly_cost": "5.00", "upfront_cost": "0.00", "currency": "USD" }
    }
  ]
}

购买号码

POST /v1/api/numbers从搜索结果中订购号码。发送Idempotency-Key头部，以确保网络重试不会重复购买号码——24小时内的重试将重播原始响应，并带有Idempotency-Replayed: true头部：

curl https://api.ody.co/v1/api/numbers \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onboarding-main-line" \
  -d '{"phoneNumber":"+15125550123"}'

该号码将被订购，添加到您的工作区，并计入您现有的订阅中——与在应用内点击购买完全相同。它会立即显示在设置 → 号码中，您（或您的团队）可以在其中配置振铃顺序、语音信箱、电话菜单或AI助理，就像其他任何号码一样。通话立即生效；本地号码的短信功能在10DLC注册获批（见下文）之前受到限制。

注册短信功能 (10DLC)

美国运营商要求本地号码在发送短信之前进行企业注册——API镜像了应用内的短信设置流程。

使用GET /v1/api/messaging检查状态。响应中的step会逐步显示企业（品牌）审核和活动审核，一旦运营商批准，canText将变为true——届时短信功能将在所有地方（应用和API）生效。

使用POST /v1/api/messaging/registration提交您的注册。business块需要displayName、email、vertical、street、city、state和postalCode——以及您的法定companyName和EIN，除非您注册为个体经营者（entityType: "SOLE_PROPRIETOR"，并提供firstName、lastName和联系电话）。campaign块是可选的；将应用合理的默认值（混合用例，包含符合规范的STOP/HELP处理）：

curl https://api.ody.co/v1/api/messaging/registration \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: acme-plumbing-10dlc" \
  -d '{
    "business": {
      "displayName": "Acme Plumbing",
      "email": "[email protected]",
      "vertical": "PROFESSIONAL",
      "companyName": "Acme Plumbing LLC",
      "ein": "12-3456789",
      "street": "600 Congress Ave",
      "city": "Austin",
      "state": "TX",
      "postalCode": "78701"
    },
    "campaign": {
      "description": "Customer care and appointment notifications",
      "samples": ["Acme Plumbing: your appointment is confirmed for Tuesday at 9am."]
    }
  }'

通过API提交的注册计费方式与应用内提交完全相同，包括20美元的一次性注册费。使用POST /v1/api/messaging/refresh重新检查运营商审核并推进流程；批准也会自动进行。

通过AI助理 (MCP)

同样的功能也可作为MCP工具使用，因此连接的助理可以为您运行整个流程：search_numbers、buy_number、get_messaging_status和submit_10dlc_registration。请参阅通过MCP连接AI工具。

测试模式

使用ody_test_…密钥，POST /numbers将返回模拟购买（"simulated": true）——不会订购、配置或收取任何费用——并且10DLC注册将以模拟模式提交：整个流程运行，但不会提交到注册机构，也不会产生费用。请参阅使用测试模式安全构建。

相关文章

• 购买电话号码
• 注册10DLC短信功能
• 通过API拨打AI电话并管理Astra
• 使用测试模式安全构建