ServiceNow Customer Connect

Introduction

The ServiceNow Customer Connect API allows you to manage your IT service management processes from one place. Use the API to log or update tickets for KPN products and services you use.

API specification

Test the API on SwaggerHub

Base URL

https://api-prd.kpn.com/network/kpn/servicenow

Conceptual model

KPN ServiceNow conceptual model

Via this API Tickets in KPN ServiceNow can be created and updated. Updates made by KPN in KPN ServiceNow will be placed in a message-queue and can be retrieved via this API.

Prerequisites

You need to be a KPN business market customer and have a KPN service contract for the products and services bought from KPN.

Definitions

A configuration item (CI) is any service component, infrastructure element, or other item that needs to be managed in order to ensure the successful delivery of services.

Ticket

A ticket is a log file of a reported request with a contracted KPN service or piece of KPN equipment. The ticket describes the situation, reports a contact person and is stored in the ServiceNow system.

Base64

Base64 is an encoding algorithm that allows you to transform any characters into an alphabet that consists of Latin letters, digits, plus and slash.

API workflow

KPN ServiceNow API workflow

Features and constraints

Features

Create a new ticket in KPN ServiceNow.
Comment to an existing ticket.
Query for updates on the tickets.
Attachments to tickets are supported.

Constraints

CI type must be chosen from a predefined list of values.
Attachments must be Base64 encoded.
Maximum total size of attachments is 80MB.

Getting started

Make sure you've read What's in it for you for more info on how to register and start testing APIs.

Authentication

The API follows the KPN Store API Authentication Standard to secure the API. It includes the use of OAuth 2.0 client_id and client_secret to receive an access token.

Go to the Authentication tab on top of this page to find out how to:

Authenticate to an API using cURL.
Authenticate to an API on Swaggerhub.
Import Open API Specifications (OAS), also called Swagger files into Postman.

How to...

Create a new ticket

The following endpoint creates a new ticket:

POST /Ticket

Request

You can send JSON content in the request body:


      Request example
      
        Code copied
        
            
      

{
  "ticket_type": "Incident",
  "customer_reference_number": "INC01234567",
  "short_description": "Win11 L schijf: Kan niet worden toegevoegd",
  "description": "Some extended description/nSecond line",
  "service": "Azure Managed Cloud",
  "ci": "GSEM01300",
  "contact": "jan.jansen@customer.com",
  "user": "truus.bakker@customer.com",
  "priority": "1 - Critical",
  "attachments": [
    {
      "name": "test.txt",
      "content": "IQ0KZW5hYmxlIHNlY3JldCBjaXNjbw0KIQ0KIQ0KIQ0KIQ0KIQ0KIQ0KIQ0Kbm8gaXAgc291cmNlLXJvdXRlDQohDQohDQohDQohDQohDQohDQohDQohDQoNCg0KIQ0KaXAgd1ZXVlIDEwMCBvdCiBwZXJtaXQgdWQogdHJhbnNwb3J0IGlucHV0IHRlbG5ldA0KIQ0KZW5k",
      "content_type": "text/plain"
    }
  ]
}

Response

The 200 response provides you with the kpn_ticket_number and the customer_reference_number of the created ticket. These fields are necessary to update the ticket.


      Response example
      
        Code copied
        
            
      

{
    "kpn_ticket_number": "INC#11252133",
    "customer_reference_number": "INC01234567",
    "note": "Incident INC#11252133 has been created;"
}

Note:
More details on how to work with tickets, the possible actions and fields can be found in the attached pdf.
2 ServiceNow CC-API for Customers

Update a ticket

The following endpoint updates a ticket:

PATCH /Ticket

Request

Send JSON content in the request body:


      Example request
      
        Code copied
        
            
      

{
  "action": "Comment",
  "comment": "New comment update",
  "status": "Success",
  "kpn_ticket_number": "INC#34567890",
  "customer_reference_number": "INC01234567",
  "attachments": [
    {
      "name": "test.txt",
      "content": "IQ0KZW5hYmxlIHNlY3JldCBjaXNjbw0KIQ0KIQ0KIQ0KIQ0KIQ0KIQ0KIQ0Kbm8gaXAgc291cmNlLXJvdXRlDQohDQohDQohDQohDQohDQohDQohDQohDQoNCg0KIQ0KaXAgd1ZXVlIDEwMCBvdCiBwZXJtaXQgdWQogdHJhbnNwb3J0IGlucHV0IHRlbG5ldA0KIQ0KZW5k",
      "content_type": "text/plain"
    }
  ]
}

