Voice LI-ELS
APIs for Local Inbound (LI) and Enhanced Local Service (ELS) allow customers to build workflow automation for reserving, ordering and subscribing, and managing Lumen telephone numbers.
Developers: Go to Getting Started for a full overview of APIs, resources, and implementation guides. Go to Documentation / Specification for OAS specifications.
APIs for Local Inbound (LI) and Enhanced Local Service (ELS) allow customers to build workflow automation for reserving, ordering and subscribing, and managing Lumen telephone numbers.
Documentation provides technical information that Lumen business partners may use to create their own API interfaces. It does not intend to provide technical or product training.
- Reserve telephone numbers
- Check service coverage
- Order LNP telephone numbers
- Change in-flight LNP orders
- Get telephone numbers inventory details report
- Change telephone numbers attributes
- Cancel orders
- Disconnect telephone numbers
Wholesale and reseller partners who want to streamline workflow into their existing ecosystems. All Lumen business partners who intend to use Voice APIs should request access by contacting your account representative; or begin the approval process by registering a user and application. The Voice APIs and associated technology should be used by someone who is familiar with API interfaces, REST, and JSON.
Voice APIs allow partners and customers to procure and manage voice services via digital channels. Voice APIs accelerate your results by giving you the ability to acquire, analyze and act on data directly from the Voice platform.
- Increased Efficiency: Voice APIs enable self-service functionality where customers no longer must call, email, or log orders one by one through a portal. Using APIs you can consume Lumen services your way.
- Digital Delivery: Voice APIs enable the automation of interactions, increase responsiveness, and reduce time to delivery, especially for customers who deal with hundreds of transactions at a time.
- Accelerate Digital Transformation: A comprehensive customer-facing API solution enables customers to process transactions through their chosen systems and enables them to get a deeper insight into their services. APIs are the ultimate customer-centric solution allowing customers to consume the information in whatever way they deem best for their business.
- Enroll in Voice APIs. Contact your account representative to enroll.
- Register user and API Apps
- Obtain API keys. Upon enrollment, you will receive test credentials to access test environments, and production credentials will move to approved status.
- Setup authorization. Using the Navigation bar go to Code Samples for sample code for setting up authorization.
- Make your first call. Using the Navigation bar go to Documentation/Specification
- Click on the Authorize button and add your Test credentials.
- Select the GET/Voice/v1/Number/rateCenters API.
- Click on the “Try it out” button.
- Fill in the Parameters and customize the sample code.
- Click the Execute button to see the response.
- Set up your webhook. Using the Navigation bar go to Webhooks / Push Notifications for sample code for setting up a webhook.
- 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 the setup is complete.
Sandbox and Production
When setting up your Apps in My Apps you can create a Sandbox app and a Production app. You will then have two different sets of Consumer Keys and Consumer Secrets.
Base URL Sandbox: https://api-test.lumen.com/
Base URL Prod: https://api.lumen.com/
The Sandbox (test) environment is available to developers to build initial code against. It is a snapshot of production type data so that you can try out requests and responses. The Sandbox is not meant to be used as a QA environment. It is also not meant to duplicate production, therefore data that exists in Production may not be present in the Sandbox environment. Sandbox does not represent the up-time expectations of Production. We recommend that you complete shakeout testing against Production, keeping in mind that all transactions will be live.
Use the Navigation bar to find OAS 3.0 (Swagger) documentation, as well as important information for setting up authorization, webhooks, and more.
Lumen APIs use RESTful design, JSON-encoded response with standard OAuth 2 Authorization protocols.
- Local Inbound product ID = 2036
- Enhanced Local Service product ID = 2042
Base URL Test: https://api-test.centurylink.com/
Base URL Prod: https://api.centurylink.com/
API Reference Resources
- Reading API specs using OAS 3.0
- API Guides: Recommended setup guide for using APIs
Open API Specification 3.0 can be found under Documentation / Specification. Additional detail on how use the APIs for specific use cases can be found below.
Order
Capability | Description | Resource |
---|---|---|
Reserve telephone numbers | Reserve telephone numbers into your inventory pool for later assignment to subscribers |
|
Check coverage | Check for Lumen coverage and portability by address and TN |
|
Order telephone numbers | Order telephone numbers for:
|
|
Manage
Capability | Description | Resource |
---|---|---|
Change telephone numbers | Change TN attributes including – Reserve telephone numbers into your inventory pool for later assignment to subscribers
|
|
Change in-flight porting orders | Change request date, subscriber information and address for port orders in progress |
|
Port now - coming soon | Real-time port activation |
|
Cancel orders | Cancel in-flight order | |
Disconnect telephone numbers | Disconnect active telephone numbers |
|
Report
Capability | Description | Resource |
---|---|---|
Telephone number inventory details | List of active (subscribed) telephone numbers in your inventory. For a list of inactive (reserved) telephone numbers use the GET/inventory endpoint. |
|
Fetch notifications | Receive asynchronous notifications through GET call. Alternative to webhook notifications |
|
Order status | Fetch status on orders. Status are created | in progress | pending credit check | credit check rejected | rejected | cancelled | rejected |
API Guide: Reserve telephone numbers
Reserve telephone numbers APIs to add new telephone numbers (TN) to populate your inventory pool which can later be assigned to your end users.
- You can reserve up to 399 telephone numbers per rate center per order (see Ordering Large Number Blocks for more information).
- ELS customers must use rate centers of the "static 911" field unless you have elected to use another provider (CP911).
- You must use at least 75% of current inventory in a rate center before ordering more inventory.
- Local Inbound product ID = 2036
- Enhanced Local Service product ID = 2042
Endpoint | Description | |
---|---|---|
1. | GET /Numbers/coverage | Check Lumen service coverage and portability |
2. | GET /Number/rateCenters | Identify the rate center and state combination to be used when ordering telephone numbers. |
3. | POST /Numbers/rateCenters/utilization | Check that you have 75% or greater utilization at a rate center before ordering more telephone numbers. |
4. | POST /Numbers/orderInventory | Order telephone numbers for each rateCenter state combination. Telephone numbers will only appear in inventory once the reservation order has completed processing. Check webhook notifications to confirm status. |
5. | GET /Numbers/inventory | List of available telephone numbers in your inventory. |
6. | Setup webhook to receive notifications on orders and backorders. | |
7. | POST /Numbers/customerApproval | Send back instructions for backorders to approve available, approve available and backorders, cancel order. |
Once telephone numbers are available in your inventory you can use the /Numbers/orders endpoint to subscribe telephone numbers to the end user.
Navigate to Documentation / Specification for resources, endpoints, definitions, ordering rules, and example requests and responses. Learn more about using OAS 3.0 in the Reading Specs Using OAS 3.0 section.
Ordering Large Number Blocks
Lumen aims to provide the best service possible to all our customers. There are some limits to reserving telephone numbers that make sure we can best serve all our customers.
Ordering large number blocks: If you need more than 399 telephone numbers per rate center per request, please submit your TN exception to LEUOrders@Lumen.com for assistance.
Specific telephone number requests: The Public Utilities Commission requires us to release telephone numbers from code blocks until they are exhausted. As such, we may not be able to process specific area codes that overlap a geographic area (e.g. 303 and 720 are both used in Denver). Likewise, we cannot accommodate specific 10-digit telephone numbers or vanity telephone numbers.
To submit your exceptions for the above situations you will need to submit a TN Exception form. Please contact LEUOrders@Lumen.com to receive the required form.
API Guide: Order numbers from inventory
New and LNP orders for Enhanced Local Service, Local Inbound, use the same /Numbers/Order endpoint. Each type of service and number type has a unique configuration using name:value pairs. To help you quickly set up your specific order type the following API guides and corresponding specifications are provided:
- Order new Local Inbound telephone numbers
- Order new Enhanced Local Service telephone numbers
- Order LNP Local Inbound telephone numbers
- Order LNP Enhanced Local Service telephone numbers
Install new telephone numbers from inventory
Once you have reserved a telephone number into inventory you can then trigger an install order to assign a telephone number(s) to a subscriber. Once the install order completes your telephone number will automatically be moved to “active” status.
- You can subscribe up to 399 telephone numbers per subscriber per request.
- Lumen supports addresses that have both residential and businesses by maintaining customer type at the subscriber line level.
- Orders for new numbers are provisioned immediately.
Use the Order new Local Inbound telephone numbers or Order new Enhanced Local Service telephone numbers under the Documentation / Specification section found on the side navigation bar.
Endpoint | Description | |
---|---|---|
1. | POST /Numbers/order | Move a TN from your inventory to active status and add subscriber information. |
Local Inbound
- Request payload will include “name”: “value” specific to Local Inbound
- E911 options are not supported on Local Inbound products.
- Directory Listing (DL) is not supported for Local Inbound APIs at this time.
- New! CNAM is now supported for Local Inbound APIs. You must have an approved subscription for CNAM.
Enhanced Local Service
- Request payload will include “name”: “value” specific to Enhanced Local Service. This will include directory listing and CNAM information. To learn more about CNAM and Directory Listing see the Reference Resources section.
- Geo-independent rate centers (where rate center and address do not match) are only supported if E-911 is Customer Provided. Directory Listing is not supported for geo-independent rate centers.
API Guide: Port-in telephone numbers
Ordering LNP telephone numbers for Local Inbound and Enhanced Local Services use the same /Numbers/order endpoint with a similar payload as ordering new telephone numbers, but additional LNP information is also collected.
Lumen will take the LNP information and work with the donating carrier to get approval. While Lumen APIs make submitting your LNP orders quick and easy, approval from the donating carrier is required and may be extended for non-bonded carriers.
- Currently, you can port up to 49 telephone numbers to a subscriber per request.
- Use the Order LNP Local Inbound telephone numbers or Order LNP Enhanced Local Service telephone numbers API specifications under the Documentation / Specification section found on the side navigation bar.
Endpoint | Description | |
---|---|---|
1. | POST /Numbers/coverage | Check the portability of a TN. |
2. | POST /Numbers/order | Port a number from another carrier to the Lumen network. |
3. | POST /Numbers/order/{voiceOrderId}/supplement | Update information for in-flight LNP orders.
|
4. | POST /Numbers/lnp/portnow | Coming Soon - Once FOC date and concurrence from the losing carrier is received you can trigger the port to occur in real-time. |
Local Inbound
- Request payload will include “name”: “value” specific to Local Inbound
- E911 options are not supported on Local Inbound products.
- Directory Listing (DL) is not supported for Local Inbound APIs at this time.
Enhanced Local Service
- Request payload will include “name”: “value” specific to Enhanced Local Service. This will include directory listing and CNAM information.
About CNAM
Caller Name Delivery (CNAM) is used to provide name identification of the calling party and most often displays in the Caller ID.
Voice APIs allow you to submit the caller information to be stored, known as CNAM provisioning or outbound CNAM. CNAM provisioning is provided at no charge.
If you have questions about CNAM contact CNAM@Lumen.com.
If CNAM is not required, the default city and state information that matches the rate center of the telephone number will display.
About Control Center
You can choose to use the Control Center portal or APIs to complete most activities. For example, you may order new telephone numbers, change subscriber information, disconnect telephone numbers, or check coverage with either the API or portal.
To change in-flight orders, you must use the same method with which the order was started. For example, you must use the API to supplement, cancel or check the status of in-progress orders submitted through the API. Likewise, you must use the portal to supplement, cancel, or check the status of in-progress orders submitted through the portal.
Navigating OAS (Swagger) documentation
Reading API specs using OAS 3.
Using the navigation bar on the right, navigate to Documentation / Specification.
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
Credential | Description | Example |
---|---|---|
user_name | Email address that grants you access to the developer portal and application registration | distro_list@abc.com |
password | Password for accessing developer portal | password123! |
client_id | Application specific credential used to obtain bearer token | v0ehG4dB55QQB7waOV6Gy1zG4kJ1V7 |
client_secret | Application password used to obtain bearer token | v0ehG4dB55QQB7waOV6Gy1zG4kJ1V7 |
access_token | Your application's unique API token | NNb28MBFtGdsobXZcldAxtrSYp9C |
Authentication credentials
Credential | Description | Example |
---|---|---|
authorization | Your application's unique API token. Always required. |
Bearer NNb28MBFtGdsobXZcldAxtrSYp9C |
x-customer-number | Lumen defined customer ID. Also known as Master BusOrg number. For business partners, this is the BusOrg for the customer you are transacting on behalf of. Always required. | 2-B6-7890 |
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"))
400 - Bad Request
Code | Message |
1405 | Customer service name is invalid for given customer number. Please check your customer service name (route name) and try again. |
1612 | This order cannot be processed at this time. This could be due to multiple orders submitted for this telephone number, or it is in a pending status. If you need assistance, please log into the service portal and create a ticket. |
10007 | Order exceeds limit for 399 telephone numbers per rate center. Please reduce order or make your request through LEUOrders@Lumen.com. |
10011 | Telephone number quantity cannot be zero, please resubmit. |
20000 | Invalid or missing product ID. Please check your product ID and try again. |
20001 | Invalid customer type. Valid values B- Business or R-Residence |
20003 | First name and last name are required when business type is residential. |
20004 | Business name is required when customer type is business. |
20005 | Business name must be NULL when customer type is residential. |
20006 | First name and last name must be NULL when customer type is business. |
20007 | Address street number is required. |
20008 | Address street name is required. |
20009 | Address street suffix is not a valid. |
20010 | Address city is required. |
20011 | Address state is missing or invalid. Please check your 2-digit state code and try again. |
20012 | Address zip code is required. |
20013 | Zip code must be a 5-digit numeric value. |
20014 | Secondary location exceeds 20 character limit. |
20015 | Telephone number list must be populated. Please correct and try again. |
20016 | Invalid telephone number. The telephone number you have provided is invalid or cannot be found. Please check your telephone number and try again. If the problem persists, please log into the service portal and create a service ticket. |
20019 | For a business customer, the directory listing business name is required. |
20020 | For a residential customer, the directory listing first name and last name is required. |
20021 | Directory listing type is required. Please select from 1(List and Publish), 2(List Only) and resubmit. To remove use directory listing action = R (remove). |
20022 | Directory listing action must equal A (Add) for new install orders. |
20023 | Block Customer Name is required and it should be "Y" or "N". |
20024 | CNAM Customer Name is required |
20025 | Telephone number is invalid or missing. Please correct and resubmit. |
20026 | Letter of authorization (LOA) name is required for LNP orders. |
20027 | Please indicate "Y" or "N" if letter of authorization (LOA) has been received for LNP orders. LNP order can not be processed with out LOA. |
20028 | Letter of authorization (LOA) date time is required to process LNP order |
20029 | Invalid or missing subscriber line information. |
20030 | There must be one subscriber line submitted per request. |
20031 | There must be one subscriber line submitted per request. |
20032 | Invalid or missing Customer Service Name from Order Mapping List. |
20040 | E911 option is invalid or missing. Please note, customer provided E911 is only available for specific products. Please check your E911 option and try again. If you require further assistance log into the servicer portal and create a ticket. |
20041 | Customer number provided does not own the given telephone number. Please check customer number and TN and try again. |
20042 | Telephone number provided for change request can not found. Please ensure your own this telephone number and try again. |
20043 | Customer Type Indicator must be provided for a Subscriber name change. |
20044 | Customer Type Indicator must be B for a business name change. |
20045 | Customer Type Indicator must be R for a residential name change. |
20046 | For a Subscriber name change, both first name and las name must be provided |
20047 | Letter of authorization (LOA) date time should be in date format of YYYY-MM-DDTHH:MM:SSZ |
20048 | At least one of the fields <Customer Type Indication, Billing Telephone number, First Name, Last Name, Middle Initial, Business Name> has to be selected for LNP order. |
20049 | Invalid Voice Order ID. |
20050 | Customer request date should be in date format of YYYY-MM-DDTHH:MM:SSZ. |
20051 | Directory listing action must be C for change orders |
20052 | One of directory listing attributes - directoryFirsTelephone numberame, directoryLasTelephone numberame, directoryBusinessName must be specified when directoryListingAction is Change |
20054 | The Voice Order ID can not be found. Cancel order has been rejected. Please check your order number and try again. If you need more assistance log into the service portal and create a ticket. |
20055 | Voice Order ID provided can not be found for the given Customer number. Please check both IDs and try again. |
20057 | At least one of the fields <Customer Type Indicator, Subscriber Name, E911_Option, Service Address, Directory Listing or CNAM> has to be selected for change order. |
20060 | The Voice Order ID provided can not be found for the given customer number. Please check both IDs and try again. |
20061 | Telephone number provided is not active. Disconnect request has been rejected. |
20064 | Invalid or missing voice order ID. Cancel order can not be completed. |
20065 | Order has been completed and can not be cancelled. If you require further assistance log into the servicer portal and create a ticket. |
20067 | Customer requested date cannot be NULL |
20068 | Customer request date must be at least 1 day from date order is submitted. Please change the customer request date and resubmit |
20069 | Invalid format for customer requested date. Use date format of YYYY-MM-DDTHH:MM:SSZ for suppliment and disconnect order. |
20070 | Supplement order can no longer be cancelled. If you require further assistance log into the servicer portal and create a ticket. |
20082 | Invalid or missing PBX index. PBX index indicates the digit in the 10 digit Telephone number in which a specific value must be excluded. |
20083 | Invalid or missing PBX value. PBX value that mush be excluded from the number as indicated in pbxIndex. |
20084 | Invalid or missing sequential Telephone number. Indicates the number of sequential Telephone number’s for a single state/rate center. If you do not want sequential use NULL. |
20085 | Rate Center cannot be NULL. |
20088 | Rate Center or state is missing |
20089 | Rate Center does not match with the rate center from Parent Order |
20090 | Use only tnList or TN location attributes (tnLocNxx, tnLocNpa, tnLocCity, tnLocState, tnLocZip). |
20091 | Invalid NPA/NXX in telephone number Location. |
20092 | Invalid city, state, zip in telephone number location |
20093 | Invalid telephone number location. |
20102 | Customer number and service ID is required. |
20103 | Invalid page number |
20104 | Invalid page size |
20108 | Provided order has already been cancelled and can not be cancelled again. |
20109 | Order number can not be found as a LNP order. |
20112 | Invalid losing carrier account number |
20113 | Invalid losing carrier PIN |
20114 | Invalid losing carrier wireless LNP. It should be "Y" or "N". |
20115 | Invalid or missing telephone number. |
20204 | Invalid or missing working telephone number |
20207 | Invalid or missing route plan name |
20210 | Invalid format for first name. Special characters are not accepted. |
20211 | Invalid format for last name. Special characters are not accepted. |
20213 | Customer requested date should not exceed more than 30 days from todays date. Use format YYYY-MM-DDTHH:MM:SSZ. |
20214 | Customer request date can not be less than current date. Use format YYYY-MM-DDTHH:MM:SSZ. |
20215 | Customer request date should be in date format of YYYY-MM-DDTHH:MM:SSZ |
20218 | Customer Name length should not be more than 15 characters. |
20231 | Customer request date can not be less than one week ahead for install order. Use format YYYY-MM-DDTHH:MM:SSZ. |
20232 | Directory listing action C (Change) or D (Delete) is not allowed on new install orders |
20237 | Only basic Latin (Unicode block) upper and lower case characters are supported at this time. Please remove special characters or non-basic Latin characters and resubmit. |
20238 | This order has completed and cannot be cancelled. Please submit a change order to modify the telephone number information. |
403 - Forbidden
Code | Message |
403001 | User authentication failed |
403002 | Token validation failed |
403003 | Application key validation failed |
403004 | Digest validation failed |
403005 | Not authorized for method |
403006 | Token expired |
404 - Not Found
Code | Message |
404001 | Requested resource not found |
405 - Method Not Found
Code | Message |
405001 | Method not allowed for resource |
406 - Not Acceptable
Code | Message |
406001 | Not acceptable |
409 - Conflict
Code | Message |
409001 | Resource could not be updated due to conflicting update |
500 - Service Error
Code | Message |
500001 | Internal service error |
503 - Service Unavailable
Code | Message |
503001 | Service unavailable |
504 - Service Timed Out
Code | Message |
504001 | Mediation timed out |
504002 | Provider timed out |

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 >
Code | Message |
901 | Order successfully submitted. Please refer to Voice Order ID for reference number. |
902 | Order successfully installed. Please refer to Voice Order ID for reference number. |
903 | LNP (porting) order FOC (Firm Order Commitment) is scheduled. Please see FOC data provided. |
904 | Your LNP (porting) order action has been updated. |
906 | Disconnect order is complete. Please refer to Voice Order ID for reference number. |
1302 | Rate Center is not open for orders, or future rate center is not available. Please select a different rate center. |
1303 | Coverage is not available for this rate center. This order is rejected. Please use the /coverage API to find a rate center. Then place a new order. If you require further assistance log into the servicer portal and create a ticket. |
1304 | The rate center provided cannot be found, check the rate center name and resubmit. |
1403 | Customer number / Master BusOrg can not be found. Only the customer number(s) that has been associated to your credentials is valid for this transaction. Contact your account manager or log a help ticket in API marketplace. |
1429 | Customer number / Master BusOrg can not be found. You must have a valid and active customer number in order to use this API. Contact your account manager or log a help ticket in API marketplace. |
1616 | No active service found for the telephone number(s) entered. Please verify the telephone number(s) or customer number and try again. |
1648 | Account has utilized less than 75% of current telephone number inventory at the given rate center. The order cannot be processed at this time. Please use telephone numbers from your existing inventory. If you need further assistance log into the service portal and create a ticket, or contact your account manager. |
1807 | Order has been put on credit hold. Please contact CreditCheck.Finance@centurylink.com to inquire about your account status. |
1921 | Order is rejected due to expired approval time. Please resubmit your order and respond to approval notification within 4 hours. If you require further assistance log into the servicer portal and create a ticket. |
4011 | Orders are already in progress or in backorder. This could be due to multiple orders submitted. This order cannot be processed at this time. If you require further assistance log into the service portal and create a ticket. |
10001 | Requested amount exceeds the {ORDER_Telephone number_QTY} telephone numbers available. Please select one of the following actions to proceed: "Reject" - do not reserve any telephone numbers at this time. "Accept with backorder" - Reserve the available telephone numbers and place the remaining balance on backorder. "Accept available only" - Only reserve the telephone number quantity available, and do not create a backorder. |
10002 | Voice order is complete. Please refer to Voice Order ID for reference number. |
10004 | Your back order cannot be fulfilled and has been cancelled. Please contact LEUOrders@Lumen.com for more assistance. |
10005 | Your back order has been cancelled per your request. |
10006 | Reclamation. Back order with same customer reclaim is being done. Please contact LEUOrders@Lumen.com for more assistance. |
10008 | System issue. Back orders cycling due to issue with inventory. Please contact LEUOrders@Lumen.com for more assistance. |
10009 | Backorder has been cancelled. The rate center you selected is invalid or was consolidated into another rate center. Please place the order using a different rate center or log into the portal and create a service ticket. |
10010 | Backorder has been cancelled. The rate center you selected is not available for native telephone number ordering. Please select a different rate center and place the order again. |
10012 | Order exceeds available inventory and cannot be processed at this time. Back orders are not supported in this region. If you require further assistance log into the service portal and create a ticket. |
10013 | We did not receive your confirmation of back orders. Back orders have been cancelled for your voice order. If you wish to place the back order create a new reservation order and confirm back order within 4 hours of placing the order. |
10015 | Order exceeds available inventory and cannot be processed at this time. Backorders are not supported for PBX Restricted Telephone numbers. Please contact LEUOrders@Lumen.com for more assistance. |
20020 | For a residential customer, the directory listing first name and last name is required. |
20063 | Invalid Customer Service name. |
20066 | Unable to complete LNP (porting) cancel. Cancellations are allowed up to one business day before FOC (Firm Order Commitment) date. Once LNP order completes you may issue a change order. If you require further assistance log into the service portal and create a ticket. |
20107 | The order information you provided is not for an active backorder. |
20217 | <telephone Number> is not valid telephone number. Please resubmit your request |
For questions or issues with, or if you would like to enroll to use Voice APIs,please click here to contact us.
If you are a new customer and would like more information about Local Inbound or Enhanced Local Service please visit Lumen Wholesale Voice Solutions.
For production support questions specific to the Local Inbound or Enhanced Local services product log into the Control Center Service Portal.
Minor version changes are backwards compatible and will be described in the Change Log section.
Major versions are used if changes are not backwards compatible. Major versions are indicated in the API URL such as api.lumen.com/Quoting/v1/. Major versioning will be communicated to API users through the header (where technically feasible) and in the change log. In some cases, Lumen may also email users to inform of deprecation and sunsetting plans.
- Deprecation: API is no longer recommended for use although it may still be operational. Usually, a new version is available.
- Deprecation Date: The date on which the new version is available, and the old version is no longer recommended for use.
- Sunsetting: The API is being shut down as of the sunset date. The API may return error codes or maybe entirely unresponsive. Sometimes referred to as “wholly deprecate”