Znuny Web Services – REST API

In this detailed guide, you will learn how to activate, configure, and integrate the Znuny REST API (part of the Generic Interface) into your own applications.

1. Architecture & Basic Principles

Znuny provides its Generic Interface via REST and SOAP web services. The REST API communicates via HTTP(S) using the JSON data format and enables:

Ticket Management: Create, retrieve, update, delete
Article Management: Add articles, manage attachments
History & Search: View ticket history and perform complex search queries

Important Note: A standard installation does not contain pre-configured web services – these must be created manually in the Admin area under “Processes & Automation → Web Services”.

2. Configuration

2.1 Activate Generic Interface

In the Admin area, navigate to SysConfig → GenericInterface.Transport and select REST (HTTP).
Under AdminGenericInterfaceTransportHTTPREST, configure timeouts, host headers, and debug levels.
In GenericInterface.Operation, define the desired operations (e.g., TicketCreate, TicketSearch, TicketGet, TicketUpdate, TicketDelete, TicketHistoryGet) and activate them.

2.2 Base URL & Authentication

Base URL TicketCreate
Authentication
- Znuny session cookies
- API keys / tokens (configurable via SysConfig)
- Always use HTTPS for secure transmissions!

3. Endpoints & HTTP Methods (Detailed Overview)

For each endpoint, you will find a detailed presentation of parameters, possible responses, and practical examples here.

3.1 TicketCreate (POST)

URL: /Webservice/<ServiceName>/TicketCreate Method: POST Description: Creates a new ticket and simultaneously creates an initial article.

Parameter	Type	Required	Description
SessionID	Integer	Yes¹	Session ID or UserLogin+Password
UserLogin	String	Yes²	Agent login (in combination with Password)
Password	String	Yes²	Password (in combination with UserLogin)
Ticket.Title	String	Yes	Subject of the ticket
Ticket.Queue	String	Yes	Queue name or Ticket.QueueID
Ticket.State	String	Yes	Initial state (e.g., `new`)
Ticket.Priority	String	Yes	Priority (e.g., `3 normal`)
Ticket.CustomerUser	String	Yes	Customer email or login
Article.Subject	String	Yes	Subject of the first article
Article.Body	String	Yes	Content of the first article
Article.MimeType	String	Yes	`text/plain` or `text/html`

¹ Either SessionID OR UserLogin+Password required. ² If no SessionID token is present.

Example Request: TicketSearch

Example Response: TicketGet

3.2 TicketSearch (GET)

URL: /Webservice/<ServiceName>/TicketSearch Method: GET Description: Searches for tickets based on various filter criteria.

Parameter	Type	Required	Description
UserLogin, Password	String,String	Yes¹	Agent credentials or SessionID²
SessionID	Integer	Yes²	Token for authenticated sessions
Title	String/String[]	No	Wildcard search in title (`%Order%`)
TicketNumber	String/String[]	No	Ticket number(s)
QueueIDs	Integer[]	No	Queue IDs
States	String[]	No	States (`new`, `open`, …)
StateType	String/String[]	No	Open/Closed category
DynamicField_Name.Op	Mixed	No	Dynamic fields with operator (Equals, Like, GreaterThan …)

¹ Either UserLogin+Password OR SessionID. ² If no login pair is provided.

Example Request: TicketUpdate

Example Response: TicketDelete

3.3 TicketGet (GET)

URL: /Webservice/<ServiceName>/TicketGet Method: GET Description: Retrieves detailed ticket data including articles, attachments, and dynamic fields.

Parameter	Type	Required	Description
UserLogin, Password	String,String	Yes¹	Agent credentials or SessionID²
SessionID	Integer	Yes²	Token for authenticated sessions
TicketID	String/String[]	Yes	One or more ticket IDs (comma-separated or array)
DynamicFields	Boolean (0/1)	No	1 = Dynamic fields in result, default = 0
Extended	Boolean	No	1 = Extended metadata (e.g., FirstResponse)
AllArticles	Boolean	No	1 = Return all articles
ArticleLimit	Integer	No	Max. number of returned articles
Attachments	Boolean	No	1 = Embed attachments in Base64
GetAttachmentContents	Boolean	No	1 = Also load attachment contents
HTMLBodyAsAttachment	Boolean	No	1 = Attach HTML version of article as attachment

¹ Either UserLogin+Password OR SessionID. ² If no login pair is provided.

Example Request: TicketHistoryGet