Response

The 200 response provides you with the kpn_ticket_number and the customer_reference_number of the updated ticket.


      Example response
      
        Code copied
        
            
      

{
    "kpn_ticket_number": "INC#34567890",
    "customer_reference_number": "INC01234567",
    "note": "Incident INC#34567890 has been updated;"
}

Update Tasks

The following endpoint updates a task:

PATCH /Task

Request

Send JSON content in the request body:


      Example request
      
        Code copied
        
            
      

{
  "action": "Comment",
  "comment": "New comment update",
  "status": "Success",
  "kpn_ticket_number": "INTASK#34567890",
  "customer_reference_number": "TASK01234567",
  "attachments": [
    {
      "name": "test.txt",
      "content": "IQ0KZW5hYmxlIHNlY3JldCBjaXNjbw0KIQ0KIQ0KIQ0KIQ0KIQ0KIQ0KIQ0Kbm8gaXAgc291cmNlLXJvdXRlDQohDQohDQohDQohDQohDQohDQohDQohDQoNCg0KIQ0KaXAgd1ZXVlIDEwMCBvdCiBwZXJtaXQgdWQogdHJhbnNwb3J0IGlucHV0IHRlbG5ldA0KIQ0KZW5k",
      "content_type": "text/plain"
    }
  ]
}

Response

The 200 response provides you with the kpn_ticket_number and the customer_reference_number of the updated ticket.


      Example response
      
        Code copied
        
            
      

{
    "kpn_ticket_number": "INTASK#34567890",
    "customer_reference_number": "TASK01234567",
    "note": "Task INTASK#34567890 has been updated;"
}

Note:
More details on how to work with tasks, the possible actions and fields can be found in the attached pdf.
3 ServiceNow CC-API for Providers

Retrieve ticket updates

This endpoint returns not yet retrieved ticket updates for all the tickets of the customer managed via the api. This should be checked on a regular base to get all the updates for active tickets.

Note: Advice is to use this operation maximum once per 5 minutes.

GET /TicketUpdates

Request

You don't need to provide any parameters.

Response

The 200 response will return an array with all active updates on the tickets. The updates will be removed from the queue after retrieval, all updates can be retrieved once. If there are no active updates an empty array will be returned.


      Response example
      
        Code copied
        
            
      

[
  {
    "message_datetime_utc": "2024-09-11T13:16:50.2099834Z",
    "ticket_type": "Incident",
    "transaction_id": "de082a10-d858-4f8b-9648-9b6c8b2fb517",
    "action": "Attachment",
    "kpn_ticket_number": "INC#11252428",
    "customer_reference_number": "INC01234567",
    "ticket_attributes": {
      "name": "Test Bijlage 1.txt",
      "size": "0.004",
      "link": "https://api-prd.kpn.com/network/kpn/servicenow/GetAttachment/abb6168e3ba81e10333b3f3a85e45a42",
      "file_action": "Add"
    }
  }
]

Note: The ticket update response can contain updates for multiple tickets. Each message can contain different information depending on the issue type and the status of the ticket. A complete overview of the possible ticket updates is available in a separate pdf document.

If a message is successful retrieved & processed expected is that via the PATCH /Ticket uperation a successful response is send using the transaction_id.

Note:
Details for all the possible updates for tickets and tasks can be found in the attached pdf.
4 ServiceNow CC-API Addendum

Retrieve attachements

This endpoint returns the attachments by calling the link provided in the TicketUpdate.

GET /GetAttachment

Request

You don't need to provide any parameters.

Response

The 200 response will return thne name, content_type and base64 encoded content of the attachment.


      Response example
      
        Code copied
        
            
      

{
    "name": "Test Bijlage 1.txt",
    "content_type": "text/plain",
    "content": "VGVzdA=="
}

Retrieve active tickets

This endpoint returns all active tickets that were issued by you.

GET /ListOpenTickets

Request

