Comprar números y registrar mensajería a través de la API

La API puede buscar números de teléfono disponibles para comprar, comprarlos y registrar su negocio para mensajería 10DLC — con la misma facturación, requisitos y resultados que al hacerlo en la aplicación. Un número comprado a través de POST /v1/api/numbers aparece en Configuración → Números inmediatamente, y un registro presentado a través de la API aparece en la tarjeta Configuración de mensajería de texto, para que pueda intervenir y administrar cualquiera de ellos desde la aplicación en cualquier momento.

Antes de empezar

• Su clave API necesita el alcance numbers:manage — el chip Comprar números y 10DLC en Configuración → API de desarrollador. Las claves de acceso completo lo incluyen automáticamente. Consulte Obtener su clave API de Ody.
• Se aplican las mismas reglas que en la aplicación: su espacio de trabajo necesita un plan activo para comprar, y si Ody le ha pedido que verifique su identidad, eso debe completarse primero — la API devuelve 409 failed_precondition hasta que se complete.
• La facturación es idéntica a la de la aplicación: su plan incluye un número, y cada número adicional se factura como el complemento de número adicional de $5/mes. Consulte Agregar números adicionales.

Buscar números disponibles

GET /v1/api/numbers/available busca números que puede comprar. Filtre con country (predeterminado EE. UU.), startsWith (por ejemplo, un código de área), contains, locality, state y limit (predeterminado 20, máximo 50):

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

Cada candidato incluye su número y el precio mensual que realmente pagaría a Ody:

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

Comprar un número

POST /v1/api/numbers solicita un número de los resultados de la búsqueda. Envíe un encabezado Idempotency-Key para que un reintento de red nunca pueda comprar el número dos veces — un reintento dentro de las 24 horas reproduce la respuesta original con un encabezado 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"}'

El número se solicita, se agrega a su espacio de trabajo y se factura en su suscripción existente — exactamente como hacer clic en Comprar en la aplicación. Aparece en Configuración → Números de inmediato, donde usted (o su equipo) puede configurar el orden de llamada, el buzón de voz, un menú telefónico o el agente de IA, como cualquier otro número. Las llamadas funcionan de inmediato; la mensajería de texto desde un número local está restringida hasta que se apruebe el registro 10DLC (a continuación).

Registrarse para mensajería de texto (10DLC)

Los operadores de EE. UU. requieren el registro comercial antes de que un número local pueda enviar mensajes de texto — la API refleja el flujo de Configuración de mensajería de texto en la aplicación.

Verificar estado con GET /v1/api/messaging. El step de la respuesta guía a través de la revisión del negocio (marca) y luego la revisión de la campaña, y canText cambia a true en el momento en que los operadores aprueban — la mensajería de texto funciona entonces en todas partes, tanto en la aplicación como en la API.

Enviar su registro con POST /v1/api/messaging/registration. El bloque business requiere displayName, email, vertical, street, city, state y postalCode — además de su companyName legal y EIN, a menos que se registre como propietario único (entityType: "SOLE_PROPRIETOR" con firstName, lastName y un teléfono de contacto en su lugar). El bloque campaign es opcional; se aplican valores predeterminados sensatos (un caso de uso mixto con manejo compatible de STOP/HELP):

curl https://api.ody.co/v1/api/messaging/registration \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -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."]
    }
  }'

Una presentación a través de la API se factura exactamente como una presentación en la aplicación, incluida la tarifa de registro única de $20. Use POST /v1/api/messaging/refresh para volver a verificar la revisión del operador y avanzar en el proceso; la aprobación también progresa automáticamente.

Desde un asistente de IA (MCP)

Las mismas capacidades están disponibles como herramientas MCP, por lo que un asistente conectado puede ejecutar todo este flujo por usted: search_numbers, buy_number, get_messaging_status y submit_10dlc_registration. Consulte Conectar herramientas de IA con MCP.

Modo de prueba

Con una clave ody_test_…, POST /numbers devuelve una compra simulada ("simulated": true) — no se ordena, aprovisiona ni cobra nada — y los registros 10DLC se presentan en modo de simulación: el proceso completo se ejecuta sin envío al registro y sin tarifa. Consulte Construir de forma segura con el modo de prueba.

Artículos relacionados

• Comprar un número de teléfono
• Registrarse para mensajería 10DLC
• Realizar llamadas de IA y administrar Astra a través de la API
• Construir de forma segura con el modo de prueba