Voice Toll-Free

Provides reservation, activation, and number management of Toll-Free services.

API Overview

API Service is currently in beta with limited availability.

Developers: Go to Getting Started for a full overview of APIs, resources, and implementation guides. Go to Documentation / Specification for OAS specifications.

The Toll-free API allows you to automate your toll-free number workflow from managing terminations, creating, and managing simple routes, reserving, porting, and managing toll-free numbers. You can also use the API to retrieve toll-free service details and receive real-time order updates through a web hook service.

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.

API guides in this overview section will provide example applications for some of the most common use cases.

Reserve random and/or vanity toll free numbers directly from industry database with Lumen acting as your Responsible Organization (RespOrg)
Port toll free numbers from incumbent RespOrgs for activation on our network
Activate toll free numbers to designated routes
Manage toll free numbers
- Change attributes or route reference
- Disconnect toll free numbers from customer
Manage routing configurations
- Create terminations.
- Create and update simple routes
Disconnect terminations, routes and toll free 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.

Getting started

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 POST/Voice/v1/Numbers/reserve/tollfree.
- 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.

Base URL Test: https://api-test.lumen.com

Base URL Prod: https://api.lumen.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
Toll free numbers with unique termination	When using Lumen as your RespOrg, reserve toll-free numbers from SMS/800 TFN Registry. Newly reserved, port to Lumen, or Customer/third party RespOrg toll-free numbers can be activated immediately or scheduled for future activation to a unique route using terminations, such as a Ring to Numbers (RTN) or to dedicated terminations with a unique Dialed Number Identification Service (DNIS) that is not the toll-free number. Routes are systematically created with the toll-free number as the route name. Letter of Authorization rejects when porting toll-free numbers can be updated to resubmit rejected port installs.	reserve uniqueTerm LOA
Terminations	Required when creating or updating routes. Terminations are ring to numbers or switch/trunk group and DNIS combinations	terminations
Route	Route names are referenced by toll-free numbers and used to identify how the toll-free numbers should route to their destination. Routes can have multiple route plan IDs however only one route plan ID can be active at any given time.	route
Toll free numbers	When using Lumen as your RespOrg, reserve toll-free numbers from SMS/800 TFN Registry. Newly reserved toll-free numbers, port to Lumen, or Customer/third party RespOrg added to your inventory and activated on our network. Letter of Authorization rejects when porting toll-free numbers can be updated to resubmit rejected port installs.	reserve installOrder LOA

Manage

Capability	Description	Resource
Change existing route	Change simple routes to update terminations or routing configurations, including adding or removing overflow routing. Changes to routes can be activated immediately or scheduled for future activation	route/changeOrder
Change toll-free numbers	Change toll-free attributes or the route toll-free numbers use for call processing. Changes can be activated immediately or scheduled for future activation RespOrg Area of Service Billing Account Number Route Name BTN	changeOrder/tollfree
Disconnect toll-free numbers	Disconnect active toll-free numbers	disconnectOrder/tollfree
Disconnect unique term toll-free numbers	Disconnect active toll-free numbers along with the unique route and terminations	uniqueTerm/disconnectOrder
Disconnect routes	Deletes unused existing route, including removal from our network	route/disconnectRoute
Disconnect route plans	Deletes inactive route plan IDs	route/deletePlan
Disconnect terminations	Deletes terminations that are not being referenced in routes or route plan IDs	deleteTermination

Capability	Description	Resource
Terminations	Search for existing terminations available in your inventory	terminations
Route	Search for existing routes available in your inventory	route
Toll-free numbers	Search for existing toll-free numbers available in your inventory	tollfree

API Guide: Reserve toll free numbers

The reserve toll free numbers API can be used to search the SMS/800 TFN Registry database for vanity or random toll free numbers. Toll free numbers are reserved for 45 calendar days from the date of reservation. Unless activated on your account prior to the expiration date, the toll free numbers will be returned to the SMS/800 TFN Registry spare number pool.

You can reserve up to 10 toll free numbers per API call
Searches can be done using criteria based on NPA, NXX, a line number, or a combination of digits and/or words
Random searches can be performed using “ANY”
Unlike other toll free API calls, reserve toll free number calls are synchronous

	Endpoint	Description
1.	POST /Voice/v1/Numbers/reserve/tollfree	Check SMS/800 TFN Registry for available toll free numbers Lumen service coverage and portability

Configuring routes for toll free numbers

Toll-free services can be established with a one to one or a one to many route configuration. Toll-free numbers that are terminating to an individual termination, defined as a unique Ring to Number (RTN) or to a dedicated termination with a unique Dialed Number Identification Service (DNIS) that is not the toll-free number, uses a one to one route configuration. These numbers can be activated using our Toll free numbers with unique termination API.

