Zenpy¶
Zenpy
is a Python wrapper for the Zendesk API. The goal of the project
is to make it possible to write clean, fast, Pythonic code when
interacting with Zendesk programmatically. 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.
The wrapper supports both reading and writing from the API.
Zenpy
supports both Python2 and Python3.
Installation¶
pip install zenpy
Usage¶
First, create a Zenpy
object:
# Zenpy accepts an API token
creds = {
'email' : 'youremail',
'token' : 'yourtoken',
'subdomain': 'yoursubdomain'
}
# An OAuth token
creds = {
"subdomain": "yoursubdomain",
"oauth_token": "youroathtoken"
}
# Or a password
creds = {
'email' : 'youremail',
'password' : 'yourpassword',
'subdomain': 'yoursubdomain'
}
# Import the Zenpy Class
from zenpy import Zenpy
# Default
zenpy_client = Zenpy(**creds)
# Alternatively you can provide your own requests.Session object
zenpy_client = Zenpy(**creds, session=some_session)
# If you are providing your own HTTPAdapter object, Zenpy provides defaults via the
# Zenpy.http_adapter_kwargs() method. You can choose to use these defaults like so:
session = requests.Session()
session.mount('https://', MyAdapter(**Zenpy.http_adapter_kwargs()))
zenpy_client = Zenpy(**creds, session=some_session)
Custom Domains¶
By default zenpy will make request to:
https://{subdomain}.{domain}/{endpoint}
(with domain being by default zendesk.com), in some cases you may want to override this behaviour (like for local testing or if you have a custom domain for zendesk) You can do this by setting the environment variables:
ZENPY_FORCE_NETLOC
ZENPY_FORCE_SCHEME (default to https)
when set it will force request on:
{scheme}://{netloc}/endpoint
Searching the API¶
All of the search parameters defined in the Zendesk search documentation should work
fine in Zenpy
. Searches are performed by passing keyword arguments to
the search
endpoint. The keyword arguments line up with the Zendesk
search documentation and are mapped as follows:
Keyword
Operator
keyword
: (equality)
*_greater_than
> (numeric|type)
*_less_than
< (numeric|type)
*_after
> (time|date)
*_before
< (time|date)
minus
- (negation)
*_between
> < (dates only)
For example, the code:
yesterday = datetime.datetime.now() - datetime.timedelta(days=1)
today = datetime.datetime.now()
for ticket in zenpy_client.search("zenpy", created_between=[yesterday, today], type='ticket', minus='negated'):
print ticket
Would generate the following API call:
/api/v2/search.json?query=zenpy+created>2015-08-29 created<2015-08-30+type:ticket+-negated
The ordering can be controlled by passing the sort_by
and/or
sort_order
parameters as keyword arguments, eg:
zenpy_client.search("some query", type='ticket', sort_by='created_at', sort_order='desc')
See the Zendesk docs for more information.
Querying the API¶
The Zenpy
object contains methods for accessing many top level
endpoints, and they can be called in one of three ways - no arguments
returns all results (as a generator):
for user in zenpy_client.users():
print user.name
Called with an id returns the object with that ID:
print zenpy_client.users(id=1159307768)
And the last option for many endpoints to get list of several items, use
ids for this. Accepts lists of ids, not list of objects! show_many.json
should exist in Zendesk endpoint, search API
docs.
Example with several ids, returns generator objects:
print zenpy_client.users(ids=[1000000001, 1000000002])
You can also filter by passing in permission_set
or role
.
In addition to the top level endpoints there are several secondary level endpoints that reference the level above. For example, if you wanted to print all the comments on a ticket:
for comment in zenpy_client.tickets.comments(ticket=86):
print comment.body
Or organizations attached to a user:
for organization in zenpy_client.users.organizations(user=1276936927):
print organization.name
You could do so with these second level endpoints.
The vast majority of endpoints are supported, however I’ve chosen not to implement some that seemed unlikely to be used. If there is an endpoint that you would like to see implemented, just create a issue and I’ll look into it.
Creating, Updating and Deleting API Objects¶
Many endpoints support the create
, update
and delete
operations. For example we can create a User
with the following
code:
from zenpy.lib.api_objects import User
user = User(name="John Doe", email="john@doe.com")
created_user = zenpy_client.users.create(user)
The create
method returns the created object with it’s various
attributes (such as id
/ created_at
) filled in by Zendesk.
We can update this user by modifying it’s attributes and calling the
update
method:
created_user.role = 'agent'
created_user.phone = '123 434 333'
modified_user = zenpy_client.users.update(created_user)
Like create
, the update
method returns the modified object.
Next, let’s assign all new tickets to this user:
for new_ticket in zenpy_client.search(type='ticket', status='new'):
new_ticket.assignee = modified_user
ticket_audit = zenpy_client.tickets.update(new_ticket)
When updating a ticket, a TicketAudit
object
is returned. This object contains the newly updated Ticket
as
well as some additional information in the Audit
object.
Finally, let’s delete all the tickets assigned to the user:
for ticket in zenpy_client.search(type='ticket', assignee='John Doe'):
zenpy.tickets.delete(ticket)
Deleting ticket returns nothing on success and raises an
ApiException
on failure.
Bulk Operations¶
Zendesk supports bulk creating, updating and deleting API objects, and
so does Zenpy
. The create
, update
and delete
methods all
accept either an object, or a list of objects.
For example, the code:
job_status = zenpy_client.tickets.create(
[Ticket(subject="Ticket%s" % i, description="Bulk") for i in range(0, 20)]
)
will create 20 tickets in one API call. When performing bulk operations, a
JobStatus
object
is returned. The only exception to this is bulk delete
operations, which
return nothing on success and raise a APIException
on failure.
Notes:
1. It is important to note that these bulk endpoints have restrictions on
the number of objects that can be processed at one time (usually 100).
Zenpy
makes no attempt to regulate this. Most endpoints will throw an
APIException
if that limit is exceeded, however some simply process
the first N objects and silently discard the rest.
2. On high intensive job loads (intensive imports, permanent delete operations, etc) Zendesk side API does not return /api/v2/job_statuses/{job_id}.json page, so if you try to query it with:
job_status = zenpy_client.job_status(id={job_id})
you will get HTTPError
. In same time page: /api/v2/job_statuses/ always
exist and contains last 100 jobs. So parse whole job list to get results:
job_id = 'some Zendesk job id'
job_statuses = zenpy_client.job_status()
for job in job_statuses:
if job.id == job_id:
do something
Incremental Exports¶
Zendesk has several incremental API endpoints (Zendesk documentation) to export items in bulk (up to 1000 items per request) and also to poll the API for changes since a point in time.
Incremental endpoints accept either a datetime object or a unix
timestamp as the start_time
parameter. For example, the following
code will retrieve all tickets created or modified in the last day:
yesterday = datetime.datetime.now() - datetime.timedelta(days=1)
result_generator = zenpy_client.users.incremental(start_time=yesterday)
for user in result_generator:
print user.id
The last end_time
value can be retrieved from the generator:
print result_generator.end_time
Passing this value to a new call as the start_time
will return items
created or modified since that point in time.
Pagination¶
Pagination in Zenpy
is supported via Python slices. The current
implementation has a few limitations:
Does not support negative values (no fancy slicing)
Always pulls the first 100 objects (sometimes one extra API call than necessary)
Does not support multiple accesses of the same slice
Example Usage:
ticket_generator = zenpy_client.tickets()
# Arguments to slice are [start:stop:page_size], they are all optional
tickets = ticket_generator[3950:4000:50]
print(tickets)
# The following examples do what you would expect
tickets = ticket_generator[240:]
tickets = ticket_generator[:207]
tickets = ticket_generator[::]
Cursor Based Generators¶
Zendesk uses cursor based pagination for the TicketAudit endpoint. The use
of a cursor allows you to change the direction in which you consume objects.
This is supported in Zenpy
via the reversed() Python method:
audit_generator = zenpy_client.tickets.audits()
# You can retrieve the cursor values from the generator.
print(audit_generator.after_cursor, audit_generator.before_cursor)
# Iterate over the last 1000 audits.
for audit in audit_generator:
print(audit)
# You can pass an explicit cursor value to consume audits create after that point.
for audit in zenpy_client.tickets.audits(cursor='fDE1MTc2MjkwNTQuMHx8'):
print(audit)
# Reversing the generator reverses the direction in which you consume objects. The
# following grabs objects from just before the cursor value until the beginning of time.
for audit in reversed(zenpy_client.tickets.audits(cursor='fDE1MTc2MjkwNTQuMHx8')):
print(audit)
Zendesk also uses cursor based pagination for incremental Ticket exports and this is recommended over time based pagination for Ticket exports (Zendesk documentation).
The last after_cursor
value can be retrieved from the generator:
print result_generator.after_cursor
Passing this value to a new call as zenpy_client.tickets.incremental(cursor=after_cursor, paginate_by_time=False)
will return items created or modified since that point in time.
Rate Limiting¶
Zendesk imposes rate limiting.
By default Zenpy
will detect this and wait the required period before trying again, however for some use cases
this is not desirable. Zenpy
offers two additional configuration options to control rate limiting:
proactive_ratelimit
If you wish to avoid ever hitting the rate limit you can set the proactive_ratelimit parameter when instantiating
Zenpy
:zenpy_client = Zenpy(proactive_ratelimit=700, **creds)
proactive_ratelimit_request_interval
When utilizing the proactive_ratelimit feature, you can also specify how long to wait when you are over your proactive_ratelimit.
ratelimit_budget
If you have a maximum amount of time you are willing to wait for rate limiting, you can set the ratelimit_budget parameter. This budget is decremented for every second spent being rate limited, and when the budget is spent throws a RatelimitBudgetExceeded exception. For example, if you wish to wait no more than 60 seconds:
zenpy_client = Zenpy(ratelimit_budget=60, **creds)
Side-Loading¶
Zendesk supports “side-loading” objects to reduce the number of API
calls necessary to retrieve what you are after Zendesk API Reference.
Zenpy
currently only minimally supports this feature, however
I plan to add proper support for it soon.
If this is something you really want raise an issue and I will get to it
sooner. To take advantage of this feature for those endpoints that support
it, simple pass an include
kwarg with the objects you would like to load,
eg:
for ticket in zenpy_client.tickets(include=['users']):
print(ticket.submitter)
The code above will not need to generate an additional API call to retrieve the submitter as it was returned and cached along with the ticket.
Caching¶
Zenpy
support caching objects to prevent API calls, and each
Zenpy
instance has it’s own set of caches.
If we turn logging on, we can see Zenpy
caching in action. The code:
me = zenpy_client.users.me()
user = zenpy_client.users(id=me.id)
user = zenpy_client.users(id=me.id)
Outputs:
DEBUG - GET: https://d3v-zenpydev.zendesk.com/api/v2/users/me.json - {'timeout': 60.0}
DEBUG - Caching: [User(id=116514121092)]
DEBUG - Cache HIT: [User 116514121092]
DEBUG - Cache HIT: [User 116514121092]
Here we see that only one API call is generated, as the user already existed in the cache after the first call.
This feature is especially useful when combined with side-loading. As an example, the following code:
ticket = zenpy_client.tickets(id=6569, include='users')
print(ticket.requester.name)
Outputs:
DEBUG - Cache MISS: [Ticket 6569]
DEBUG - GET: https://d3v-zenpydev.zendesk.com/api/v2/tickets/6569.json?include=users - {'timeout': 60.0}
DEBUG - Caching: [Ticket(id=6569)]
DEBUG - Caching: [User(id=116514121092)]
DEBUG - Cache HIT: [User 116514121092]
We can see that because we “side-loaded” users, an extra API call was not generated when we attempted to access the requester attribute.
Controlling Caching¶
The Zenpy
object contains methods for adding, removing and modifying
caches. Each object type can have a different cache implementation and
settings. For example, you might use a
TTLCache
for Ticket
objects with a timeout of one minute, and a
LFUCache
for Organization
objects. It’s even possible to change cache
implementations on the fly.
For example, to also cache SatisfactionRatings:
zenpy_client.add_cache(object_type='satisfaction_rating', cache_impl_name='LRUCache', maxsize=10000)
Cache method reference¶
add_cache
(object_type, cache_impl_name, maxsize, **kwargs)¶Add a new cache for the named object type and cache implementation
caching_engines
()¶Returns available caching engines.
caching_status
()¶Returns caching status.
delete_cache
(cache_name)¶Deletes the named cache
disable_caching
()¶Disable caching of objects.
enable_caching
()¶Enable caching of objects.
get_cache_impl_name
(cache_name)¶Returns the name of the cache implementation for the named cache
get_cache_max
(cache_name)¶Returns the maxsize attribute of the named cache
get_cache_names
()¶Returns a list of current caches
purge_cache
(cache_name)¶Purges the named cache.
set_cache_implementation
(cache_name, impl_name, maxsize, **kwargs)¶Changes the cache implementation for the named cache
set_cache_max
(cache_name, maxsize, **kwargs)¶Sets the maxsize attribute of the named cache
Zenpy Endpoint Reference¶
-
class
Zenpy
(domain='zendesk.com', subdomain=None, email=None, token=None, oauth_token=None, password=None, session=None, timeout=None, ratelimit_budget=None, proactive_ratelimit=None, proactive_ratelimit_request_interval=10, disable_cache=False)¶
users
(*args, **kwargs)¶
Add (PUT) one or more tags.
- Parameters
id – the id of the object to tag
tags – array of tags to apply to object
create
(api_objects, **kwargs)¶Create (POST) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to create
create_or_update
(users)¶Creates a user (POST) if the user does not already exist, or updates an existing user identified by e-mail address or external ID.
- Parameters
users – User object or list of User objects
- Returns
the created/updated User or a JobStatus object if a list was passed
delete
(api_objects, **kwargs)¶Delete (DELETE) one or more API objects. After successfully deleting the objects from the API they will also be removed from the relevant Zenpy caches.
- Parameters
api_objects – object or objects to delete
delete_by_external_id
(api_objects)¶Delete (DELETE) one or more API objects by external_id.
- Parameters
api_objects –
Delete (DELETE) one or more tags.
- Parameters
id – the id of the object to delete tag from
tags – array of tags to delete from object
deleted
()¶List Deleted Users.
These are users that have been deleted but not permanently yet. Zendesk API Reference.
- Returns
incremental
(start_time, include=None, per_page=None)¶Retrieve bulk data from the incremental API.
- Parameters
include – list of objects to sideload. Side-loading API Docs.
start_time – The time of the oldest object you are interested in.
me
(include=None)¶Return the logged in user
- Parameters
include – list of objects to sideload. Side-loading API Docs.
Set (POST) one or more tags.
- Parameters
id – the id of the object to tag
tags – array of tags to apply to object
Lists the most popular recent tags in decreasing popularity from a specific ticket.
update
(api_objects, **kwargs)¶Update (PUT) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to update
update_by_external_id
(api_objects)¶Update (PUT) one or more API objects by external_id.
- Parameters
api_objects –
tickets
(*args, **kwargs)¶
add_tags
(id, tags)Add (PUT) one or more tags.
- Parameters
id – the id of the object to tag
tags – array of tags to apply to object
create
(api_objects, **kwargs)Create (POST) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to create
delete
(api_objects, **kwargs)Delete (DELETE) one or more API objects. After successfully deleting the objects from the API they will also be removed from the relevant Zenpy caches.
- Parameters
api_objects – object or objects to delete
delete_tags
(id, tags)Delete (DELETE) one or more tags.
- Parameters
id – the id of the object to delete tag from
tags – array of tags to delete from object
deleted
()List Deleted Tickets.
These are tickets that have been deleted but not permanently yet. See Permanently delete ticket in Zendesk API docs
- Returns
ResultGenerator with Tickets objects with length 0 of no deleted tickets exist.
events
(start_time, include=None, per_page=None)¶Retrieve TicketEvents
- Parameters
include – list of objects to sideload. Side-loading API Docs.
start_time – time to retrieve events from.
incremental
(start_time=None, paginate_by_time=True, cursor=None, include=None, per_page=None)Incrementally retrieve Tickets.
If paginate_by_time is True, a ZendeskResultGenerator is returned to handle time based pagination. This is defaulted to True for backwards compatibility but is not recommended by Zendesk.
If paginate_by_time is False, a TicketCursorGenerator is returned to handle cursor based pagination. This is recommended by Zendesk.
The TicketCursorGenerator allows you to change the direction that you are consuming objects. This is done with the reversed() python method.
For example:
for ticket in reversed(zenpy_client.tickets.incremental(cursor='xxx')): print(ticket)See the Zendesk docs for information on additional parameters.
- Parameters
start_time – the time of the oldest object you are interested in, applies to both time/cursor based pagination.
paginate_by_time – True to use time based pagination, False to use cursor based pagination.
cursor – cursor value of the page you are interested in, can’t be set with start_time.
include – list of objects to sideload. Side-loading API Docs.
per_page – number of results per page, up to max 1000
metrics_incremental
(start_time)¶Retrieve TicketMetric incremental
- Parameters
start_time – time to retrieve events from.
permanently_delete
(tickets)¶Permanently delete ticket. See Zendesk API docs
Ticket should be softly deleted first with regular delete method.
- Parameters
tickets – Ticket object or list of tickets objects
- Returns
JobStatus object
rate
(id, rating)¶Add (POST) a satisfaction rating.
- Parameters
id – id of object to rate
rating – SatisfactionRating
recent
(include=None)¶Retrieve the most recent tickets
set_tags
(id, tags)Set (POST) one or more tags.
- Parameters
id – the id of the object to tag
tags – array of tags to apply to object
tags
(ticket_id)Lists the most popular recent tags in decreasing popularity from a specific ticket.
update
(api_objects, **kwargs)Update (PUT) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to update
organizations
(*args, **kwargs)¶
add_tags
(id, tags)Add (PUT) one or more tags.
- Parameters
id – the id of the object to tag
tags – array of tags to apply to object
create
(api_objects, **kwargs)Create (POST) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to create
create_or_update
(organization)Creates an organization if it doesn’t already exist, or updates an existing organization identified by ID or external ID
- Parameters
organization – Organization object
- Returns
the created/updated Organization
delete
(api_objects, **kwargs)Delete (DELETE) one or more API objects. After successfully deleting the objects from the API they will also be removed from the relevant Zenpy caches.
- Parameters
api_objects – object or objects to delete
delete_by_external_id
(api_objects)Delete (DELETE) one or more API objects by external_id.
- Parameters
api_objects –
delete_tags
(id, tags)Delete (DELETE) one or more tags.
- Parameters
id – the id of the object to delete tag from
tags – array of tags to delete from object
external
(external_id, include=None)¶Locate an Organization by it’s external_id attribute.
- Parameters
include – list of objects to sideload. Side-loading API Docs.
external_id – external id of organization
incremental
(start_time, include=None, per_page=None)Retrieve bulk data from the incremental API.
- Parameters
include – list of objects to sideload. Side-loading API Docs.
start_time – The time of the oldest object you are interested in.
set_tags
(id, tags)Set (POST) one or more tags.
- Parameters
id – the id of the object to tag
tags – array of tags to apply to object
tags
(ticket_id)Lists the most popular recent tags in decreasing popularity from a specific ticket.
update
(api_objects, **kwargs)Update (PUT) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to update
update_by_external_id
(api_objects)Update (PUT) one or more API objects by external_id.
- Parameters
api_objects –
views
(*args, **kwargs)¶
active
(include=None)¶Return all active views.
create
(api_objects, **kwargs)Create (POST) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to create
delete
(api_objects, **kwargs)Delete (DELETE) one or more API objects. After successfully deleting the objects from the API they will also be removed from the relevant Zenpy caches.
- Parameters
api_objects – object or objects to delete
search
(*args, **kwargs)¶Search views. See Zendesk API Reference.
- Parameters
args – query is the only accepted arg.
kwargs – search parameters
update
(api_objects, **kwargs)Update (PUT) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to update
requests
(*args, **kwargs)¶
ccd
()¶Return all ccd requests
comments
(request_id)¶Return comments for request
create
(api_objects, **kwargs)Create (POST) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to create
open
()¶Return all open requests
search
(*args, **kwargs)Search for requests. See the Zendesk docs for more information on the syntax.
solved
()¶Return all solved requests
update
(api_objects, **kwargs)Update (PUT) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to update
groups
(*args, **kwargs)¶
create
(api_objects, **kwargs)Create (POST) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to create
delete
(api_objects, **kwargs)Delete (DELETE) one or more API objects. After successfully deleting the objects from the API they will also be removed from the relevant Zenpy caches.
- Parameters
api_objects – object or objects to delete
update
(api_objects, **kwargs)Update (PUT) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to update
chats
(*args, **kwargs)¶
incremental
(start_time, **kwargs)Retrieve bulk data from the chat incremental API.
- Parameters
fields – list of fields to retrieve. Chat API Docs.
start_time – The time of the oldest object you are interested in.
group_memberships
(*args, **kwargs)¶
assignable
()¶Return GroupMemberships that are assignable.
create
(api_objects, **kwargs)Create (POST) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to create
delete
(api_objects, **kwargs)Delete (DELETE) one or more API objects. After successfully deleting the objects from the API they will also be removed from the relevant Zenpy caches.
- Parameters
api_objects – object or objects to delete
end_user
(*args, **kwargs)¶
update
(api_objects, **kwargs)Update (PUT) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to update
macros
(*args, **kwargs)¶
create
(api_objects, **kwargs)Create (POST) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to create
delete
(api_objects, **kwargs)Delete (DELETE) one or more API objects. After successfully deleting the objects from the API they will also be removed from the relevant Zenpy caches.
- Parameters
api_objects – object or objects to delete
update
(api_objects, **kwargs)Update (PUT) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to update
organization_fields
(*args, **kwargs)¶
create
(api_objects, **kwargs)Create (POST) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to create
delete
(api_objects, **kwargs)Delete (DELETE) one or more API objects. After successfully deleting the objects from the API they will also be removed from the relevant Zenpy caches.
- Parameters
api_objects – object or objects to delete
update
(api_objects, **kwargs)Update (PUT) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to update
sla_policies
(*args, **kwargs)¶
delete
(api_objects, **kwargs)Delete (DELETE) one or more API objects. After successfully deleting the objects from the API they will also be removed from the relevant Zenpy caches.
- Parameters
api_objects – object or objects to delete
automations
(*args, **kwargs)¶
create
(api_objects, **kwargs)Create (POST) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to create
delete
(api_objects, **kwargs)Delete (DELETE) one or more API objects. After successfully deleting the objects from the API they will also be removed from the relevant Zenpy caches.
- Parameters
api_objects – object or objects to delete
update
(api_objects, **kwargs)Update (PUT) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to update
brands
(*args, **kwargs)¶
create
(api_objects, **kwargs)Create (POST) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to create
delete
(api_objects, **kwargs)Delete (DELETE) one or more API objects. After successfully deleting the objects from the API they will also be removed from the relevant Zenpy caches.
- Parameters
api_objects – object or objects to delete
update
(api_objects, **kwargs)Update (PUT) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to update
custom_agent_roles
(*args, **kwargs)¶
create
(api_objects, **kwargs)Create (POST) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to create
delete
(api_objects, **kwargs)Delete (DELETE) one or more API objects. After successfully deleting the objects from the API they will also be removed from the relevant Zenpy caches.
- Parameters
api_objects – object or objects to delete
update
(api_objects, **kwargs)Update (PUT) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to update
dynamic_content
(*args, **kwargs)¶
create
(api_objects, **kwargs)Create (POST) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to create
delete
(api_objects, **kwargs)Delete (DELETE) one or more API objects. After successfully deleting the objects from the API they will also be removed from the relevant Zenpy caches.
- Parameters
api_objects – object or objects to delete
update
(api_objects, **kwargs)Update (PUT) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to update
jira_links
(*args, **kwargs)¶
create
(api_objects, **kwargs)Create (POST) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to create
delete
(api_objects, **kwargs)Delete (DELETE) one or more API objects. After successfully deleting the objects from the API they will also be removed from the relevant Zenpy caches.
- Parameters
api_objects – object or objects to delete
organization_memberships
(*args, **kwargs)¶
create
(api_objects, **kwargs)Create (POST) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to create
delete
(api_objects, **kwargs)Delete (DELETE) one or more API objects. After successfully deleting the objects from the API they will also be removed from the relevant Zenpy caches.
- Parameters
api_objects – object or objects to delete
recipient_addresses
(*args, **kwargs)¶
create
(api_objects, **kwargs)Create (POST) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to create
delete
(api_objects, **kwargs)Delete (DELETE) one or more API objects. After successfully deleting the objects from the API they will also be removed from the relevant Zenpy caches.
- Parameters
api_objects – object or objects to delete
update
(api_objects, **kwargs)Update (PUT) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to update
create
(api_objects, **kwargs)Create (POST) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to create
delete
(api_objects, **kwargs)Delete (DELETE) one or more API objects. After successfully deleting the objects from the API they will also be removed from the relevant Zenpy caches.
- Parameters
api_objects – object or objects to delete
update
(api_objects, **kwargs)Update (PUT) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to update
skips
(*args, **kwargs)¶
create
(api_objects, **kwargs)Create (POST) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to create
targets
(*args, **kwargs)¶
create
(api_objects, **kwargs)Create (POST) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to create
delete
(api_objects, **kwargs)Delete (DELETE) one or more API objects. After successfully deleting the objects from the API they will also be removed from the relevant Zenpy caches.
- Parameters
api_objects – object or objects to delete
update
(api_objects, **kwargs)Update (PUT) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to update
ticket_fields
(*args, **kwargs)¶
create
(api_objects, **kwargs)Create (POST) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to create
delete
(api_objects, **kwargs)Delete (DELETE) one or more API objects. After successfully deleting the objects from the API they will also be removed from the relevant Zenpy caches.
- Parameters
api_objects – object or objects to delete
update
(api_objects, **kwargs)Update (PUT) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to update
ticket_forms
(*args, **kwargs)¶
create
(api_objects, **kwargs)Create (POST) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to create
delete
(api_objects, **kwargs)Delete (DELETE) one or more API objects. After successfully deleting the objects from the API they will also be removed from the relevant Zenpy caches.
- Parameters
api_objects – object or objects to delete
update
(api_objects, **kwargs)Update (PUT) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to update
ticket_import
(*args, **kwargs)¶
create
(api_objects, **kwargs)Create (POST) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to create
triggers
(*args, **kwargs)¶
create
(api_objects, **kwargs)Create (POST) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to create
delete
(api_objects, **kwargs)Delete (DELETE) one or more API objects. After successfully deleting the objects from the API they will also be removed from the relevant Zenpy caches.
- Parameters
api_objects – object or objects to delete
update
(api_objects, **kwargs)Update (PUT) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to update
user_fields
(*args, **kwargs)¶
create
(api_objects, **kwargs)Create (POST) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to create
delete
(api_objects, **kwargs)Delete (DELETE) one or more API objects. After successfully deleting the objects from the API they will also be removed from the relevant Zenpy caches.
- Parameters
api_objects – object or objects to delete
update
(api_objects, **kwargs)Update (PUT) one or more API objects. Before being submitted to Zendesk the object or objects will be serialized to JSON.
- Parameters
api_objects – object or objects to update
attachments
(*args, **kwargs)¶
download
(attachment_id, destination)¶Download an attachment from Zendesk.
- Parameters
attachment_id – id of the attachment to download
destination – destination path. If a directory, the file will be placed in the directory with the filename from the Attachment object.
- Returns
the path the file was written to
upload
(fp, token=None, target_name=None, content_type=None)¶Upload a file to Zendesk.
- Parameters
fp – file object, StringIO instance, content, or file path to be uploaded
token – upload token for uploading multiple files
target_name – name of the file inside Zendesk
- Returns
Upload
object containing a token and other information see Zendesk API Reference.
satisfaction_ratings
(*args, **kwargs)¶
search
(*args, **kwargs)The search endpoint accepts all the parameters defined in the Zendesk Search Documentation. Zenpy defines several keywords that are mapped to the Zendesk comparison operators:
Keyword
Operator
keyword
: (equality)
*_greater_than
> (numeric|type)
*_less_than
< (numeric|type)
*_after
> (time|date)
*_before
< (time|date)
minus
- (negation)
*_between
> < (dates only)
For example the call:
zenpy.search("zenpy", created_between=[yesterday, today], type='ticket', minus='negated')Would generate the following API call:
/api/v2/search.json?query=zenpy+created>2015-08-29 created<2015-08-30+type:ticket+-negated .. py:method:: count(*args, **kwargs) Returns results count only
activities
(*args, **kwargs)¶
help_center
(*args, **kwargs)¶
job_status
(*args, **kwargs)¶
tags
(*args, **kwargs)
talk
(*args, **kwargs)¶
ticket_metric_events
(*args, **kwargs)¶An IncrementalEndpoint takes a start_time parameter for querying the incremental api endpoint.
Note: The Zendesk API expects UTC time. If a timezone aware datetime object is passed Zenpy will convert it to UTC, however if a naive object or unix timestamp is passed there is nothing Zenpy can do. It is recommended to always pass timezone aware objects to this endpoint.
- Parameters
start_time – unix timestamp or datetime object
include – list of items to sideload
ticket_metrics
(*args, **kwargs)¶
topics
(*args, **kwargs)¶