Voice LI-ELS

Lumen supports the OAuth 2.0 client credentials authorization grant flow for external access by client-side applications. 

Only existing Lumen customers can access Voice APIs. Please contact your account manager to begin the enrollment process, or see the Support section for more information. Upon enrollment, you will receive instructions on how to get started. Once your application is approved you can go to Using OAuth 2.0 for detailed steps on getting a Bearer token using basic authorization base64 encoding.

Access base credentials

Authentication credentials

Code Examples are provided in the OpenAPI Specifications documentation.

Authorization Header

Example cURL

curl --location --request GET 'https://api-test1.centurylink.com/Voice/v1/Numbers/rateCenters?pageNumber=1&pageSize=10&productID=2036&state=CO' \ --header 'x-customer-number: 1-ABC-23' \ --header 'Authorization: Bearer 06AGcVK3QXFtx0AEGlJyp93DhRoE'

Example Python - http.client

import http.client import mimetypes conn = http.client.HTTPSConnection("api-test1.centurylink.com") payload = '' headers = { 'x-customer-number': '1-ABC-23', 'Authorization': 'Bearer 06AGcVK3QXFtx0AEGlJyp93DhRoE' } conn.request("GET", "/Voice/v1/Numbers/rateCenters?pageNumber=1&pageSize=10&productID=2036&state=CO", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8"))

7/15/2022

New! Updated route plan and trunk groups. More options for getting status on orders.

Update trunk group and route plans using your Customer Service Name

Local Inbound and Enhanced Local Services customers can now update the customer service name (CSN) to change the route plan and trunk group that TNs should be routed through. Changes to customer service names are automated and complete within minutes of a successful API request.
 

This enhancement has been added to the order/change API and is backwards compatible (no breaking changes). Simply add the “customerServiceName” : “value” pair.

Push notifications now have two security models to choose from.

Lumen Voice API solutions already utilizes webhooks so you can get real time updates on your voice orders. We have now added basic authentication to make this feature more accessible to different corporate policies. When setting up your webhook you can choose which security model Lumen will use when sending push notifications:

• OAuth 2:  You provide Lumen a client key and client secret to your authorization server to get an access token. Lumen will then send the token in the header when sending your notification.   
• Basic access authentication: You provide Lumen with a username and password. Lumen will pass the credentials as Base64 encoded in the header. 

For more information on how to setup your webhook visit the Web hooks / Notifications section.

Webhooks not your thing? Try our new GET notifications API 

Connect to GET /notifications API to fetch notifications associated to your voice order ID. You can find the most recent notification or search for up to 180 days of historical notifications.

Fetch telephone number status

Find out the status of your change, install, or disconnect orders using the GET /orderStatus API. Status includes created, in-progress, pending credit check, credit rejected, rejected, cancelled, and completed.
 

7/20/2021

We’re making some changes to the Lumen® API Marketplace to improve your experience managing test and production credentials for your apps. These changes will not impact your production API apps.

On July 8, 2021, at 7:00 pm MT, we will launch a new sandbox (test) environment and release an API Marketplace feature that allows you to select whether you want to create an app to access the new sandbox environment or to access our production environment. 
On September 8, 2021, we will decommission our old sandbox environment.

Action required: Before September 8, 2021, update your existing apps to point to the new sandbox environment by doing the following:

• Create a new app using the sandbox environment:
• Sign in to API Marketplace.
• Click MyApps.
• Click + Add New App.
• Select the sandbox environment, select an API product(s), and wait for approval.
• Update the client key/secret in your test client calls.
• Change the hostname URL on API client calls to the new sandbox environment. For example:

change api-dev1.lumen.com to api-test.lumen.com
change api-test1.lumen.com to api-test.lumen.com

• Update your test application client to make the test OAuth token call to the Lumen production OAuth token server and not the test OAuth token server. For example, change the Lumen authorization server call from https://api-test1.lumen.com/oauth/token to https://api.lumen.com/oauth/token.

6/30/21

Complete your end-to-end workflow management with these new APIs. 

Cancel in-flight LNP orders: Cancelling a voice order will cause all telephone numbers on the order to be cancelled. Cancelling a parent transaction order ID will cancel only the telephone numbers associated to that order.

Disconnect orders: Disconnect active service telephone numbers (a ported telephone number or new telephone). Customer request date must be set at least one business day in the future.

Change orders:  request to change the subscriber name, DL (Directory Listing), service address, CNAM information and E911 options for a single or group of TNs. Telephone number inventory reports: Returns a list of active telephone numbers by customer number. Report includes subscriber, address, E911 address, and customer service name details.

4/30/21

From ordering new telephone numbers to disconnects, we have the API for you. 

We have added a suite of Local Inbound and Enhanced Local Service APIs designed to help you automate and integrate workflows and manage large groups of telephone numbers easily.
Lumen serviceability and portability check

• Submit orders for new telephone numbers (TNs) from reserved inventory
• Submit porting (LNP) orders
• Supplement in-flight LNP order information
• Submit disconnect orders

Improved feature functionality.

In addition to new REST APIs to aid in your workflow automation, we’ve added new features and functionality.

• Improved TN status flow: When you place your install order to subscribe your TNs to end users, the TN will be placed into active status, allowing you to manage your different telephone number inventories more easily and help prevent double assignment. 
• Subscriber Information on Local Inbound (LI): Add subscriber information to your new LI telephone numbers to better manage your customer inventory. 
• Customer Name (CNAM) on Local Inbound: Add customer name information when you place an install order. 
• Supplement Address Information: You can now update in-flight LNP orders with subscriber addresses. This means fewer LNP cancellations and less rework.

  ---

   

12/22/20

We've made exciting changes to make it easier for you to do business. 

You can now request sequential numbers and PBX restrictions for your Local Inbound and Enhanced Local Service telephone numbers.  

To order sequential telephone numbers use POST /Voice/v1/Numbers/orderInventory endpoint with the “sequentialIndicator” attribute . For example, if you want  sequentially numbers you would use:
          “sequentialIndictor”: “Y”
 
For cases where a specific value can conflict with PBX dialing, you can request telephone numbers that exclude a specific number from a specific place in the telephone number. For example, to exclude the number 9 from the fourth position from the left NPA-NXX-1234 use the attributes: 
          “pbxIndex”:“4”, 
          “pbxValue”:“9” 

If we cannot fulfill your requests, we will push a notification to you while continuing to process the order. If you need additional help or have a different request, the LEU team is here to help. Contact them at LEUorders@lumen.com. 

 
Searching your reserved inventory just got easier. 

We have added new query parameters to the GET /Voice/v1/Numbers/inventory endpoint so you can better customize the response. We have added the following query parameters:
          “voiceOrderID”
          “externalOrderID”
          “NPA”
          “NXX”
These parameters are optional; however, if you want to search by NXX, you also have to include the NPA. 

Global customers will benefit from our new telephone number format.

We updated our telephone number format to the E.164 format to accommodate both domestic and international numbers with similar payloads and endpoints.  While we will continue to accept telephone numbers in the NPA / NXX / line format, you can now use the following format to reference a range of TNs:
 
            "startTN": 18008719244,
            "endTN": 18008719254

Resources

• You can find minor bug fixes in the next section under “Change Log”
• Use left navigation menu to view updated Documentation / Specification 
• For additional questions, please use the Contact Us form under the Help menu

Lumen will push notifications to your URL service so that you can receive up-to-the-minute updates on status and notifications. 

Lumen voice APIs adopts a bi-directional communication so that the API itself can initiate a request to the API consumer(s). This will allow API consumers to be notified when certain events occur at the server side (for example, a change in an order status), and prevents the constant polling of an API.

• Provide the webhook URL and Authorization information on the enrollment form, email to voice-api-prod@lumen.com or through the Marketplace Help form.
• You will receive a push notification to your URL once setup is complete.

Security Requirements

You man use an OAuth 2.0 or basic authorization (username and password) mode.  Please provide Lumen with the credential and URL specifics to access your service. A minimum token refresh rate of 24 hours is required. 

Web Service Setup 

To receive notifications from API, you need to implement the following an API specification and host it on your servers:
 
URL: http://{customer-host-name}/voice/notifications
Method: PUT
Payload:
 
<?xml version="1.0"?>
<PartnerNotification>
   <orderNumber>API Voice Order Number</ orderNumber >
   <customerNumber>Customer Number </customerNumber> 
   <customerName>Customer Name</customerName> 
 
   <voiceOrderStatus> 
    <notificationCode>123</notificationCode>
     <notificationMessage>…</notificationMessage>
   </voiceOrderStatus>
 
   <!—Only for PON Level Notification à  
   <rateCenterOrderStatus>
    <rateCenter>Rate Center </rateCenter>
    <state>CO</state>
    <notificationCode>123</notificationCode>
     <notificationMessage>…</notificationMessage>
   </ rateCenterOrderStatus >
 
</ PartnerNotification >