Service Diagnostics

Enables the use of Lumen internal triage logic to assist in isolating trouble points or identifying possible performance issues with Lumen services.

API Overview

Functional Overview

Lumen Service Diagnostics APIs enable the use of Lumen’s internal triage logic to assist in isolating trouble points or identifying possible performance issues with Lumen services. API access allows use of this logic for customers to create their own UI or process flows that will use the Lumen next suggested actions to better understand the current state of a customer service. This document provides technical information that Lumen customers may use to access the Service Diagnostics APIs and interpret the responses or error messages when interfacing with the APIs. It does not intend to provide technical training on the individual dispositions and how they are interpreted on networks or within systems.

Intended User (Target Audience)

The Service Diagnostics APIs are only for use by approved Lumen Customers. All of the Lumen customers who intend to use Service Diagnostics APIs should request access for API Marketplace and complete the required authentication and authorization prerequisites before accessing the APIs. The Service Diagnostics APIs and associated technology should be used by someone who is familiar with API interfaces, REST, and JSON.

Service Diagnostics APIs are designed to most effectively support Lumen Layer 3 (IP associated) services at this time and will be expanding into other product delivery types in future releases.

Business Benefits

Lumen Service Diagnostics APIs allow a Customer to directly call APIs from their own application instead of having to login to a Lumen system or front end application to get this information. This should enable a more efficient process for self-diagnosing services, viewing connection statuses, and creating tickets from their own applications. The Service Diagnostics APIs are not intended to be used as a persistent state check on any or all services on a repetitive basis and are intended to be used in a flow process when a services issue is detected, expected, or has been previously reported and additional information is needed.

Getting started

Quick Start Guide

Enroll in Service Diagnostics APIs. Contact your account representative to assist with enrolling.
Register user and API Apps
Obtain API keys. Upon enrollment you will receive test credentials to access any available 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 the Documentation/Specification section:
- Click on the Authorize button and add your Test credentials.
- Select the Service Diagnostics GET/service/detail API.
- Click on the “Try it out” button.
- Fill in the Parameters.
- Click the Execute button to see the response.

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 the Service Diagnostics 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.

Credential	Description	Example
user_name	Email address that grants you access to the developer portal and application registration	your_account@your_domain.com
password	Password for accessing developer portal	password123!
client_id	Application specific credential used to obtain bearer token	KylFl1J5hGdEAYvxvmXf7ekeO0La3cLo
client_secret	Application password used to obtain bearer token	wH1GnMPZEMlMTlHQ
access_token	A current unique OAuth2 bearer token for your application	PPhwBYy6HYm2FqMNCqVUwnaxi4d6

Credential	Description	Example
authorization	Your application's unique API token. Always required.	Bearer PPhwBYy6HYm2FqMNCqVUwnaxi4d6

Documentation / Specification

Code Samples

Examples using curl

Retrieve a current OAuth2 token

curl --request POST -d grant_type=client_credentials -u ${Consumer_Key}:${Consumer_Secret} https://api.lumen.com/oauth/token

Retrieve diagnostics detail report for a service (v2)

curl --request GET -H 'accept: application/json' -H "Authorization: Bearer ${OAuth2_Token}" 'https://api.lumen.com/ServiceAssurance/v2/Diagnostics/service/detail?serviceId=${Service_Id}'

Extract PDF Summary from JSON response of detail report (v2)

A PDF summary file is contained in the Detail API JSON response.
To view the PDF file follow these steps

extract the “pdf” JSON element
strip off the leading text descriptor: data:application/pdf;base64
decode the remainder as base64
save to a file with .pdf extension

Here is an example:

curl --request GET -H 'accept: application/json' -H "Authorization: Bearer ${OAuth2_Token}" \ 'https://api.lumen.com/ServiceAssurance/v2/Diagnostics/service/detail?serviceId=${Service_Id}' \
| jq -r .data[0].pdf | sed 's/data:application\/pdf;base64,//' | base64 --decode > summary.pdf

Status and Codes

200 - OK

400 - Bad Request

403 - Forbidden

404 - Not Found

500 - Internal Server Error

503 - Service Unavailable

Support / Tools

Should you have any questions or issues with this API please click here to contact us.