Skip to content
Python wrapper for the Zendesk API
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs More docs (#304) Mar 8, 2019
specification Custom agent roles API implementation (#314) Mar 24, 2019
tests Fix tests. Feb 24, 2019
zenpy Custom agent roles API implementation (#314) Mar 24, 2019
.travis.yml More docs (#304) Mar 8, 2019
LICENSE Create LICENSE Sep 15, 2015
requirements.txt More docs (#304) Mar 8, 2019

Build Status


Zenpy is a Python wrapper for the Zendesk, Chat and HelpCentre APIs. The goal of the project is to make it easy to write clean, fast, Pythonic code when interacting with Zendesk progmatically. The wrapper tries to keep API calls to a minimum. Wherever it makes sense objects are cached, and attributes of objects that would trigger an API call are evaluated lazily.

Zenpy supports both Python2 and Python3.

Note: HelpCentre API support is in beta.

Please report bugs!


from zenpy import Zenpy
# Create a Zenpy instance
zenpy_client = Zenpy(**credentials)

# Create a new ticket"Important", description="Thing"))

# Perform a simple search
for ticket in'PC LOAD LETTER', type='ticket', assignee='facetoe'):
    # No need to mess around with ids, linked objects can be accessed directly.

    # All objects can be converted to a Python dict.

    # Or to JSON.


Searching open and pending tickets for a specific user and sort them by descending'ticket', status_less_than='closed', assignee='', sort_order='desc')
Searching only opened tickets'ticket', status='open')
Creating a ticket with a different requester
from zenpy.lib.api_objects import Ticket, User
    Ticket(description='Some description',
           requester=User(name='bob', email=''))
Commenting on a ticket
from zenpy.lib.api_objects import Comment

ticket =
ticket.comment = Comment(body="Important private comment", public=False)
Adding a HTML comment to a ticket
from zenpy.lib.api_objects import Ticket, Comment
    subject='Html comment example',
    comment=Comment(body='The smoke is very colorful',
                    html_body='<h2>The smoke is <i>very</i> colourful</h2>'))
Appending tags to a ticket
from zenpy.lib.api_objects import Ticket

ticket =
ticket.tags.extend(['onetag', 'twotag', 'threetag', 'four'])
Uploading an attachment
from zenpy.lib.api_objects import Comment

# Upload the file (or file-like object) to Zendesk and obtain an Upload instance
upload_instance = zenpy_client.attachments.upload('/tmp/awesome_file.txt')

ticket =
ticket.comment = Comment(body='This comment has my file attached', uploads=[upload_instance.token])
Creating a ticket with a custom field set
from zenpy.lib.api_objects import CustomField, Ticket

ticket_audit =
    subject='Has custom field',
    description="Wow, such field",
    custom_fields=[CustomField(id=43528467, value=1337)]
Updating a custom field on a ticket
from zenpy.lib.api_objects import CustomField
ticket =
ticket.custom_fields.append(CustomField(id=43528467, value=1337))
Applying a Macro to a ticket
# Execute the show_macro_effect() method which returns what the macro *would* do.
# The method accepts either Zenpy objects or ids. 
macro_result =, macro_id_or_object)

# Update the ticket to actually change the ticket.
Adding a photo to a user
user = zenpy_client.users(id=user_id)
user.remote_photo_url = 'http://domain/example_photo.jpg'


Check out the documentation for more info.


Contributions are very welcome. I've written an explanation of the core ideas of the wrapper in the Contributors Guide.

You can’t perform that action at this time.