PX PreOrder
PX PreOrder APIs provide partners ability to retrieve and configure available CenturyLink products and services for a given address.
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).
PreOrder API includes:
· Retrieve qualified services
· Retrieve configuration options
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.
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.
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/pxQualify 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.
The below diagram depicts high level process flow for all partner APIs.
This section provides detailed information for Qualify (pxQualify API) and Configure (pxConfigure API) steps.
Qualify API:
- Qualify API allows partners to verify an address and get CTL products and bundles qualified for that address. Partner sends
- Partner details like TransactionId (Px Transaction Id for reference), Salescode, PartnerId, PartnerOrderId
- Address to qualify
- The API also allows partners to select an address in case of multiple near matches retuned by the service.
- Partners can also qualify with a different address in case of No-Matches. Partners cannot requalify on a No-match response.
Config API:
Partner will call this service after selecting a product returned in the Qualify API response and send
- Partner details like TransactionId, Salescode, PartnerId, PartnerOrderId
- Selected product
- Customer details
- Config type
The API will return any one of the following based on the selections made
- Add-ons for the selected product like Tech Install options,
- Tech Installation if TECH is chosen as option
- Tech Installation if the speed qualifies for installation services
- Self-Installation if SELF is chosen as option
- In this option Shipping & Handling charges are added to the selected modem
- Add-ons for the selected product like Modem options
- Modem purchase
- Modem lease
- I have my own modem
- This option cannot be chosen if Technical Installation is required
- Deposit to be paid in case of Postpaid and based on the credit output
- Credit issue - Hard stop
- Final Bill outstanding – Hard stop
Besides following Config / Reconfig logic will be implemented to ensure customer credit is not run multiple times.
ConfigType=Config type: logic
- Transaction Id, that is returned in Qualify API response, is sent by the partner
- Customer information will be sent in the API request
- Based on the billtype of the product selected, if billtype=prepaid authentication is required, must send DOB and all “9”s in SSN field (i.e. 999 99 9999).
- Based on the authentication check, an error or zero deposit will be returned.
- If billtype=postpaid then
- SSN and DOB are required
- If customer refuses or does not have SSN, must send all “9”s in SSN field (i.e. 999 99 9999)
- Based on the credit result send an error message or a deposit amount.
ConfigType=Reconfig: logic
- Credit check will not be run in Reconfig and hence no customer information is provided
- Same transaction Id with ConfigType=Reconfig and customer information is provided in the request, then Px shall send an error message
- If customer is switching billtype then new Config is required (vs. Reconfig).
- Same transaction Id with ConfigType=Reconfig and product billtype is changed from Prepaid to Postpaid or vice versa, then Px shall send an error message
- In a Reconfig request for same billtype=postpaid, then
- Changing products may change the deposit amount.
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.
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.
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;
}
}
PxQualifyRestClient.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.Qualify;
import com.ctl.px.api.model.QualifyApiRequest;
@Component
public class PxQualifyRestClient {
@Autowired
private PxAuthenticationService authenticationService;
@Value("${px.qualify.url}")
private String qualifyUrl;
@Autowired
private RestTemplateBuilder restTemplateBuilder;
Logger log = LoggerFactory.getLogger(PxQualifyRestClient.class);
public ResponseEntity<String> qualify(QualifyApiRequest qualifyRequest) {
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<QualifyApiRequest> request = new HttpEntity<>(qualifyRequest, headers);
response = restTemplate.postForEntity(qualifyUrl, request, String.class);
} catch (Exception e) {
log.debug("Exception occurred while making rest call to " + qualifyUrl + ", Exception was: "
+ e.getStackTrace());
}
return response;
}
}
PxConfigRestClient.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.Configure;
@Component
public class PxConfigRestClient {
@Autowired
private PxAuthenticationService authenticationService;
@Value("${px.configure.url}")
private String configUrl;
@Autowired
private RestTemplateBuilder restTemplateBuilder;
Logger log = LoggerFactory.getLogger(PxConfigRestClient.class);
public ResponseEntity<String> config(Configure configRequest) {
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<Configure> request = new HttpEntity<>(configRequest, headers);
response = restTemplate.postForEntity(configUrl, request, String.class);
}catch(Exception e) {
log.debug("Exception occurred while making rest call to "+configUrl+", Exception was: "+ e.getStackTrace());
}
return response;
}
}
API Name | Reason | API Status Code | Internal Message Code | User Message |
Qual | No match for the address | 200 | 2096 | This address is within the Centurylink footprint but no address matched; TxID <> |
Qual | No match for the address | 200 | 2086 | This address is not within the Centurylink footprint; TxID <> |
Qual | Sales code | 401 | 2000 | Missing or Invalid <B>; TxID <> |
Qual | Agent ID | 401 | 2010 | Missing or Invalid <B>; TxID <> |
Qual | Market Segment | 401 | 2020 | Missing or Invalid <B>; TxID <> |
Qual | Partner ID | 401 | 2030 | Missing or Invalid <B>; TxID <> |
Qual | Qual for Video is NOT False | 401 | 2040 | Missing or Invalid <B>; TxID <> |
Qual | Street Address not complete or missing | 410 | 1000 | Missing or Invalid <B>; TxID <> |
Qual | Address does not have a city | 410 | 1010 | Missing or Invalid <B>; TxID <> |
Qual | Address does not have a state or a valid state ID | 410 | 1020 | Missing or Invalid <B>; TxID <> |
Qual | Address does not have a zip code or a valid zip code | 410 | 1030 | Missing or Invalid <B>; TxID <> |
Qual | Transaction Id | 410 | 2070 | Missing or Invalid <B>; TxID <> |
Qual | addressDetailId | 410 | 2080 | Missing or Invalid <B>; TxID <> |
Qual | 2nd Qual cannot be completed on Qual that is older then current day (within 24 hour clock) based on Central Time | 410 | 2220 | The original Qualify response has expired; please submit a new Qualification TxID <> |
Qual | If the same address has been submitted in past 30 days which has PX/Partner Status of RECEIVED, PROVIDER IN PROCESS, COMPLETED, return error message (1000 series error code). | 410 | 1005 | “CenturyLink received an order for service at this address within the last [30] days on order number <>. Please call <B> to make changes to this order; TxID <>” |
Qual | Address service not available | 500 | 4000 | Centurylink Address Service unavailable; TxID <> |
Qual | Address service timeout | 500 | 4010 | Centurylink Address Service unavailable; TxID <> |
Qual | Address service return unknown error | 500 | 5000 | Centurylink Exception/Error, please notify CenturyLink?; TxID <> |
Qual | LoopQual service not available | 500 | 4020 | Centurylink LoopQual Service; TxID <> |
Qual | LoopQual service time out | 500 | 4030 | Centurylink LoopQual Service unavailable; TxID <> |
Qual | LoopQual service return unknown error | 500 | 5010 | Centurylink Exception/Error, please notify CenturyLink?; TxID <> |
Qual | No offer returned | 500 | 6000 | No offers available; TxID <> |
Config | Sales code | 401 | 2000 | Missing or Invalid <B>; TxID <> |
Config | Partner ID | 401 | 2030 | Missing or Invalid <B>; TxID <> |
Config | Transaction Id | 410 | 2070 | Missing or Invalid <B>; TxID <> |
Config | addressDetailId | 401 | 2025 | Missing or Invalid <B>; TxID <> |
Config | RequestType=Reconfig without Configuration call | 410 | 2090 | Unable to find config transaction for transaction id <> and sales code <>; TxID <> |
Config | Promocode not availble in Qual response | 410 | 2100 | Invalid <B>; TxID <> |
Config | Promocode does not apply to selected Product Code | 410 | 2180 | PromoCode <> not applicable ot selected ProductCode <>; TxID <> |
Config | Product code not availble in Qual response | 410 | 2110 | Invalid <B>; TxID <> |
Config | Product code not submitted in Config request (required) | 410 | 2120 | Missing <B>; TxID <> |
Config | Partner Order ID is not provided (but is required) or invalid syntax? | 410 | 2225 | Missing or invalid (i.e. contains unsupported characters like !@#$%^&*()<>?{}[]+=) Partner Order Id <>; TxID <> |
Config | Partner Order ID length needs to be 50 or less? | 401 | 2105 | Field length cannot exceed 50 characters for Partner Order Id; TxID <> |
Config | Partner Order ID used with another Order | 410 | 2130 | SalesCode <> and PartnerOrderId <> combination must be unique; TxID <> |
Config | Billing Type | 410 | 2140 | Product Code <> does not match Billing Type <>; TxID <> |
Config | interestedInSelfInstallOrTechInstall (NULL for Voice) | 410 | 2160 | Missing or Invalid <B>; TxID <> |
Config | accountFirstName | 410 | 1040 | Missing or Invalid <B>; TxID <> |
Config | accountLastName | 410 | 1050 | Missing or Invalid <B>; TxID <> |
Config | ssn | 410 | 1060 | Missing or Invalid <B>; TxID <> |
Config | dob | 410 | 1070 | Missing or Invalid <B>; must be 18 years or older; TxID <> |
Config | dob | 410 | 1080 | Please call CenturyLink at 800#<> for help with processing this orde?; TxID <> |
Config | dob | 410 | 1090 | Missing or Invalid <B>; format must be in format like "MM/DD/"YYYY"; TxID <> |
Config | Config cannot be completed on Qual that is older then current day (within 24 hour clock) based on Central Time | 410 | 2200 | A config cannot be executed on Qualify response from the previous days TxID <> |
Config | Partner Order ID and transaction combination must be unique to a config request and must remain constant thru order submit. | 410 | 2131 | Transaction Id <B> and PartnerOrderId <> combination must remain constant through Complete; TxID <> |
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. | ||||
Config | Configtype value is missing in the Config request | 401 | 2106 | Missing or invalid configType (Config or Reconfig are expected values); TxIX <> |
Config (for Re-Config) | Billing Type | 410 | 2170 | Re-Config cannot contain customer information; TxID <> |
Config (for Re-Config) | Billing Type | 410 | 2181 | Cannot change Billtype on Re-Config request type; TxID <> |
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.