Phone numbers

The phone-number routes buy and manage the numbers an organization owns: search carrier inventory, purchase a number, list and inspect the organization’s numbers, suspend and reactivate one, release it, and re-apply a vonage number’s carrier voice configuration. lua channels manages numbers interactively (search, purchase, bind to an agent, unbind, list, release) and has no non-interactive form; suspend, reactivate, and configure-voice have no CLI equivalent. The carrier compliance records a US number needs before it can send SMS, 10DLC brands and campaigns and toll-free registrations, are on SMS registrations; the end-to-end setup is SMS and phone numbers. Verified against lua-cli 3.33.0.

Base URL and authentication

Every route sits under https://api.heylua.ai/developer and takes Authorization: Bearer <<YOUR_API_KEY>>. Routes under orgs/:orgId check a telephony scope on the organization in the path: telephony:read lists and inspects, telephony:write suspends, reactivates, and configures voice, telephony:manage releases, and telephony:provision purchases. telephony:provision is a sensitive scope: a wildcard grant never covers it, so a scoped key must hold it by name. The inventory search needs only an authenticated key. msisdn path parameters are E.164 digits without the leading +, for example 12025550100. A field that fails validation answers 400 with message as an array of the failed rules. Keys, scopes, and the error envelope are on the REST API overview.

Phone number object

string

Record ID.

string

The number in E.164 digits.

string

ISO 3166-1 alpha-2 country code.

string

One of mobile-lvn, landline, landline-toll-free.

string[]

Carrier features, for example voice, sms.

string

Owning organization.

string

User ID of the purchaser.

string

Purchaser email, when known.

string

One of active, suspended, released.

number

Unix time in milliseconds.

string

Carrier the number is provisioned through: livekit, vonage, or byo-sip.

string

ID of the linked 10DLC campaign, if any.

string

ID of the attached toll-free registration, if any.

Endpoints

GET /developer/phone-numbers/available

Searches carrier inventory for numbers you can buy. Any authenticated key; searches count against vendor-spend limits.

string

required

ISO 3166-1 alpha-2 code, for example US. Upper-cased by the server.

string

default:"livekit"

Inventory to query: livekit or vonage. byo-sip numbers come from a SIP trunk and answer 400.

number

default:10

Maximum results, capped at 50; the server may configure a lower cap.

string

vonage only: mobile-lvn, landline, or landline-toll-free.

string

vonage only: comma-separated features, for example voice,sms.

string

vonage only: digit pattern to match in the number.

number

vonage only: how contains matches, 0 starts with, 1 contains, 2 ends with.

Response 200 with { numbers: [{ msisdn, country, type, features, cost?, transport }], count }, where cost is present when the carrier reports a price and count is the length of numbers.

POST /developer/orgs/:orgId/phone-numbers

Purchases a number for the organization. Scope telephony:provision.

string

required

The number to buy, from the availability search.

string

default:"livekit"

livekit or vonage; byo-sip answers 400.

string

Country code. Required when transport is vonage; derived from inventory otherwise.

Response 201 with the phone number object.

GET /developer/orgs/:orgId/phone-numbers

Lists the organization’s numbers. Scope telephony:read.

string

active, suspended, or released.

string

Filter by country code.

string

livekit, vonage, or byo-sip.

number

default:50

Maximum results.

number

Results to skip.

Response 200 with { numbers: PhoneNumber[], count }, where count is the total matching the filters, not the page length.

GET /developer/orgs/:orgId/phone-numbers/:msisdn

Returns one number. Scope telephony:read. Response 200 with the phone number object. 404 Phone number not found when the organization does not own the number or has released it.

DELETE /developer/orgs/:orgId/phone-numbers/:msisdn

Releases an active number back to the carrier; this cannot be undone. Scope telephony:manage. A byo-sip number answers 400; a number that is not active answers 404 Phone number not found or already released. Response 200 with { "success": true }.

POST /developer/orgs/:orgId/phone-numbers/:msisdn/suspend

Suspends an active number: the organization keeps it, but calls are not routed. Scope telephony:write. Response 201 with the updated phone number object; 404 Phone number not found or not active otherwise.

POST /developer/orgs/:orgId/phone-numbers/:msisdn/reactivate

Reactivates a suspended number. Scope telephony:write. Response 201 with the updated phone number object; 404 Phone number not found or not suspended otherwise.