Example Response (abbreviated): /Webservice/<ServiceName>/TicketCreate

3.4 TicketUpdate (PUT)

URL: /Webservice/<ServiceName>/TicketUpdate Method: PUT Description: Updates fields of an existing ticket and can optionally create a new article.

Parameter	Type	Required	Description
SessionID	Integer	Yes¹	Token or UserLogin+Password²
TicketID	Integer	Yes	ID of the ticket to be updated
Ticket.Title	String	No	New title
Ticket.State	String	No	New state
Ticket.Owner	String/ID	No	New owner
Ticket.PendingTime	Hash / Diff	No	New pending time
Article.Subject	String	No	Creates a new article
Article.Body	String	No	Content of the new article
DynamicField…	Array	No	Update dynamic fields
Attachment…	Array	No	Add new attachments

¹ Either SessionID OR UserLogin+Password. ² If no SessionID token is present.

Example Request: POST

Example Response: new

3.5 TicketDelete (DELETE)

URL: /Webservice/<ServiceName>/TicketDelete Method: DELETE Description: Permanently deletes one or more tickets.

Parameter	Type	Required	Description
SessionID	Integer	Yes¹	Token or UserLogin+Password²
TicketID	String/Array	Yes	One or more ticket IDs

Example Request: 3 normal

Example Response: text/plain

3.6 TicketHistoryGet (GET)

URL: /Webservice/<ServiceName>/TicketHistoryGet Method: GET Description: Retrieves the history of one or more tickets.

Parameter	Type	Required	Description
SessionID	Integer	Yes¹	Token or UserLogin+Password²
TicketID	String/Array	Yes	One or more ticket IDs

Example Request: text/html

4. Extension & Customization

4.1 WADL Definition

Define new resources in the WADL file: /Webservice/<ServiceName>/TicketSearch

4.2 YAML Import

Alternatively, you can define operations via YAML: GET

5. Error Handling & Logging

Success indicator: Success: 0|1
Error message: ErrorMessage in JSON
Debugging: Set Debug-Level to Debug in the transport dialog → log entries become visible in the database

6. Use Cases

Scenario	Description
Cross-system automation	Create tickets from monitoring tools (Nagios, Zabbix)
Data synchronization	Batch updates of ticket fields from external CRM
Self-service portals	Customers create their own tickets via REST
Mobile apps	Native iOS/Android apps communicate via REST

Conclusion

The Znuny REST API is flexible, performant, and highly extensible thanks to the Generic Interface. Whether it’s simple ticket creation or complex workflow automation – with just a few steps in the Admin area and standard JSON requests, you can realize seamless integrations into any IT landscape.

7. Python Client: OpenTicketAI `znuny`

For Python developers, the OpenTicketAI package znuny provides a typed client for the Znuny GenericInterface REST API. It handles authentication, request models, and configurable operation URLs for your web service. See the full OpenTicketAI Znuny Python SDK documentation for setup details.

7.1 Installation

pip install znuny

7.2 Quick Start

from znuny import BasicAuth, ClientConfig, TicketOperation, ZnunyClient

client = ZnunyClient(
    ClientConfig(
        base_url="https://znuny.example.com",
        webservice_name="MyWebservice",
        operation_url_map={
            TicketOperation.CREATE: "ticket-create",
            TicketOperation.GET: "ticket-get",
            TicketOperation.SEARCH: "ticket-search",
            TicketOperation.UPDATE: "ticket-update",
        },
    )
)

client.login(BasicAuth(user_login="agent", password="secret"))

7.3 Example: Create a Ticket

from znuny import Article, Ticket, TicketCreate

response = client.create_ticket(
    TicketCreate(
        Ticket=Ticket(
            Title="Server unreachable",
            Queue="Support",
            State="new",
            Priority="3 normal",
            CustomerUser="customer@example.com",
        ),
        Article=Article(
            Subject="Initial report",
            Body="The server has not been responding since 08:00 AM.",
            MimeType="text/plain",
        ),
    )
)

print(response.TicketID)

7.4 Example: Search and Retrieve Tickets

from znuny import TicketGet, TicketSearch

search = client.search_tickets(TicketSearch(Title="%Server%"))

for ticket_id in search.TicketID:
    ticket = client.get_ticket(TicketGet(TicketID=ticket_id, AllArticles=1))
    print(ticket.Ticket[0].Title)

7.5 Supported Operations