When several toll-free numbers route to the same trunk group(s), use the toll-free number as the DNIS or when all of the toll-free numbers use the same DNIS, the service can be activated using a combination of our APIs to build reusable route components. The terminations that will be used in the route are activated using our Termination API. After your terminations are created, you will use them to build a simple route using our Route API. The Toll free numbers API completes your toll free number activation to our network. You can use the toll free API for most activities however routes that require routing features, beyond overflow routing, must be submitted through the 1+ Switched & Toll Free portal via Control Center.

API Guide: Order Termination

Terminations define destinations to be used in route plans for toll-free numbers. A termination can be a switched Ring to Number (RTN) or a dedicated termination. A dedicated termination is the combination of a switch identifier, trunk group and the dialed number identification service (DNIS). The DNIS can be custom digits or use “TFN” to indicate that the dialed toll-free number is the DNIS.

Terminations must be unique
RTNs must be within the 48 Contiguous United States
Switch ID/Trunk Group must match the Billing Account Number (BAN). Available trunk groups per BAN can be found using the 1+ Switched & Toll Free portal via Control Center
Customer DNIS supports between 2-10 digits

	Endpoint	Description
1.	POST /Voice/v1/RoutePlans/terminations/installOrder/tollfree	Order terminations to be used in a route

API Guide: Order Route

Route names are referenced by toll-free numbers and used to identify how the toll-free numbers should route to their final termination. Routes reference a route plan ID, which stores the configuration.

The route plan ID for a simple route name may contain a single switched or dedicated termination.
Simple route names can also be configured with overflow options.
- When the primary termination is a Ring to Number (RTN), the overflow can only be another RTN.
- When the primary termination is a dedicated trunk group, the overflow may consist of up to two additional dedicated terminations and/or up to two RTNs.
Routes that require routing features beyond overflow routing must be submitted through the 1+ Switched & Toll Free portal via Control Center

	Endpoint	Description
1.	POST /Voice/v1/RoutePlans/route/installOrder/tollfree	Order routes configured with terminations used for call processing

API Guide: Order Toll free numbers

The install request adds new toll-free numbers or port-in toll-free numbers to your inventory and activates those numbers on our network. The 8XX type “New” is used when you are activating toll-free numbers that are either reserved under our Responsible Organization (RespOrg) ID, reserved using your RespOrg ID or toll-free numbers that you have reserved using a third party RespOrg ID. When we are acting as your RespOrg, we’ll take care of building the toll-free numbers in the SMS/800 TFN Registry. If you’re not using our RespOrg ID, you or your third party RespOrg will be responsible for managing the SMS/800 TFN Registry. Be sure that the RespOrg ID on your order matches the RespOrg ID in the SMS/800 TFN Registry. Our application will perform a RespOrg verification as part of the order process. For 8XX type “Port” we will systematically submit the letter of authorization (LOA) and invoice you provide to the "losing carrier" through the Centralized Resp Org Change Management System. Having an invoice is not required but it does help us to resolve potential rejects. You may also choose to embed the invoice into the LOA file. When the “losing carrier” releases the toll-free numbers to our RespOrg ID, we will build the toll-free numbers to the route designated on the order and then schedule the carrier change in the SMS/800 TFN Registry at the due date and time listed on the order.

When using the Toll free numbers with unique termination API, the terminations and route will be provisioned as part of this call. The route name will default to the toll free number being provisioned.
The API accepts an array of toll free data.
- All submitted toll free numbers will have the same activation date/time.
- All submitted toll free numbers can consist of 8XX type New and Port, however the LOA and invoice will apply to all toll free numbers in the request.
The LOA and invoice file must be .PDF and base64 encoded, sent as a string in the letterOfAuthorization/invoice field(s).

	Endpoint	Description
1.	POST /Voice/v1/Numbers/uniqueTerm/installOrder/tollfree	Activates a toll-free number that terminates to a destination that is unique to the toll-free number, either using a unique DNIS that is not the toll-free number or terminates to a 10 digit ring to number.
2.	POST /Voice/v1/Numbers/installOrder/tollfree	Activates a toll-free number on the Lumen network.
3.	PUT /Voice/v1/Numbers/LOA/tollfree	Resubmits a LOA for a port request that has been rejected on a toll free install.

Navigating OAS (Swagger) documentation

Reading API specs using OAS 3.

Using the navigation bar on the right, navigate to Documentation / Specification.

Authentication / Authorization

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
x-billing-account-number	Lumen defined billing account number the application will be making transactions for. A customer number can have many billing account numbers (BANs). Required for specific API calls.	1-A23BC4DE

