Numbers

#List numbers

Returns every number in the workspace.

Scope: numbers:read

Returns { numbers: Number[] }.

curl https://api.ody.co/v1/api/numbers \
  -H "Authorization: Bearer $ODY_API_KEY"

const numbers = await ody.numbers.list();

numbers = client.numbers.list()

{
  "numbers": [
    {
      "e164": "+15125550100",
      "type": "local",
      "voiceMode": "agent",
      "agentId": "0d9c…",
      "forwardTo": null,
      "assignedUserId": null,
      "status": "active"
    }
  ]
}

#Search available numbers

Searches live carrier inventory. Each result is quoted at Ody's retail monthly price: $5 for local (the first local number is included in the plan), $10 for toll-free.

Scope: numbers:manage

Query parameters

Returns { available: [{ phone_number, phone_number_type, region_information, cost_information }] }. These fields are snake_case because they come straight from the carrier.

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

const available = await ody.numbers.searchAvailable({ startsWith: "512", limit: 5 });

available = client.numbers.search_available(starts_with="512", limit=5)

{
  "available": [
    {
      "phone_number": "+15125550188",
      "phone_number_type": "local",
      "region_information": [{ "region_type": "rate_center", "region_name": "AUSTIN" }],
      "cost_information": { "monthly_cost": "5.00", "upfront_cost": "0.00", "currency": "USD" }
    }
  ]
}

#Buy a number

Orders the number and bills the workspace exactly like a purchase in the app. The number is live as soon as the call returns. Inbound calls ring the team (voiceMode: "app") until you route it to the agent.

The same hard gates as the app apply. The workspace must have chosen a plan and completed identity and mobile verification where required. Workspaces billed through the Apple App Store can't add paid add-ons (a second number or a toll-free line). An agent can never buy past these gates.

With a test key nothing is ordered or charged; the response has simulated: true.

Scope: numbers:manage · supports Idempotency-Key

Body

Returns 201 with { number, simulated? }.

Errors (409): "Choose a plan before adding phone numbers", "Verify your identity before adding phone numbers", "Verify your mobile number before adding phone numbers", the App Store add-on block, or the carrier's message when the number was taken between search and order.

curl https://api.ody.co/v1/api/numbers \
  -H "Authorization: Bearer $ODY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onboard-acme-main-line" \
  -d '{"phoneNumber":"+15125550188"}'

const { number } = await ody.numbers.buy({
  phoneNumber: "+15125550188",
  idempotencyKey: "onboard-acme-main-line",
});

res = client.numbers.buy(phone_number="+15125550188", idempotency_key="onboard-acme-main-line")

#Route a number to the agent

Sends the number's inbound calls to the AI agent. The agent must already exist: create it with PATCH /agent first. Encode + as %2B in the path.

Scope: agent:manage

Returns { ok: true, voiceMode: "agent" }. Returns 404 if the number isn't in the workspace, or 409 "Create an agent first".

curl -X POST https://api.ody.co/v1/api/numbers/%2B15125550188/connect \
  -H "Authorization: Bearer $ODY_API_KEY"

await ody.numbers.connectAgent("+15125550188");

client.numbers.connect_agent("+15125550188")

#Route a number away from the agent

Takes the agent off the line and chooses who answers instead.

Scope: agent:manage

Body (optional)

Returns { ok: true, voiceMode }.

curl -X POST https://api.ody.co/v1/api/numbers/%2B15125550188/disconnect \
  -H "Authorization: Bearer $ODY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"forward","forwardTo":"+15125559999"}'

await ody.numbers.disconnectAgent("+15125550188", { mode: "forward", forwardTo: "+15125559999" });

client.numbers.disconnect_agent("+15125550188", mode="forward", forward_to="+15125559999")