How to Connect to the Lumen API and Automate IoD Bandwidth

Short answer: To connect to the Lumen API, get a client ID and secret for your NaaS account, then POST them to https://api.lumen.com/oauth/v2/token using Basic auth and grant_type=client_credentials. Send the returned token as a Bearer header, with your customer number in x-customer-number. Changing bandwidth on Lumen Intelligent Internet (formerly Internet On-Demand) then takes two calls: a price request that returns a quote, and a modify order that uses that quote.

Updated November 5, 2026. An earlier version of this guide showed example endpoints that do not match Lumen's production API. The paths, fields and limits below come from Apptifi's working integration with Lumen. Lumen can change its API, so confirm the details in Lumen's developer portal before you build.

Why Automate IoD Bandwidth Changes

On hourly billing, IoD charges for the tier your connection is ordered at. A connection left at 1 Gbps costs the same at 3am on Sunday as it does at peak, and many enterprise workloads have long off-peak windows that need far less.

Changing tiers by hand in Lumen Connect every evening and morning is not a workflow. It is a way to forget on a Friday and pay the 1 Gbps rate all weekend. Lumen says customers can provision and adjust connectivity through Lumen Connect or APIs, so a scheduler can place those changes for you.

Lumen IoD API: Environments and Endpoints

Lumen runs a sandbox and a production environment. Both use the same paths.

These are the IoD endpoints that matter for automation:

• • POST /oauth/v2/token gets an access token.
• • GET /Network/v1/location looks up locations.
• • GET /Product/v1/price lists speed and price options. Pass masterSiteId only, because passing serviceId returns a 422.
• • POST /Product/v1/priceRequest creates a quote for a specific speed.
• • POST /Customer/v3/Ordering/orderRequest creates, modifies or deletes a service.
• • GET /ProductInventory/v1/inventory lists services. Add ?serviceId= for one service.
• • POST /Customer/v3/Ordering/notifications looks up order details for a quote.
• • POST /Notification/v2/webhook registers for order milestones.

There is no single "change bandwidth" endpoint for IoD. A bandwidth change is a quote followed by a modify order.

Step 1: Get an Access Token

Create an API key in Lumen's developer portal. That gives you a client ID and a client secret, which work once Lumen approves the key. Then request a token. This is the request from Lumen's Getting Started guide, with the production URL filled in:

curl -X POST \
  https://api.lumen.com/oauth/v2/token \
  -H 'Authorization: Basic {base64_encoded_string}' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=client_credentials

{base64_encoded_string} is your clientID:clientSecret, Base64 encoded. The response is JSON, and the two fields you need are access_token and expires_in.

Send the token on every call as a Bearer header, with your customer number:

curl https://api.lumen.com/ProductInventory/v1/inventory \
  -H 'Authorization: Bearer {access_token}' \
  -H 'x-customer-number: {customer_number}'

Three things to plan for:

• • Tokens last 1,799 seconds, just under 30 minutes. A call with an expired token returns a 401.
• • There is no separate refresh call. Lumen's guide renews a token by sending the same request again, so do that before the token expires.
• • Keep the secret out of the script. Store it in a secrets manager.

Step 2: Request a Quote for the New Speed

The quote is what tells Lumen the target speed. It is valid for 15 minutes, so request it right before you place the order, not when you build the schedule.

Two details catch people out. The API still uses the name Internet On-Demand, even though Lumen now markets the service as Lumen Intelligent Internet. And serviceId must be the numeric service ID that starts with 77. For a data center connection, send partnerId instead of serviceId.

Step 3: Submit the Modify Order

The order references the quote and leaves productCharacteristic empty. If you leave out the quote, Lumen has no speed instruction. externalId is limited to 20 characters.

Step 4: Confirm the Change Finished

Order progress arrives through webhooks. A bandwidth modify sends two milestones: Design Complete, then Order Complete.

• • Register a webhook. Milestones only go to a subscription made through /Notification/v2/webhook, with webHookType set to ORDER_MILESTONE. A callbackUrl in the order body is ignored.
• • Plan for one webhook per customer name. A second registration returns a 409.
• • Do not mix up the IDs. The id in the order response is a UUID. The orderId in webhooks is a different, numeric value.
• • Have a fallback. POST /Customer/v3/Ordering/notifications returns the numeric orderId for a quote, and the inventory endpoint shows the service, but neither one replaces milestones as proof that an order finished.

Limits to Design Around

• • 24 changes per day. Lumen allows 24 change orders per connection per GMT day. The next one returns a 422 with INVALIDVALUE. The day resets at 00:00 GMT, which is not midnight for most US teams, so count against GMT.
• • 15-minute quotes. A quote expires if you do not use it, so never store one for later.
• • Sandbox data is limited. Passing in sandbox does not prove a production order will work.

Scheduling the Calls

The API makes the change, and a scheduler decides when. For one or two connections, cron is enough.

Cron stops being enough when you need calendar-driven events, exceptions such as holidays, a view of what every connection will do next week, proof that last night's change applied, or separate customers. See scheduling recurring bandwidth changes for common patterns.

Ethernet On-Demand Uses a Different Call

Ethernet On-Demand (EoD) does not use the quote and order flow. Its bandwidth is changed with a PATCH to /Network/v5/DynamicConnection/evcs/{evcId}, with bandwidth and userEmail in the body and the billing account in x-billing-account-number. If the EVC is already at the requested speed, Lumen returns a 400 saying so, which a scheduler can treat as success.

When to Build and When to Buy

For a few connections on a fixed weekly pattern, a script is reasonable. Once you have many connections, separate customers, calendar-driven events or audit needs, you are maintaining token renewal, quote timing, webhooks, the daily limit and reporting yourself.

Apptifi handles that work behind a visual calendar. It places the quote and order for each scheduled change, stops at the daily limit and alerts you, and keeps an audit log. The Core plan is $50 a month. If you are comparing options, see how to control bandwidth on Lumen.