You don't need to provide any parameters.

Response

The 200 response will return an array with all active tickets.


      Response example
      
        Code copied
        
            
      


{
    "result": [
        {
            "customer_reference_number": "INC01234567",
            "short_description": "test1",
            "state": "On Hold",
            "kpn_ticket_number": "INC#11203614",
            "ticket_type": "Incident",
            "link": "https://api-prd.kpn.com/network/kpn/servicenow/Ticket?kpn_ticket_number=INC%2311203614"
        },
        {
            "customer_reference_number": "INC01234568",
            "short_description": "test2",
            "state": "New",
            "kpn_ticket_number": "INC#11203618",
            "ticket_type": "Incident",
            "link": "https://api-prd.kpn.com/network/kpn/servicenow/Ticket?kpn_ticket_number=INC%2311203618"
        },
        {
            "customer_reference_number": "INC01234569",
            "short_description": "test3",
            "state": "New",
            "kpn_ticket_number": "INC#11203619",
            "ticket_type": "Request for Information",
            "link": "https://api-prd.kpn.com/network/kpn/servicenow/Ticket?kpn_ticket_number=INC%2311203619"
        }
    ]
}

Retrieve single ticket

This endpoint returns all data of a single ticket:

GET /Ticket?kpn_ticket_number=INC%2311252428

Request

Send the url encode kpn_ticket_number as the query parameter.

Response

The 200 response returns all details of the ticket, including priority, impact, urgency, on_hold_reason and an array with all the comments.


      Response example
      
        Code copied
        
            
      

{
    "result": [
        {
            "category": "Incident",
            "ci": "2-3156425",
            "company": "Customer B.V.",
            "contact": "KPN",
            "description": "test",
            "impact": "1 - High",
            "on_hold_reason": "Awaiting User",
            "priority": "3 - Moderate",
            "customer_reference_number": "INC01234567",
            "resolution_code": null,
            "resolution_notes": "",
            "service": "Managed Cloudservices - KIS Uplink",
            "short_description": "test",
            "sla_due": "14-Aug-2024 12:18:32",
            "state": "On Hold",
            "kpn_ticket_number": "INC#11252428",
            "urgency": "3 - Low",
            "user": "jan.jansen@customer.nl",
            "comments": [
                {
                    "comment": "Looks fine. SNOW can be closed .Thank you.",
                    "date_time": "30-Aug-2024 09:05:36",
                    "user": "via integration"
                },
                {
                    "comment": "As you requested i restored the link for you please check details and let me know if any issue.",
                    "date_time": "30-Aug-2024 07:05:00",
                    "user": "KPN"
                }
            ]
        }
    ]
}

Error responses

In case of an error the API will return an error response:

statusCode 500: Something went wrong technical: the system is temporarely not able to process the request: Please retry
statusCode 400: Something is wrong with the message, see the error code and details for the error


      400 Response example
      
        Code copied
        
            
      

{
    "error": {
        "code": "1000",
        "message": "Received data not complete: Value (1 - Zeer hoog) for field priority is not correct. "
    }
}

Possible Error codes: Can be found in the different pdf's

Postman collection

For easy development and testing a Postman collection is available.
Postman Collection

This collection contains samples of the API calls towards the ServiceNow Customer Connect API.

To use it:

Put the correct client_id and client_secret in de body of the "GetAccessToken" request.
Update the "refStart" variable in this collection with the value you want to use to start your reference number with. Referencenumber will be made in the format "refStart-YYYYMMDD-Counter"

On ticket creation the customer_reference_number and returned kpn_ticket_number will be stored to be used in the patch actions. If a new ticket or task is retrieved the kpn_ticket_number will be stored and a customer_reference_number will be generated and stored.

Messaging

Voice

Video

Chat

Identity

Internet

IoT

LAN/WAN

Service Management

Mobile

Integrations

Features

ServiceNow Customer Connect

Introduction

API specification

Base URL

Conceptual model

Prerequisites

Definitions

API workflow

Features and constraints

Features

Constraints

Getting started

Authentication

How to...

Create a new ticket

Update a ticket

Update Tasks

Retrieve ticket updates

Retrieve attachements

Retrieve active tickets

Retrieve single ticket

Error responses

Postman collection