Documentation / Specification

Code Samples

Code samples are provided in the OpenAPI Specifications documentation.

Status and Codes

Termination and Route Errors

Code	Message
40000	RTN is valid
40001	already exist
40002	Invalid Ring to Number (RTN). RTN must be 10 digits in format NPANXXXXXX
40003	The NPA-NXX entered is invalid
40004	Order has been successfully created with order id:
40005	Order failed to submit. Please resubmit your request
40006	Required fields are missing or incomplete. Please populate Route Name and Route Activation Date. For a switched termination, a Ring to Number (RTN) is required. Switched overflow may also include a secondary RTN. For a dedicated termination, a primary trunk group is required. Dedicated overflow allows up to 5 terminations that may consist of 3 dedicated terminations and 2 RTNs terminations
40007	The NPA-NXX entered is invalid
40008	Invalid Term Type
40009	Term Type is Empty
40010	DNIS must be defined. Valid values: TFN or 2-10 digits
40011	Switch/trunk group and DNIS combination already exist
40012	RTN and TG combination already Exist
40013	Routes must be unique
40014	Duplicate ring to number requested
40015	Duplicate switch/trunk group and DNIS combination requested
40016	DNIS must be within 2 to 10 digits in length
40017	RTN is Empty , Enter a value
40018	Switch Identifier and trunk group are required
40019	is invalid
40020	Route Name is not unique. Updates to an existing Route Name must be handled through a change
40021	Route Name already exists for customer.
40022	Cannot perform change. No unique active orders found to perform change
40023	Cannot perform change. There is a Pending Order
40024	Provided Route configuration already exist with another Order
40025	Route Name is mandatory and must be between 1 and 25 characters where _ is the only valid special character
40026	INVALID NPA/NXX, NOT found in NPA NXX table
40027	The input provided should be of 3/6 or 10 Digits
40028	DNIS Value should be minimum of 2 and maximum of 10 digits
40029	Network activation failed. Lumen system support is investigating
40030	Inventory update failed. Lumen system support is investigating
40031	Network activation failed. Lumen system support is investigating
40032	Billing process failed. Lumen system support is investigating
40033	Inventory update failed. Lumen system support is investigating
40034	Billing process failed. Lumen system support is investigating
40035	Failure in SOMOS ROC Call
40036	Failure in BILLING Call
40037	Success in adding termination in Inventory
40046	Failure in updating route as Active in PRO
40047	Please enter only digits in the DNIS field
40048	Route configuration for {routeName1} is same as the route configuration of {routeName2}
40049	Duplicate term - {term} in route {routeName}
40051	Unable to disconnect Termination, since it is being used on following active route plan id(s):
40052	Unable to disconnect route since it is being currently active on
40053	Unable to disconnect plan since it is being currently used in TFN(s):

Toll Free Number Errors

Code	Message
50000	TFN is valid
50001	Toll free number is already being processed on another order
50002	is invalid
50003	Order has been successfully created with voice order id:
50004	Order submission failure:
50005	is currently assigned in NUMS.
50006	A toll free number is required
50007	The billing telephone number (BTN) is required
50008	The NPA-NXX you entered is invalid
50010	The Route Name referenced does not exist. Please resubmit with an active Route Name
50011	The toll free number cannot be activated on your account because the responsible organization listed on your order does not match the carrier database
50012	Toll free number is active for another customer and must be ordered as toll free type Port
50013	The toll free number is not reserved. Please reserve the toll free number prior to submitting an activation request
50014	Either Order id or Customer Id or tfn has to be mandatory field to search
50015	TFN does not have a completed and active voice order for change
50018	Due date cannot extend more than 45 days from the current date
50019	Type 8xx is Mandatory to provide
50020	Type 8xx is invalid, Please pass a valid Type 8xx
50021	RespOrg is Mandatory to provide
50022	RespOrg is invalid, Please pass a valid RespOrg
50023	CIC value is not available for selected BAN.
50024	No service Image found for this TFN -
50025	No change from previous service image
50026	TFN Order is in pending state and TFN not active
50027	Toll free number is associated to KSW01 in SOMOS and must not be ordered as toll free type Port
50028	Toll free number is in transitional status in SOMOS and must not be ordered as toll free type Port
50056	Hot cut cannot be removed as status is AH Received

Search Errors

