Buy numbers and register texting via the API

The API can search buyable phone numbers, buy them, and register your business for 10DLC texting — with the exact same billing, requirements, and results as doing it in the app. A number bought via POST /v1/api/numbers appears in Settings → Numbers immediately, and a registration filed via the API shows up in the Text messaging setup card, so you can step in and manage either from the app at any time.

Before you start

• Your API key needs the numbers:manage scope — the Buy numbers & 10DLC chip in Settings → Developer API. Full-access keys include it automatically. See Get your Ody API key.
• The same rules as the app apply: your workspace needs an active plan to buy, and if Ody has asked you to verify your identity, that must be completed first — the API returns 409 failed_precondition until it is.
• Billing is identical to in-app: your plan includes one number, and each extra bills as the $5/month additional-number add-on. See Add additional numbers.

Search available numbers

GET /v1/api/numbers/available searches numbers you can buy. Filter with country (default US), startsWith (e.g. an area code), contains, locality, state, and limit (default 20, max 50):

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

Each candidate includes its number and the monthly price you'd actually pay Ody:

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

Buy a number

POST /v1/api/numbers orders a number from the search results. Send an Idempotency-Key header so a network retry can never buy the number twice — a retry within 24 hours replays the original response with an Idempotency-Replayed: true header:

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"}'

The number is ordered, added to your workspace, and billed on your existing subscription — exactly like clicking Buy in the app. It appears in Settings → Numbers right away, where you (or your team) can configure ring order, voicemail, a phone menu, or the AI agent, just like any other number. Calls work immediately; texting from a local number is gated until 10DLC registration is approved (below).

Register for texting (10DLC)

US carriers require business registration before a local number can send texts — the API mirrors the in-app Text messaging setup flow.

Check status with GET /v1/api/messaging. The response's step walks through business (brand) review and then campaign review, and canText flips to true the moment carriers approve — texting then works everywhere, app and API alike.

Submit your registration with POST /v1/api/messaging/registration. The business block requires displayName, email, vertical, street, city, state, and postalCode — plus your legal companyName and EIN, unless you register as a sole proprietor (entityType: "SOLE_PROPRIETOR" with firstName, lastName, and a contact phone instead). The campaign block is optional; sensible defaults (a Mixed use case with compliant STOP/HELP handling) are applied:

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."]
    }
  }'

A filing via the API is billed exactly like an in-app filing, including the $20 one-time registration fee. Use POST /v1/api/messaging/refresh to re-check carrier review and advance the pipeline; approval also progresses automatically.

From an AI assistant (MCP)

The same capabilities are available as MCP tools, so a connected assistant can run this whole flow for you: search_numbers, buy_number, get_messaging_status, and submit_10dlc_registration. See Connect AI tools with MCP.

Test mode

With an ody_test_… key, POST /numbers returns a simulated purchase ("simulated": true) — nothing is ordered, provisioned, or charged — and 10DLC registrations file in mock mode: the full pipeline runs with no registry submission and no fee. See Build safely with test mode.

Related articles

• Buy a phone number
• Register for 10DLC messaging
• Place AI calls and manage Astra via the API
• Build safely with test mode