What is this API?

This API is a comprehensive platform that manages IT services, incidents, changes, and assets within an organization. It provides programmatic access to core functionality, enabling integration with chatbots, automated workflows, and custom applications.

API Overview

• Host:your-api-host.com
• Base Path:/api/v1
• Protocol:HTTPS only
• Authentication:API Key Management (subscription keys required)

What You Can Do With This API

• Create and manage incidents(IT support tickets)
• Search and retrieve knowledge base articles
• Access asset informationfrom the Configuration Management Database (CMDB)
• Manage change requestsand their lifecycle
• Retrieve supporting data(users, categories, operators, etc.)

Core Entities and Their Relationships

Key Terminology

Typical Incident Lifecycle

Authentication Setup

You'll need API Management credentials. All requests require these headers:

Content-Type: application/json
  Access-Control-Allow-Origin: *
  Accept-Encoding: gzip, deflate, br

Your First API Call - Find a Person

Before creating tickets, you need to find user IDs:

// Find a user by name
  const response = await fetch('/api/persons?query=dynamicName=="John Doe"', {
    headers: {
      'Content-Type': 'application/json',
      'Access-Control-Allow-Origin': '*',
      'Accept-Encoding': 'gzip, deflate, br'
    }
  });
  
  const persons = await response.json();
  console.log(persons[0].id); // Use this ID when creating tickets

Understanding Dynamic Dropdowns

This platform is highly configurable. Each organization customizes their instance with their own categories, operator groups, priorities, and call types.

What This Means for Integration:

// ❌ WRONG - These IDs won't work in your environment
  const ticketData = {
    category: { id: "12345-hardware" },      // Your org might not have this
    operatorGroup: { id: "67890-helpdesk" } // Different ID in your instance
  };

// ✅ CORRECT - Always fetch current options first
  const categories = await getDropdownOptions('/api/categories/parent');
  const operatorGroups = await getDropdownOptions('/api/operatorgroups');
  
  const ticketData = {
    category: { id: categories.find(c => c.name === "Hardware").id },
    operatorGroup: { id: operatorGroups.find(g => g.groupName === "IT Support").id }
  };

Why This Approach is Essential:

• Configuration Changes:Admins add/remove/rename categories regularly
• Environment Differences:Dev, test, and prod environments have different IDs
• Organization Differences:Every company's setup is configured differently
• API Failures:Using invalid IDs results in 400 Bad Request errors

Essential Endpoints for Getting Started

1. Find Users (Required for ticket creation)

2. Get Dropdown Options (Required for ticket creation)

3. Create Incident Ticket

4. Search Knowledge Base