canonical: https://jentic.com/apis/lumen.com/lumen-voice-li-els

# Lumen Voice LI-ELS

The Lumen Voice LI-ELS API manages the telephone number life cycle for Lumen's Local Inbound (LI) and Enhanced Local Service (ELS) voice products. It lists rate centers by state, checks service coverage and number portability at an address, reserves numbers into inventory by rate center, and creates install or Local Number Portability (LNP) porting orders that can be supplemented, changed, cancelled, or triggered in real time. Further operations disconnect active numbers, report order and porting status, list active numbers, and return order notifications. Calls use an OAuth 2.0 client-credentials token and carry the customer's BusOrg ID in the x-customer-number header; the spec's server is Lumen's mock environment.

## For AI agents

Reserve Lumen LI and ELS telephone numbers by rate center, check coverage and portability, place install or porting orders, trigger ports, disconnect numbers, and track order status. Uses OAuth2 client credentials and an x-customer-number header.

## Scope

Does not place or record calls, send SMS, or bill end customers. Use for ordering, porting, and managing Lumen LI and ELS telephone numbers only.

## Capabilities

- List rate centers by state and check their utilization for a productID before ordering numbers
- Reserve up to 399 telephone numbers per rate center per order via POST `/Voice/v1/Numbers/orderInventory`
- Check service availability and portability for an address or telephone number through POST `/Voice/v3/Numbers/coverage`
- Create install or LNP porting orders for LI and ELS products with POST `/Voice/v2/Numbers/order`, then supplement, change, or cancel them
- Activate a port in real time with POST `/Voice/v1/Numbers/lnp/portnow` once the FOC date is today or past
- Answer a backorder prompt with Accept_with_BackOrder, Accept_Available_Only, or Reject through POST `/Voice/v1/Numbers/customerApproval`
- Track orders with GET `/Voice/v1/Numbers/orderStatus` and porting with GET `/Voice/v1/Numbers/lnp/{VOID}/status`

## Use cases

### Number provisioning agent through Jentic

A provisioning agent fulfils a request for local numbers in a new market. It searches Jentic for 'reserve Lumen telephone numbers', receives the orderInventory operation with its productID, rateCenters, and customerServiceName fields, checks options with GET `/Voice/v1/Numbers/rateCenters` for the state, and submits the reservation. If the request goes to backorder, it answers through the customerApproval operation before the 4-hour window closes.

Example prompt: Call GET `/Voice/v1/Numbers/rateCenters` with state CO, then POST `/Voice/v1/Numbers/orderInventory` with productID, customerServiceName, and rateCenters containing rateCenter DENVER, state CO, tnQuantity 20

### Number porting

Move existing numbers onto Lumen. POST `/Voice/v3/Numbers/coverage` with lnpIndicator Y checks portability, POST `/Voice/v2/Numbers/order` creates the LNP order with its subscriberLineList, and once the Firm Order Commit date is today or in the past, POST `/Voice/v1/Numbers/lnp/portnow` activates the numbers in real time. GET `/Voice/v1/Numbers/lnp/{VOID}/status` reports progress with the PON.

Example prompt: Call POST `/Voice/v3/Numbers/coverage` with lnpIndicator Y for the numbers, then GET `/Voice/v1/Numbers/lnp/{VOID}/status` with the PON, and call POST `/Voice/v1/Numbers/lnp/portnow` when the FOC date has arrived

### Inventory and disconnect housekeeping

Keep the number estate tidy. GET `/Voice/v2/Reports/inventoryDetails` looks up an active number by TN, GET `/Voice/v3/Numbers/inventory` lists inventory or pending orders by rate center, and POST `/Voice/v1/Numbers/order/disconnect` releases numbers with a customerRequestedDate at least one business day ahead.

