Drawer content here
< Back to API Products
API Overview
API Overview

This describes the Partner API specifications for partners wishing to configure CenturyLink available products, services and purchase on behalf of their customers.  The new Px system enables partners to seamlessly and securely transact with CenturyLink electronically on cloud based next generation CRM platforms.   The products supported as part of the current version of Partner APIs include Local Service packages, Long Distance packages, Broadband internet access and product bundles containing two or more products.  The APIs also offer the ability to configure modems, services (e.g. broadband installation services), and accessories (for example CenturyLink @Ease).

SubmitOrder API includes:

·         Retrieve RCC service

·         Send RCC service

.         Get RCC Acceptance service

.         Complete Order service

Intended User (Target Audience)

Mass Market Partner APIs are available to new and existing partners who are selling local service packages, long-distance packages, broadband internet access, and product bundles to CenturyLink consumers and small business customers.

Business Benefit

Mass Markets Partner APIs enable partners to seamlessly and securely qualify products and place orders with CenturyLink electronically on cloud-based next-generation CRM platforms. Digital information sharing between CenturyLink and our partners increases the speed and accuracy of products and services being delivered to the end customer.

Getting started
Quick Start Guide

1. Register a user.

2. Create sandbox and production apps under My Apps.

2. Obtain API keys. Upon approval, sandbox and production credentials will move to approved status. If you have questions about approvals use the Contact Us form.  

3. Setup authorization. Using the navigation menu go to Code Samples for sample code for setting up authorization.