Method	Description
`create_ticket()`	Create a new ticket with the first article
`get_ticket()`	Retrieve ticket details incl. articles & attachments
`search_tickets()`	Search tickets by filters
`update_ticket()`	Update fields, state, owner, and articles
`get_ticket_history()`	Load the full history of a ticket

Note: The package name is znuny and it is available on PyPI. More examples and webservice setup guidance are available in the OpenTicketAI Znuny Python SDK documentation.

8. OpenTicketAI Runtime & Znuny Connector

For those who want to not only use the Znuny REST API but intelligently automate it, the OpenTicketAI Runtime is the solution – an on-premise AI platform that classifies, prioritizes, and routes incoming tickets fully automatically.

8.1 System Architecture

                            ┌─────────────────────────┐
  Incoming Emails     ────► │   Znuny (Generic Interface / REST API)  │
                            └────────────┬────────────┘
                                         │  Webhook / Polling
                                         ▼
                            ┌─────────────────────────┐
                            │  OpenTicketAI Runtime   │
                            │  (Docker, On-Premise)   │
                            │  ┌───────────────────┐  │
                            │  │  AI Model (NLP)   │  │
                            │  └───────────────────┘  │
                            └────────────┬────────────┘
                                         │  otai-znuny-znuny Connector
                                         ▼
                            ┌─────────────────────────┐
                            │  Znuny REST API          │
                            │  TicketUpdate / Routing  │
                            └─────────────────────────┘

The runtime runs entirely locally in your data center – no ticket data leaves your infrastructure.

8.2 Installation of the Znuny Connector

Install the OpenTicketAI core library together with the Znuny-specific connector package otai-znuny-znuny:

pip install open-ticket-ai otai-hf-local otai-znuny-znuny

Package	Function
`open-ticket-ai`	OpenTicketAI core: orchestration, pipelines, config
`otai-hf-local`	Local AI models via Hugging Face (On-Premise)
`otai-znuny-znuny`	Connector: reads & writes tickets via Znuny REST

8.3 Configuration

Create a config.yaml and connect the runtime to your Znuny instance:

connector:
  type: znuny
  url: https://znuny.example.com
  username: otai-bot
  password: "${ZNUNY_PASSWORD}"

model:
  provider: hf-local
  model_name: softoft/ticket-classifier-de

routing:
  default_queue: "Unclassified"
  rules:
    - category: "Network"
      queue: "IT-Infrastructure"
      priority: "4 high"
    - category: "Billing"
      queue: "Accounting"
      priority: "3 normal"

8.4 Workflow of Automatic Ticket Processing

Ticket arrives in Znuny (via email or REST TicketCreate)
Connector polls for new tickets at the configured interval via TicketSearch
AI model analyzes subject and article text with Natural Language Processing
Classification result (category, priority, suggested queue) is determined
TicketUpdate via REST sets queue, priority, and optional internal article
Ticket lands fully automatically with the correct team – without manual triage

8.5 Advantages over Manual REST Integration

Feature	Manual REST Integration	OpenTicketAI + Connector
Classification	❌ Manual	✅ Fully automatic (AI)
Data protection	✅ Local	✅ 100% On-Premise
Rule-based routing	✅ Possible	✅ Included
Learning capability	❌ Rigid rules	✅ Model trainable
Setup effort	High	Low (YAML config)

Learn more: Visit openticketai.com/solutions/znuny/ or contact Softoft for an individual demo.

Znuny Web Services – REST API

Znuny Web Services – REST API

1. Architecture & Basic Principles

2. Configuration

2.1 Activate Generic Interface

2.2 Base URL & Authentication

3. Endpoints & HTTP Methods (Detailed Overview)

3.1 TicketCreate (POST)

3.2 TicketSearch (GET)

3.3 TicketGet (GET)

3.4 TicketUpdate (PUT)

3.5 TicketDelete (DELETE)

3.6 TicketHistoryGet (GET)

4. Extension & Customization

4.1 WADL Definition

4.2 YAML Import

5. Error Handling & Logging

6. Use Cases

Conclusion

7. Python Client: OpenTicketAI znuny

7.1 Installation

7.2 Quick Start

7.3 Example: Create a Ticket

7.4 Example: Search and Retrieve Tickets

7.5 Supported Operations

8. OpenTicketAI Runtime & Znuny Connector

8.1 System Architecture

8.2 Installation of the Znuny Connector

8.3 Configuration

8.4 Workflow of Automatic Ticket Processing

8.5 Advantages over Manual REST Integration

7. Python Client: OpenTicketAI `znuny`