Example prompt: Call GET `/Voice/v3/Numbers/inventory` with state CO to list spare numbers, then POST `/Voice/v1/Numbers/order/disconnect` with a tnList of unused numbers and a customerRequestedDate next week

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/Voice/v1/Numbers/rateCenters` | List rate centers by state |
| POST | `/Voice/v1/Numbers/orderInventory` | Reserve telephone numbers |
| POST | `/Voice/v3/Numbers/coverage` | Retrieve service availability |
| POST | `/Voice/v2/Numbers/order` | Create an install or porting order |
| POST | `/Voice/v1/Numbers/lnp/portnow` | Trigger a port |
| GET | `/Voice/v1/Numbers/orderStatus` | Retrieve voice order status |
| POST | `/Voice/v1/Numbers/order/disconnect` | Disconnect telephone numbers |

## Key resources

- **Rate centers** — Rate centers by state with utilization per product
- **Inventory** — Reserved telephone numbers and pending orders by rate center
- **Orders** — Install, porting, supplement, change, cancel, and disconnect orders
- **Porting** — LNP status by PON and real-time port activation
- **Reports** — Active number details and order notifications

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 65 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 58 / 100
  - Developer Experience & Jentic Compatibility: 75 / 100
  - AI-Readiness & Agent Experience: 46 / 100
  - Agent Usability: 94 / 100
  - Security: 85 / 100
  - AI Discoverability: 69 / 100
- **View full report:** https://jentic.com/apis/lumen.com/lumen-voice-li-els/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Lumen Voice LI-ELS by hand means running the OAuth2 client-credentials exchange, sending the right BusOrg in the x-customer-number header, and building nested subscriberLineList payloads for install and porting orders. Through Jentic you install once, import the Lumen Voice LI-ELS API from the API Directory, store your client credentials once, and your agent calls it.
- **Permission scoping:** Most Lumen voice operations carry the order or number in the request body, so limit the agent to the operations it needs, such as reading order status and inventory. Lumen carries the target inside the request body, so rules bound which operations your agent may call, not which order. Destructive ones like disconnect or order cancel are not included unless you add them.
- **Credential handling:** Your Lumen client credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'reserve telephone numbers' or 'check number portability', and Jentic returns the matching Lumen operation with its input schema, including enums like lnpIndicator and approvalResponse, so the agent calls the right endpoint without browsing the developer portal.

## Related APIs

- **Lumen Version 2 Voice LI-ELS** — Single-operation Lumen address validation for voice service addresses
- **Telnyx API** — Number search, ordering, porting, and programmable voice
- **Twilio Numbers v2 API** — Regulatory bundles and hosted number orders for Twilio numbers
- **Plivo API** — Voice and SMS platform with phone number rental

## FAQ

### What authentication does the Lumen Voice LI-ELS API use?

Per its OpenAPI spec, the Lumen Voice LI-ELS API uses OAuth2 with the client credentials flow, with a token URL of `/oauth/token` on Lumen's test host. Requests also carry the x-customer-number header, your Lumen BusOrg ID; for ordering and disconnect calls this is the Child BusOrg tied to the billing account. Through Jentic, your client credentials are stored encrypted by your own Jentic One instance and the token is attached at execution time.

### How many numbers can I reserve per order with the Lumen Voice LI-ELS API?

The spec states that POST `/Voice/v1/Numbers/orderInventory` reserves up to 399 telephone numbers per rate center per order, and that at least 75% of the current inventory in a rate center must be installed before ordering more.

### What are the rate limits for the Lumen Voice LI-ELS API?

The OpenAPI spec does not specify rate limits. Check https://developer.lumen.com/contact-us/ for current limits on your account.

### How do I port a number to Lumen through Jentic?

Install Jentic One, add the Lumen Voice LI-ELS API from the Jentic directory, and store your OAuth2 client credentials. Your agent searches for 'port a phone number to Lumen', receives POST `/Voice/v2/Numbers/order` with its lnpIndicator and subscriberLineList schema, and later activates the port with POST `/Voice/v1/Numbers/lnp/portnow.` To run it on your own infrastructure, install Jentic One from its GitHub repo.

### What happens if a Lumen number request cannot be fulfilled?

Lumen sends a push notification saying how many numbers can be fulfilled now and how many will be backordered. You answer with POST `/Voice/v1/Numbers/customerApproval` using an approvalResponse such as Accept_with_BackOrder, Accept_Available_Only, or Reject, and the order is cancelled unless a response arrives within 4 hours.

### Is there a Lumen Voice LI-ELS MCP server?

You don't need an MCP server to give your agent the Lumen Voice LI-ELS API. Jentic connects it directly from the API Directory: import it, store your credential once, and your agent calls it, discovering the ordering and porting operations by intent.

### Can I limit what my agent is allowed to do with the Lumen Voice LI-ELS API?

Yes. For a monitoring agent, allow only GET `/Voice/v1/Numbers/orderStatus`, GET `/Voice/v1/Numbers/lnp/{VOID}/status`, and GET `/Voice/v3/Numbers/inventory`, so it can report on orders and inventory but cannot reserve, port, or disconnect numbers. The agent's calls are logged for review.