Usage

To use Zammad API Client in a project:

from zammad_py import ZammadAPI
# Note the Host URL should be in this format: 'https://zammad.example.org/api/v1/'
client = ZammadAPI(url='<HOST>', username='<USERNAME>', password='<PASSWORD>')

Zammad Resources are implemented as an abstract class (Resource), meaning most objects have the same mechanisms. Because Zammad uses pagination (https://docs.zammad.org/en/latest/api/intro.html#pagination), the pagination is very helpful.

General Methods

Most Resources support these methods.

.all()
Returns a paginated response with _page containing the page number and _items containing a list of elements.
This allows to iterate over the objects.
from zammad_py import ZammadAPI
client = ZammadAPI(url='<HOST>', username='<USERNAME>', password='<PASSWORD>')
# all return a paginated response
this_page = client.user.all()
# Iterate through page object
for user in this_page:
    print(user)
.next_page()
Can be called from the current page (returned by .all())
Contains the next page object if there are any.
next_page = this_page.next_page()
.prev_page()
Can be called from the current page (pagination object)
Contains the previous page object if there are any.
prev_page = this_page.prev_page()
.search(search_string)
Searches the object with a Zammad search query
Learn more about Zammad Search queries here: https://user-docs.zammad.org/en/latest/advanced/search.html
from zammad_py import ZammadAPI
client = ZammadAPI(url='<HOST>', username='<USERNAME>', password='<PASSWORD>')
client.ticket.search('Search Content')
.find(id)
Displays a Resource if you know the id. (Returns a dict)
from zammad_py import ZammadAPI
client = ZammadAPI(url='<HOST>', username='<USERNAME>', password='<PASSWORD>')
client.ticket.find(<TICKETID>)
.create(params)
Creates a new Resource.
You can find the required structure for the params in the Zammad API Documentation.
from zammad_py import ZammadAPI
client = ZammadAPI(url='<HOST>', username='<USERNAME>', password='<PASSWORD>')
params = {
   "title": "Help me!",
   "group": "2nd Level",
   "customer": "david@example.com",
   "article": {
      "subject": "My subject",
      "body": "I am a message!",
      "type": "note",
      "internal": false
   }
}
new_ticket = client.ticket.create(params=params)
.update(params)
Updates a resource.
You can find the required structure for the params in the Zammad API Documentation, or use a dict provided by the .find(id) functionaliy.
from zammad_py import ZammadAPI
client = ZammadAPI(url='<HOST>', username='<USERNAME>', password='<PASSWORD>')
org = client.organization.find(<ID>)
org['name'] = 'NewCompanyName Ltd.'
client.organization.update(id=org['id'],params=org)
.destroy(id)
Deletes a Resource.
For some resources, you need special privileges. Refer to the Zammad API Documentation.
from zammad_py import ZammadAPI
client = ZammadAPI(url='<HOST>', username='<USERNAME>', password='<PASSWORD>')
client.organization.destroy(<ID>)
Available Resources

user organization group ticket link ticketarticle ticketarticleplain ticketpriority ticketstate tickettag object taglist

User Resource

The User resource also has the me() method to get information about the current user.

from zammad_py import ZammadAPI
client = ZammadAPI(url='<HOST>', username='<USERNAME>', password='<PASSWORD>')
print(client.user.me())

Ticket Resource

The Ticket resource also has the articles() method to get the articles associated to the ticket.

from zammad_py import ZammadAPI
client = ZammadAPI(url='<HOST>', username='<USERNAME>', password='<PASSWORD>')
print(client.ticket.find(<ID>))
ticketarticles = client.ticket.articles
print(ticketarticles)

The Ticket resource also has the tags() method to get the tags associated to the ticket.

from zammad_py import ZammadAPI
client = ZammadAPI(url='<HOST>', username='<USERNAME>', password='<PASSWORD>')
print(client.ticket.find(<ID>))
ticket_tags = client.ticket.tags((<ID>))
for ttag in ticket_tags['tags']:
    print(ttga)

Further, it has the merge() method, that allows to merge two tickets. (This is not documented in the Zammad API Documentation) The method requires the Ticket id of the Child (The ticket you want to merge into the parent) and the Ticket Number of the Parent Ticket. (The ticket you want to contain the articles of the child after merging.)

Important: If you want to use the merge functionality, you need to use password, not http_token for your authentication.

from zammad_py import ZammadAPI
client = ZammadAPI(url='<HOST>', username='<USERNAME>', password='<PASSWORD>')
client.ticket.merge(id=<ID>,number=<NUMBER>)

TicketArticleAttachment Resource

The TicketArticleAttachment resource has the download() method.

"""Download the ticket attachment associated with the ticket id

:param id: Ticket attachment id
:param article_id: Ticket article id
:param ticket_id: Ticket id
"""

TagList Resource

The :class ~zammad_py.api.TagList resource handles tags in the admin scope and has methods to create, remove and list tags.

zammad_py.api.TagList.all()
This returns all tags configured (paginated).
zammad_py.api.TagList.create()
Creates a new tag.
zammad_py.api.TagList.destroy()
Deletes a tag with the ID provided.
from zammad_py import ZammadAPI
client = ZammadAPI(url='<HOST>', username='<USERNAME>', password='<PASSWORD>')
client.taglist.create({'name': 'TestTag'})
for tag in client.taglist.all():
    print(tag)
    if tag['name'] == 'TestTag':
        client.taglist.destroy(tag['id'])

TicketTag Resource

The :class ~zammad_py.api.TicketTag resource handles tags in the ticket scope and has methods to add and remove tags associated to tickets.

zammad_py.api.TicketTag.add()
Add a new tag to a ticket. (This will create the tag if it doesn’t exist and the user has permission to do so.)
zammad_py.api.TicketTag.remove()
Remove a tag from a ticket.
from zammad_py import ZammadAPI
client = ZammadAPI(url='<HOST>', username='<USERNAME>', password='<PASSWORD>')
ticket_tags = client.ticket.tags((<ID>))
print(ticket_tags['tags'])  # ['TestTag', 'Zammad']
client.ticket_tag.add(<ID>, 'FancyNewTag')
client.ticket_tag.remove(<ID>, 'Zammad')
ticket_tags = client.ticket.tags((<ID>))
print(ticket_tags['tags'])  # ['TestTag', 'FancyNewTag']

Object Resource

The Object resource has the execute_migrations() method to run the migrations of an object.

Using “On behalf of”

To do actions on behalf of another user, just set the on_behalf_of attribute on the instance of ZammadAPI

from zammad_py import ZammadAPI
client = ZammadAPI(url='<HOST>', username='<USERNAME>', password='<PASSWORD>')
client.on_behalf_of = 'test@user.com'
# Do stuff...