POST /developer/orgs/:orgId/phone-numbers/:msisdn/configure-voice

Re-applies the carrier voice configuration to an active vonage number, for when it failed during purchase. Scope telephony:write. 400 Phone number does not have voice capability on an SMS-only number; 404 Phone number not found or not active otherwise. A livekit number cannot be configured here and fails at the carrier. Response 201 with { "success": true }.

Errors

Status	Message	Meaning
`400`	`Country is required`	Availability search without `country`; pass it
`400`	`Unsupported transport: <value>`	A search with a transport other than `livekit` or `vonage`, or a purchase with `byo-sip`; use one of the two
`400`	`msisdn should not be empty`	Purchase body without `msisdn`; pass the number from the search
`400`	`This number is already owned`	The number is in an organization; search again and pick another
`400`	`country is required for vonage purchases`	`transport: "vonage"` without `country`; pass it
`400`	`Cannot release number with transport: byo-sip`	Release of a bring-your-own SIP number; remove it from your SIP trunk instead
`400`	`Phone number does not have voice capability`	`configure-voice` on an SMS-only number; buy a number with the `voice` feature
`400`	Validation messages	A field failed a rule named in `message`; fix the field
`403`	—	The key lacks the scope on this organization; `telephony:provision` must be granted by name
`404`	`Phone number not found`, `… or already released`, `… or not active`, `… or not suspended`	The number is unknown to the organization or in the wrong status for the action; check `status` with the list route

Example

Purchase a number found with the availability search. The CLI does this only through the interactive lua channels menu, so there is no CLI tab.

const response = await fetch('https://api.heylua.ai/developer/orgs/<<YOUR_ORG_ID>>/phone-numbers', {
  method: 'POST',
  headers: { Authorization: 'Bearer <<YOUR_API_KEY>>', 'Content-Type': 'application/json' },
  body: JSON.stringify({ msisdn: '12025550100' }),
});
if (!response.ok) throw new Error(`Purchase failed: ${response.status} ${await response.text()}`);
const number: { id: string; msisdn: string; status: 'active' | 'suspended' | 'released'; transport: string } =
  await response.json();
console.log(number.msisdn, number.status, number.transport);

curl -X POST "https://api.heylua.ai/developer/orgs/<<YOUR_ORG_ID>>/phone-numbers" \
  -H "Authorization: Bearer <<YOUR_API_KEY>>" \
  -H "Content-Type: application/json" \
  -d '{ "msisdn": "12025550100" }'

SDK

CLI

REST API

Base URL and authentication

Phone number object

Endpoints

GET /developer/phone-numbers/available

POST /developer/orgs/:orgId/phone-numbers

GET /developer/orgs/:orgId/phone-numbers

GET /developer/orgs/:orgId/phone-numbers/:msisdn

DELETE /developer/orgs/:orgId/phone-numbers/:msisdn

POST /developer/orgs/:orgId/phone-numbers/:msisdn/suspend

POST /developer/orgs/:orgId/phone-numbers/:msisdn/reactivate

POST /developer/orgs/:orgId/phone-numbers/:msisdn/configure-voice

Errors

Example

See also

​Base URL and authentication

​Phone number object

​Endpoints

​GET /developer/phone-numbers/available

​POST /developer/orgs/:orgId/phone-numbers

​GET /developer/orgs/:orgId/phone-numbers

​GET /developer/orgs/:orgId/phone-numbers/:msisdn

​DELETE /developer/orgs/:orgId/phone-numbers/:msisdn

​POST /developer/orgs/:orgId/phone-numbers/:msisdn/suspend

​POST /developer/orgs/:orgId/phone-numbers/:msisdn/reactivate

​POST /developer/orgs/:orgId/phone-numbers/:msisdn/configure-voice

​Errors

​Example

​See also

Base URL and authentication

Phone number object

Endpoints

GET /developer/phone-numbers/available

POST /developer/orgs/:orgId/phone-numbers

GET /developer/orgs/:orgId/phone-numbers

GET /developer/orgs/:orgId/phone-numbers/:msisdn

DELETE /developer/orgs/:orgId/phone-numbers/:msisdn

POST /developer/orgs/:orgId/phone-numbers/:msisdn/suspend

POST /developer/orgs/:orgId/phone-numbers/:msisdn/reactivate

POST /developer/orgs/:orgId/phone-numbers/:msisdn/configure-voice

Errors

Example

See also