4. Make your first call. Using the navigation menu go to Documentation/Specification.

  a. Click on the authorize button and add your credentials.

  b. Select the POST/pxRetrieveRCC API.

  c. Click on the “Try it out” button.

  d. Fill in the parameters and customize the sample code.

  e. Click the execute button to see the response. 

     

    Overview

    The below diagram depicts high level process flow for all partner APIs

     

    Partner will send the following details in the Get RCC API request. 

    1. Partner authorization details

    Px will then the return the appropriate RCC text to be formatted for the partner agent to read out to the customer.

    Send RCC

    Partners will call this service if customer requests RCC’s to be sent electronically. This will trigger RCC’s to be sent via SMS or Email (rather than delivering verbally). This will trigger RCC to be sent to the customer in method selected.

    Get RCC Acceptance

    Partners would call this service if they triggered RCC’s to be sent via SMS or Email (rather than delivering verbally). This will retrieve method of acceptance by the customer. Only after acceptance has been confirmed by the customer should this call be made (so that the acceptance confirmation and method will be retrieved). Px will store confirmation of RCC acceptance via method delivered (i.e. verbal, email, or sms).

    Complete Order

    Partner will send the following details in the Complete API request

    1. Partner authorization details
    2. RCC Accepted

    Px will then send the order details in the response.

    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.
     

    Authentication / Authorization
    AUTHENTICATION/AUTHORIZATION

    Lumen supports the OAuth 2.0 client credentials authorization grant flow for external access by client-side applications. Once your credentials are approved you can go to Using OAuth 2.0 for detailed steps on getting a bearer token using basic authorization base64 encoding.  Use the navigation menu and select Code Samples for an example of authorization.

    Documentation / Specification
    Code Samples
    Code Samples

    PxAuthenticationService.java
    ----------------------------

    package com.ctl.px.api.client;

    import org.springframework.beans.factory.annotation.Value;
    import org.springframework.stereotype.Service;

    import org.apache.oltu.oauth2.client.OAuthClient;
    import org.apache.oltu.oauth2.client.URLConnectionClient;
    import org.apache.oltu.oauth2.client.request.OAuthClientRequest;
    import org.apache.oltu.oauth2.client.response.OAuthJSONAccessTokenResponse;
    import org.apache.oltu.oauth2.common.OAuth;
    import org.apache.oltu.oauth2.common.message.types.GrantType;
    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;

    @Service
    public class PxAuthenticationService {

        Logger log = LoggerFactory.getLogger(PxAuthenticationService.class);
        
        @Value("${px.sf.token.url}")
        private String tokenURL;
        
        @Value("${px.sf.token.basicAuth}")
        private String basicAuth;

        public String getAccessToken() {
            String accessToken = null;
            String methodName = new Object() {
            }.getClass().getEnclosingMethod().getName();

            try {
                OAuthClient client = new OAuthClient(new URLConnectionClient());

                OAuthClientRequest request = OAuthClientRequest.tokenLocation(tokenURL)
                        .setGrantType(GrantType.CLIENT_CREDENTIALS).buildBodyMessage();

                request.addHeader(OAuth.HeaderType.AUTHORIZATION, "Basic " + basicAuth);
                accessToken = client.accessToken(request, OAuthJSONAccessTokenResponse.class).getAccessToken();

            } catch (Exception exn) {
                exn.printStackTrace();
            }
            return accessToken;
        }

    }


    PxRetrieveRccClient.java
    ------------------------

    package com.ctl.px.api.client;

    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.beans.factory.annotation.Value;
    import org.springframework.boot.web.client.RestTemplateBuilder;
    import org.springframework.http.HttpEntity;
    import org.springframework.http.HttpHeaders;
    import org.springframework.http.MediaType;
    import org.springframework.http.ResponseEntity;
    import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
    import org.springframework.stereotype.Component;
    import org.springframework.web.client.RestTemplate;

    import com.ctl.px.api.model.RetrieveRccRequestObj;

    @Component
    public class PxRetrieveRccClient {

        @Autowired
        private PxAuthenticationService authenticationService;

        @Autowired
        private RestTemplateBuilder restTemplateBuilder;

        @Value("${px.retrieveRCC.url}")
        private String retrieveRCCurl;

        Logger log = LoggerFactory.getLogger(PxRetrieveRccClient.class);

        public ResponseEntity<String> retrieveRcc(RetrieveRccRequestObj retrieveRccRequest) {
            RestTemplate restTemplate;
            restTemplate = restTemplateBuilder.build();
            String accessToken = authenticationService.getAccessToken();
            log.debug("Using access token: " + accessToken);
            HttpHeaders headers = new HttpHeaders();
            headers.add("Authorization", "Bearer " + accessToken);
            headers.setContentType(MediaType.APPLICATION_JSON);
            restTemplate.getMessageConverters().add(new MappingJackson2HttpMessageConverter());
            ResponseEntity<String> response = null;
            try {
                HttpEntity<RetrieveRccRequestObj> request = new HttpEntity<>(retrieveRccRequest, headers);
                response = restTemplate.postForEntity(retrieveRCCurl, request, String.class);
            } catch (Exception e) {
                log.debug("Exception occurred while making rest call to " + retrieveRCCurl + ", Exception was: "
                        + e.getStackTrace());
            }

            return response;

        }

    }

    PxSendRccClient.java
    --------------------

    package com.ctl.px.api.client;

    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.beans.factory.annotation.Value;
    import org.springframework.boot.web.client.RestTemplateBuilder;
    import org.springframework.http.HttpEntity;
    import org.springframework.http.HttpHeaders;
    import org.springframework.http.MediaType;
    import org.springframework.http.ResponseEntity;
    import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
    import org.springframework.stereotype.Component;
    import org.springframework.web.client.RestTemplate;
    import com.ctl.px.api.model.SendRccApiRequest;

    @Component
    public class PxSendRccClient {

        @Autowired
        private PxAuthenticationService authenticationService;

        @Value("${px.sendRcc.url}")
        private String sendRccUrl;

        @Autowired
        private RestTemplateBuilder restTemplateBuilder;

        Logger log = LoggerFactory.getLogger(PxSendRccClient.class);

        public ResponseEntity<String> sendRcc(SendRccApiRequest sendRccApiRequest) {
            RestTemplate restTemplate;
            restTemplate = restTemplateBuilder.build();
            String accessToken = authenticationService.getAccessToken();
            log.debug("Using access token: " + accessToken);
            HttpHeaders headers = new HttpHeaders();
            headers.add("Authorization", "Bearer " + accessToken);
            headers.setContentType(MediaType.APPLICATION_JSON);
            restTemplate.getMessageConverters().add(new MappingJackson2HttpMessageConverter());
            ResponseEntity<String> response = null;
            try {
                HttpEntity<SendRccApiRequest> request = new HttpEntity<>(sendRccApiRequest, headers);
                response = restTemplate.postForEntity(sendRccUrl, request, String.class);
            } catch (Exception e) {
                log.debug("Exception occurred while making rest call to " + sendRccUrl + ", Exception was: "
                        + e.getStackTrace());
            }

            return response;

        }

    }


    PxGetRccAcceptanceClient.java
    -----------------------------


    package com.ctl.px.api.client;

    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.beans.factory.annotation.Value;
    import org.springframework.boot.web.client.RestTemplateBuilder;
    import org.springframework.http.HttpEntity;
    import org.springframework.http.HttpHeaders;
    import org.springframework.http.MediaType;
    import org.springframework.http.ResponseEntity;
    import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
    import org.springframework.stereotype.Component;
    import org.springframework.web.client.RestTemplate;
    import com.ctl.px.api.model.GetRCCAcceptanceApiRequest;

    @Component
    public class PxGetRccAcceptanceClient {

        @Autowired
        private PxAuthenticationService authenticationService;

        @Value("${px.getRccAcceptance.url}")
        private String getRccAcceptanceUrl;

        @Autowired
        private RestTemplateBuilder restTemplateBuilder;

        Logger log = LoggerFactory.getLogger(PxGetRccAcceptanceClient.class);

        public ResponseEntity<String> getRccAcceptance(GetRCCAcceptanceApiRequest getRCCAcceptanceRequest) {
            RestTemplate restTemplate;
            restTemplate = restTemplateBuilder.build();
            String accessToken = authenticationService.getAccessToken();
            log.debug("Using access token: " + accessToken);
            HttpHeaders headers = new HttpHeaders();
            headers.add("Authorization", "Bearer " + accessToken);
            headers.setContentType(MediaType.APPLICATION_JSON);
            restTemplate.getMessageConverters().add(new MappingJackson2HttpMessageConverter());
            ResponseEntity<String> response = null;
            try {
                HttpEntity<GetRCCAcceptanceApiRequest> request = new HttpEntity<>(getRCCAcceptanceRequest, headers);
                response = restTemplate.postForEntity(getRccAcceptanceUrl, request, String.class);
            } catch (Exception e) {
                log.debug("Exception occurred while making rest call to " + getRccAcceptanceUrl + ", Exception was: "
                        + e.getStackTrace());
            }

            return response;

        }

    }


    PxCompleteOrderClient.java 
    --------------------------

    package com.ctl.px.api.client;

    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.beans.factory.annotation.Value;
    import org.springframework.boot.web.client.RestTemplateBuilder;
    import org.springframework.http.HttpEntity;
    import org.springframework.http.HttpHeaders;
    import org.springframework.http.MediaType;
    import org.springframework.http.ResponseEntity;
    import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
    import org.springframework.stereotype.Component;
    import org.springframework.web.client.RestTemplate;

    import com.ctl.px.api.model.CompleteRequestObj;

    @Component
    public class PxCompleteOrderClient {

        @Autowired
        private PxAuthenticationService authenticationService;

        @Autowired
        private RestTemplateBuilder restTemplateBuilder;

        @Value("${px.completeOrder.url}")
        private String completeOrderUrl;

        Logger log = LoggerFactory.getLogger(PxCompleteOrderClient.class);

        public ResponseEntity<String> completeOrder(CompleteRequestObj completeOrderRequest) {
            RestTemplate restTemplate;
            restTemplate = restTemplateBuilder.build();
            String accessToken = authenticationService.getAccessToken();
            log.debug("Using access token: " + accessToken);
            HttpHeaders headers = new HttpHeaders();
            headers.add("Authorization", "Bearer " + accessToken);
            headers.setContentType(MediaType.APPLICATION_JSON);
            restTemplate.getMessageConverters().add(new MappingJackson2HttpMessageConverter());
            ResponseEntity<String> response = null;
            try {
                HttpEntity<CompleteRequestObj> request = new HttpEntity<>(completeOrderRequest, headers);
                response = restTemplate.postForEntity(completeOrderUrl, request, String.class);
            } catch (Exception e) {
                log.debug("Exception occurred while making rest call to " + completeOrderUrl + ", Exception was: "
                        + e.getStackTrace());
            }

            return response;

        }

    }

    Status and Codes
    Status and Error Codes
    API Name Reason API Status Code Internal Message Code User Message
    Get RCC Sales code 401 2000 Missing or Invalid <B>; TxID <>
    Get RCC Partner ID 401 2030 Missing or Invalid <B>; TxID <>
    Get RCC addressDetailId 401 2025 Missing or Invalid <B>; TxID <>
    Get RCC Transaction Id 410 2070 Missing or Invalid <B>; TxID <>
    Get RCC Partner Order ID is not provided    2225 Missing Partner Order Id <>; TxID <>
    Get RCC Partner Order ID and transaction combination must be unique to a config request and must remain constant thru order submit.

    Cannot  submit a new Partner Order ID with an already used transaction ID on a new config request.

    Cannot alter partner order ID and transaction ID through the order flow through submit request.    		 410 2131 Transaction Id <B> and PartnerOrderId <> combination must remain constant through Submit; TxID <>
    Get RCC taxEstimate service not available 500 4040 Centurylink taxEstimateService unavailable; TxID <>
    Get RCC No RCC is returned should raise error and block Complete API (RCC is required to proceed). 500 4050 Downstream applications failed, cannot process order at this time. Please contact Centurylink 1-800-xxx xxxx (from sales code) to process  your order? TxID <>
    Complete RCC requested and accepted? 401 1210 RCC must be accepted to submit an order, please correct and resubmit; TxID <>
    Complete Sales code 401 2000 Missing or Invalid <B>; TxID <>
    Complete Partner ID 401 2030 Missing or Invalid <B>; TxID <>
    Complete addressDetailId 401 2025 Missing or Invalid <B>; TxID <>
    Complete Payment declined - Card was declined by paymet system 410 1099 Invalid credit card information. Authorization Failed Please correct and resend TxID <>
    Complete Payment service down 401   Payment system is down please contact CenturyLink at <B>; TxID <>
    Complete If payment required but PaymentToken not provided 410 1130 Because payment is required, token must be provided. Please correct and resend. TxID <>
    Complete Partner Order ID is not provided (but is required)?   2225 Missing Partner Order Id <>; TxID <>
    Complete Already received and processed submitted order (cannot change a submitted order or submit again) 410 2130 Order shows already submitted and may not be submitted again; TxID <>
    Complete Can only select one gift card (cannot select more then 1 giftcard) 410 1215 Only one gift card can be submitted, please correct and resubmit; TxID <>
    Complete A complete connot be submitted >120 minutes after succesful prepare


         		 410 2215 A complete order cannot be executed more than 120 minutes after the corresponding prepare Order TxID <>
    Complete Partner Order ID and transaction combination must be unique to a config request and must remain constant thru order submit.

    Cannot  submit a new Partner Order ID with an already used transaction ID on a new config request.

    Cannot alter partner order ID and transaction ID through the order flow through submit request.    		 410 2131 Transaction Id <B> and PartnerOrderId <> combination must remain constant through Submit; TxID <>
    Support / Tools
    Support

    Partners who would like to have API access please contact PXAPIAccessandSupport@lumen.com. 

    For API-specific support please complete the support form select the Help -> Contact Us menu option.