Code	Message
70000	No record found for the requested data
70001	Page number is missing
70002	Page size is missing
70003	Order Submission Failure
70004	The customer number is not found. Please contact your Account Manager if you believe this message to be inaccurate
70005	The toll free number was not found.
70006	The route Name was not found.
70007	The route Plan ID was not found.
70008	The voice order ID was not found for the requested customer number. The route Name was not found for the requested customer number. No record found for the requested customer number.
70009	The voice order ID was not found for the requested customer number. The toll free number was not found for the requested customer number. No record found for the requested customer number.
70010	The Ring to Number was not found.
70011	The switch ID was not found.
70012	Trunk group ID was not found.
70013	The voice order ID was not found.

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

Web Hooks / Push Notifications

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

Lumen requires that you utilize an OAuth model. 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>
   <callBackUrl>https://env1-my.level3.com/portalWeb/mylevel3?goto-page=QUKcv&orderSearch=11105970
   </callBackUrl>
   <customerName>Lumen IT N & C - V</customerName>
   <customerNumber>1-BPH-400</customerNumber>
   <orderNumber>11105970</orderNumber>
   <tollfreeOrderStatus>
       <notificationCode>60005</notificationCode>
       <notificationMessage>Tollfree number successfully updated in network –
           8335601910
       </notificationMessage>
       <tollfreeNumber>8335601910</tollfreeNumber>
   </tollfreeOrderStatus>
</partnerNotification>

<partnerNotification>
   <callBackUrl>https://env1-my.level3.com/portalWeb/mylevel3?goto-page=QUKcv&orderSearch=11105970</callBackUrl>
   <customerName>Lumen IT N & C - V</customerName>
   <customerNumber>1-BPH-400</customerNumber>
   <orderNumber>11105970</orderNumber>
   <tollfreeOrderStatus>
       <notificationCode>60009</notificationCode>
       <notificationMessage>Tollfree number successfully activated in SOMOS – 8335601914</notificationMessage>
       <tollfreeNumber>8335601914</tollfreeNumber>
   </tollfreeOrderStatus>
</partnerNotification>

<?xml version="1.0"?>
<partnerNotification>
<callBackUrl>https://env1-my.level3.com/portalWeb/mylevel3?goto-page=QUKcv&orderSearch=11105959 </callBackUrl>
<customerName>Lumen IT N & C - V</customerName>
<customerNumber>1-BPH-400</customerNumber>
<orderNumber>11105959</orderNumber>
<tollfreeOrderStatus>
<notificationCode>60005</notificationCode>
<notificationMessage>Tollfree number successfully updated in network – 8336511681</notificationMessage>
<tollfreeNumber>8336511681</tollfreeNumber>
</tollfreeOrderStatus>
</partnerNotification>

<?xml version="1.0"?>
<partnerNotification>
<callBackUrl>https://env1-my.level3.com/portalWeb/mylevel3?goto-page=QUKcv&orderSearch=11105959 </callBackUrl>
<customerName>Lumen IT N & C - V</customerName>
<customerNumber>1-BPH-400</customerNumber>
<orderNumber>11105959</orderNumber>
<tollfreeOrderStatus>
<notificationCode>60010</notificationCode>
<notificationMessage>Porting of tollfree number approved – 8336511677 </notificationMessage>
<tollfreeNumber>8336511677</tollfreeNumber>
</tollfreeOrderStatus>
</partnerNotification>

<partnerNotification>
   <callBackUrl>https://env1-my.level3.com/portalWeb/mylevel3?goto-page=QUKcv&orderSearch=11105959</callBackUrl>
   <customerName>Lumen IT N & C - V</customerName>
   <customerNumber>1-TW-258</customerNumber>
   <orderNumber>11105959</orderNumber>
   <tollfreeOrderStatus>
       <notificationCode>60008</notificationCode>
       <notificationMessage>Error while activating tollfree number in SOMOS –
           8336511676,Issue in Activate in Somos with message: No customer
           record exists for this number. for Order: 10649639729</notificationMessage>
       <tollfreeNumber>8336511676</tollfreeNumber>
   </tollfreeOrderStatus>
</partnerNotification>

Code	Message
60000	Error while adding termination to network – {term}
60001	Termination added successfully to network – {term}
60002	Error while adding route to network – {route}
60003	Route added successfully to network – {route}
60004	Error while updating tollfree number in network – {tfn}
60005	Tollfree number successfully updated in network – {tfn}
60006	Error while removing tollfree number from network – {tfn}
60007	Tollfree number successfully removed from network – {tfn}
60008	Error while activating tollfree number in SOMOS – {tfn}
60009	Tollfree number successfully activated in SOMOS – {tfn}
60010	Porting of tollfree number approved – {tfn}
60011	Porting of tollfree number rejected – {tfn}

Support / Tools

For questions or issues with, or if you would like to enroll to use Voice APIs, please click here to contact us.

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”