API Objects

The Zenpy API objects are automatically generated using the script gen_classes.py in the tools directory based on the specification found in the specification directory. The generated Python objects are a one to one mapping with the API, so any attribute returned by the API should be present in the Python object.

Instantiating Objects

When creating objects, any keyword argument can be passed to the constructor and it will become an attribute of that object. For example the code:

user = User(name='Jim', email='jim@jim.com')

Will create a User object with the name and email fields set.

Object Properties

Many attributes are implemented as properties. Any attribute that holds an id is also implemented as a property which returns the object associated with that id. For example, the Ticket object has two related attributes: assignee and assignee_id. When the assignee attribute is accessed, Zenpy first attempts to locate the related User in the User cache and if it cannot be found will generate and execute an API call to retrieve, instantiate, cache and return the object. Accessing the assignee_id attribute simply returns the id.

The following attributes are also implemented as properties:

Attribute Type Returns
dict object the dict represents
date string Python datetime object
list of id’s List of objects

It is important to note that most property setters throw away all information except for the id. This is because Zendesk only expects the id, so any modifications made to the object will not be persisted automatically. For example, the following Ticket:

ticket = Ticket(subject='stuffs', description='stuff stuff stuff')
user = User(id=10, name='Jim', email='jim@jim.com')
ticket.assignee = user

Will be serialized as:

{
    "description": "stuff stuff stuff",
    "assignee_id": 10,
    "subject": "stuffs"
}

Object Serialization

Before API objects are sent to Zendesk (eg for creation/updates), they are serialized into JSON once again. This is done recursively and any nested objects will be serialized as well. One handy side effect of how this is done is it is possible to set any arbitrary attribute on an API object and it will be serialized and sent to Zendesk. For example the object:

user = User(name='Jim', email='jim@jim.com')
user.some_thing = 100

Will be serialized as:

{
    "email": "jim@jim.com",
    "some_thing": 100,
    "name": "Jim"
}

A more useful example might be adding a comment to a ticket. Usually the Ticket object does not have a comment attribute, however if we add one it will be correctly serialized, sent to Zendesk and added to the specified ticket. For example, after adding the comment attribute containing a Comment object:

ticket.comment = Comment(body="I am a private comment", public=False)

the serialized ticket will include the additional information:

{
  "description": "I am a test ticket",
  "subject": "Testing",

  ...snip...
  "comment": {
    "public": false,
    "body": "I am a private comment"
  }
}

Api Object Modifications

When updating an object, only the id and those attributes that have been modified will be sent to Zendesk. For example, the following code will only print the user’s id.

user = zenpy_client.users.me()
print(user.to_dict(serialize=True))

Whereas the following will also include the name attribute, as it has been modified:

user = zenpy_client.users.me()
user.name = "Batman"
print(user.to_dict(serialize=True))

This is also true of attributes of objects that are lists or dicts, however the implementation might lead to some surprises. Consider the following:

ticket = zenpy_client.tickets(id=1)
ticket.custom_fields[0]['value'] = 'I am modified'
print(ticket.to_dict(serialize=True))

Here we modify the first element of the custom_fields list. How can Zenpy know that this has happened? The answer is proxy objects:

print(type(ticket.custom_fields))
>> <class 'zenpy.lib.proxy.ProxyList'>

print(type(ticket.custom_fields[0]))
>> <class 'zenpy.lib.proxy.ProxyDict'>

The way this works is when an element is retrieved from a list, it checks whether or not it is a list or dict. If it is, then the list or dict is wrapped in a Proxy class which executes a callback on modification so that the parent knows it has been modified. As a result, we can detect changes to lists or dicts and properly update Zendesk when they occur.

Api Object Reference

class zenpy.lib.api_objects.Activity(api=None, actor=None, created_at=None, id=None, title=None, updated_at=None, url=None, user=None, verb=None, **kwargs)[source]
created
updated
class zenpy.lib.api_objects.AgentMacroReference(api=None, id=None, macro_id=None, macro_title=None, type=None, via=None, **kwargs)[source]
macro
class zenpy.lib.api_objects.Attachment(api=None, content_type=None, content_url=None, file_name=None, id=None, size=None, thumbnails=None, **kwargs)[source]
class zenpy.lib.api_objects.Audit(api=None, author_id=None, created_at=None, events=None, id=None, metadata=None, ticket_id=None, via=None, **kwargs)[source]
author
created
ticket
class zenpy.lib.api_objects.Automation(api=None, actions=None, active=None, conditions=None, created_at=None, id=None, position=None, raw_title=None, title=None, updated_at=None, url=None, **kwargs)[source]
created
Comment: The time the automation was created
updated
Comment: The time of the last update of the automation
class zenpy.lib.api_objects.BaseObject[source]

Base for all Zenpy objects. Keeps track of which attributes have been modified.

to_dict(serialize=False)[source]

This method works by copying self.__dict__, and removing everything that should not be serialized.

to_json(indent=2)[source]

Return self formatted as JSON.

class zenpy.lib.api_objects.Brand(api=None, active=None, brand_url=None, created_at=None, default=None, has_help_center=None, help_center_state=None, host_mapping=None, id=None, logo=None, name=None, subdomain=None, updated_at=None, url=None, **kwargs)[source]
created
Comment: The time the brand was created
updated
Comment: The time of the last update of the brand
class zenpy.lib.api_objects.CcEvent(api=None, id=None, recipients=None, type=None, via=None, **kwargs)[source]
class zenpy.lib.api_objects.ChangeEvent(api=None, field_name=None, id=None, previous_value=None, type=None, value=None, **kwargs)[source]
class zenpy.lib.api_objects.Comment(api=None, attachments=None, author_id=None, body=None, created_at=None, id=None, metadata=None, public=None, type=None, via=None, **kwargs)[source]
author
created
class zenpy.lib.api_objects.CommentPrivacyChangeEvent(api=None, comment_id=None, id=None, public=None, type=None, **kwargs)[source]
comment
class zenpy.lib.api_objects.Conditions(api=None, all=None, any=None, **kwargs)[source]
class zenpy.lib.api_objects.CreateEvent(api=None, field_name=None, id=None, type=None, value=None, **kwargs)[source]
class zenpy.lib.api_objects.CustomField(api=None, id=None, value=None, **kwargs)[source]
class zenpy.lib.api_objects.CustomFieldOption(api=None, id=None, name=None, position=None, raw_name=None, url=None, value=None, **kwargs)[source]
class zenpy.lib.api_objects.Definitions(api=None, all=None, any=None, **kwargs)[source]
class zenpy.lib.api_objects.ErrorEvent(api=None, id=None, message=None, type=None, **kwargs)[source]
class zenpy.lib.api_objects.Export(api=None, status=None, view_id=None, **kwargs)[source]
view
class zenpy.lib.api_objects.ExternalEvent(api=None, body=None, id=None, resource=None, type=None, **kwargs)[source]
class zenpy.lib.api_objects.FacebookCommentEvent(api=None, attachments=None, author_id=None, body=None, data=None, graph_object_id=None, html_body=None, id=None, public=None, trusted=None, type=None, **kwargs)[source]
author
class zenpy.lib.api_objects.FacebookEvent(api=None, body=None, communication=None, id=None, page=None, ticket_via=None, type=None, **kwargs)[source]
class zenpy.lib.api_objects.Group(api=None, created_at=None, deleted=None, id=None, name=None, updated_at=None, url=None, **kwargs)[source]
created
Comment: The time the group was created
updated
Comment: The time of the last update of the group
class zenpy.lib.api_objects.GroupMembership(api=None, created_at=None, default=None, group_id=None, id=None, updated_at=None, url=None, user_id=None, **kwargs)[source]
created
Comment: The time the membership was created
group
Comment: The id of a group
updated
Comment: The time of the last update of the membership
user
Comment: The id of an agent
class zenpy.lib.api_objects.Identity(api=None, created_at=None, deliverable_state=None, id=None, primary=None, type=None, undeliverable_count=None, updated_at=None, url=None, user_id=None, value=None, verified=None, **kwargs)[source]
created
updated
user
class zenpy.lib.api_objects.Item(api=None, created_at=None, default_locale_id=None, id=None, name=None, outdated=None, placeholder=None, updated_at=None, url=None, variants=None, **kwargs)[source]
created
default_locale
updated
class zenpy.lib.api_objects.JobStatus(api=None, id=None, message=None, progress=None, results=None, status=None, total=None, url=None, **kwargs)[source]
class zenpy.lib.api_objects.JobStatusResult(api=None, action=None, errors=None, id=None, status=None, success=None, title=None, **kwargs)[source]
created
ticket
updated
class zenpy.lib.api_objects.Locale(api=None, created_at=None, default=None, id=None, locale=None, name=None, native_name=None, presentation_name=None, rtl=None, updated_at=None, url=None, **kwargs)[source]
created
updated
class zenpy.lib.api_objects.LogmeinTranscriptEvent(api=None, body=None, id=None, type=None, **kwargs)[source]
class zenpy.lib.api_objects.Macro(api=None, actions=None, active=None, created_at=None, description=None, id=None, position=None, restriction=None, title=None, updated_at=None, url=None, **kwargs)[source]
created
Comment: The time the macro was created
updated
Comment: The time of the last update of the macro
class zenpy.lib.api_objects.MacroResult(api=None, ticket=None, **kwargs)[source]
class zenpy.lib.api_objects.Metadata(api=None, custom=None, system=None, **kwargs)[source]
class zenpy.lib.api_objects.NotificationEvent(api=None, body=None, id=None, recipients=None, subject=None, type=None, via=None, **kwargs)[source]
class zenpy.lib.api_objects.Organization(api=None, created_at=None, details=None, domain_names=None, external_id=None, group_id=None, id=None, name=None, notes=None, organization_fields=None, shared_comments=None, shared_tickets=None, tags=None, updated_at=None, url=None, **kwargs)[source]
created
Comment: The time the organization was created
group
Comment: New tickets from users in this organization are automatically put in this group
updated
Comment: The time of the last update of the organization
class zenpy.lib.api_objects.OrganizationActivityEvent(api=None, body=None, id=None, recipients=None, subject=None, type=None, via=None, **kwargs)[source]
class zenpy.lib.api_objects.OrganizationField(api=None, active=None, created_at=None, description=None, id=None, key=None, position=None, raw_description=None, raw_title=None, regexp_for_validation=None, title=None, type=None, updated_at=None, url=None, **kwargs)[source]
created
Comment: The time the ticket field was created
updated
Comment: The time of the last update of the ticket field
class zenpy.lib.api_objects.OrganizationMembership(api=None, created_at=None, default=None, id=None, organization_id=None, updated_at=None, url=None, user_id=None, **kwargs)[source]
created
Comment: When this record was created
organization
Comment: The ID of the organization associated with this user, in this membership
updated
Comment: When this record last got updated
user
Comment: The ID of the user for whom this memberships belongs
class zenpy.lib.api_objects.PolicyMetric(api=None, business_hours=None, metric=None, priority=None, target=None, **kwargs)[source]
class zenpy.lib.api_objects.PushEvent(api=None, id=None, type=None, value=None, value_reference=None, **kwargs)[source]
class zenpy.lib.api_objects.Recipient(api=None, created_at=None, delivered_at=None, delivery_id=None, id=None, survey_id=None, survey_name=None, updated_at=None, user_email=None, user_id=None, user_name=None, **kwargs)[source]
created
delivered
delivery
survey
updated
user
class zenpy.lib.api_objects.RecipientAddress(api=None, brand_id=None, created_at=None, default=None, email=None, forwarding_status=None, id=None, name=None, spf_status=None, updated_at=None, **kwargs)[source]
brand
created
updated
class zenpy.lib.api_objects.Request(api=None, assignee_id=None, can_be_solved_by_me=None, collaborator_ids=None, created_at=None, custom_fields=None, description=None, due_at=None, fields=None, id=None, organization_id=None, priority=None, requester_id=None, status=None, subject=None, type=None, updated_at=None, url=None, via=None, **kwargs)[source]
assignee
Comment: The id of the assignee if the field is visible to end users
collaborators
Comment: Who are currently CC’ed on the ticket
created
Comment: When this record was created
due
Comment: When the task is due (only applies if the request is of type “task”)
organization
Comment: The organization of the requester
requester
Comment: The id of the requester
updated
Comment: When this record last got updated
class zenpy.lib.api_objects.Response(api=None, comment=None, delivered_at=None, delivery_id=None, id=None, rated_at=None, rating=None, recipient_id=None, survey_id=None, survey_name=None, user_email=None, user_id=None, user_name=None, **kwargs)[source]
delivered
delivery
rated
recipient
survey
user
class zenpy.lib.api_objects.SatisfactionRating(api=None, assignee_id=None, created_at=None, group_id=None, id=None, requester_id=None, score=None, ticket_id=None, updated_at=None, url=None, **kwargs)[source]
assignee
Comment: The id of agent assigned to at the time of rating
created
Comment: The time the satisfaction rating got created
group
Comment: The id of group assigned to at the time of rating
requester
Comment: The id of ticket requester submitting the rating
ticket
Comment: The id of ticket being rated
updated
Comment: The time the satisfaction rating got updated
class zenpy.lib.api_objects.SatisfactionRatingEvent(api=None, assignee_id=None, body=None, id=None, score=None, type=None, **kwargs)[source]
assignee
class zenpy.lib.api_objects.SharingAgreement(api=None, created_at=None, id=None, name=None, partner_name=None, remote_subdomain=None, status=None, type=None, **kwargs)[source]
created
Comment: The time the record was created
class zenpy.lib.api_objects.Skip(api=None, created_at=None, id=None, reason=None, ticket=None, ticket_id=None, updated_at=None, user_id=None, **kwargs)[source]
created
updated
user
class zenpy.lib.api_objects.SlaPolicy(api=None, created_at=None, description=None, filter=None, id=None, policy_metrics=None, position=None, title=None, updated_at=None, url=None, **kwargs)[source]
created
updated
class zenpy.lib.api_objects.Source(api=None, from_=None, rel=None, to=None, **kwargs)[source]
class zenpy.lib.api_objects.Status(api=None, action=None, errors=None, id=None, status=None, success=None, title=None, **kwargs)[source]
class zenpy.lib.api_objects.SuspendedTicket(api=None, author=None, brand_id=None, cause=None, content=None, created_at=None, id=None, recipient=None, subject=None, ticket_id=None, updated_at=None, url=None, via=None, **kwargs)[source]
brand
Comment: The id of the brand this ticket is associated with - only applicable for enterprise accounts
created
Comment: When this record was created
ticket
Comment: The ticket ID this suspended email is associated with, if available
updated
Comment: When this record last got updated
class zenpy.lib.api_objects.System(api=None, client=None, ip_address=None, latitude=None, location=None, longitude=None, **kwargs)[source]
class zenpy.lib.api_objects.Tag(api=None, count=None, name=None, **kwargs)[source]
class zenpy.lib.api_objects.Target(api=None, active=None, content_type=None, created_at=None, id=None, method=None, password=None, target_url=None, title=None, type=None, url=None, username=None, **kwargs)[source]
created
Comment: The time the target was created
class zenpy.lib.api_objects.Thumbnail(api=None, content_type=None, content_url=None, file_name=None, id=None, size=None, **kwargs)[source]
class zenpy.lib.api_objects.Ticket(api=None, assignee_id=None, brand_id=None, collaborator_ids=None, created_at=None, custom_fields=None, description=None, due_at=None, external_id=None, fields=None, forum_topic_id=None, group_id=None, has_incidents=None, id=None, organization_id=None, priority=None, problem_id=None, raw_subject=None, recipient=None, requester_id=None, satisfaction_rating=None, sharing_agreement_ids=None, status=None, subject=None, submitter_id=None, tags=None, type=None, updated_at=None, url=None, via=None, **kwargs)[source]
assignee
Comment: The agent currently assigned to the ticket
brand
Comment: Enterprise only. The id of the brand this ticket is associated with
collaborators
Comment: The ids of users currently cc’ed on the ticket
created
Comment: When this record was created
due
Comment: If this is a ticket of type “task” it has a due date. Due date format uses ISO 8601 format.
forum_topic
Comment: The topic this ticket originated from, if any
group
Comment: The group this ticket is assigned to
organization
Comment: The organization of the requester. You can only specify the ID of an organization associated with the requester. See Organization Memberships
problem
Comment: For tickets of type “incident”, the ID of the problem the incident is linked to
requester
Comment: The user who requested this ticket
sharing_agreements
Comment: The ids of the sharing agreements used for this ticket
submitter
Comment: The user who submitted the ticket. The submitter always becomes the author of the first comment on the ticket
updated
Comment: When this record last got updated
class zenpy.lib.api_objects.TicketAudit(api=None, audit=None, ticket=None, **kwargs)[source]
class zenpy.lib.api_objects.TicketEvent(api=None, child_events=None, id=None, ticket_id=None, updater_id=None, via=None, **kwargs)[source]
ticket
timestamp
updater
class zenpy.lib.api_objects.TicketField(api=None, active=None, collapsed_for_agents=None, created_at=None, description=None, editable_in_portal=None, id=None, position=None, raw_description=None, raw_title=None, raw_title_in_portal=None, regexp_for_validation=None, required=None, required_in_portal=None, tag=None, title=None, title_in_portal=None, type=None, updated_at=None, url=None, visible_in_portal=None, **kwargs)[source]
created
Comment: The time the ticket field was created
updated
Comment: The time of the last update of the ticket field
class zenpy.lib.api_objects.TicketForm(api=None, active=None, created_at=None, default=None, display_name=None, end_user_visible=None, id=None, in_all_brands=None, in_all_organizations=None, name=None, position=None, raw_display_name=None, raw_name=None, restricted_brand_ids=None, restricted_organization_ids=None, ticket_field_ids=None, updated_at=None, url=None, **kwargs)[source]
created
restricted_brands
Comment: ids of all brands that this ticket form is restricted to
restricted_organizations
ticket_fields
Comment: ids of all ticket fields which are in this ticket form
updated
class zenpy.lib.api_objects.TicketMetric(api=None, agent_wait_time_in_minutes=None, assigned_at=None, assignee_stations=None, assignee_updated_at=None, created_at=None, first_resolution_time_in_minutes=None, full_resolution_time_in_minutes=None, group_stations=None, id=None, initially_assigned_at=None, latest_comment_added_at=None, on_hold_time_in_minutes=None, reopens=None, replies=None, reply_time_in_minutes=None, requester_updated_at=None, requester_wait_time_in_minutes=None, solved_at=None, status_updated_at=None, ticket_id=None, updated_at=None, **kwargs)[source]
assigned
Comment: When the ticket was last assigned
assignee_updated
Comment: When the assignee last updated the ticket
created
Comment: When this record was created
initially_assigned
Comment: When the ticket was initially assigned
latest_comment_added
Comment: When the latest comment was added
requester_updated
Comment: When the requester last updated the ticket
solved
Comment: When the ticket was solved
status_updated
Comment: When the status was last updated
ticket
Comment: Id of the associated ticket
updated
Comment: When this record last got updated
class zenpy.lib.api_objects.TicketMetricEvent(api=None, deleted=None, id=None, instance_id=None, metric=None, sla=None, status=None, ticket_id=None, time=None, type=None, **kwargs)[source]
ticket
Comment: Id of the associated ticket
class zenpy.lib.api_objects.TicketMetricItem(api=None, business=None, calendar=None, **kwargs)[source]
class zenpy.lib.api_objects.TicketSharingEvent(api=None, action=None, agreement_id=None, id=None, type=None, **kwargs)[source]
class zenpy.lib.api_objects.Topic(api=None, body=None, created_at=None, forum_id=None, id=None, locked=None, pinned=None, position=None, search_phrases=None, submitter_id=None, tags=None, title=None, topic_type=None, updated_at=None, updater_id=None, url=None, **kwargs)[source]
created
forum
submitter
updated
updater
class zenpy.lib.api_objects.Trigger(api=None, actions=None, active=None, conditions=None, description=None, id=None, position=None, title=None, **kwargs)[source]
class zenpy.lib.api_objects.TweetEvent(api=None, body=None, direct_message=None, id=None, recipients=None, type=None, **kwargs)[source]
class zenpy.lib.api_objects.Upload(api=None, attachment=None, attachments=None, expires_at=None, token=None, **kwargs)[source]
expires
class zenpy.lib.api_objects.User(api=None, active=None, alias=None, chat_only=None, created_at=None, custom_role_id=None, details=None, email=None, external_id=None, id=None, last_login_at=None, locale=None, locale_id=None, moderator=None, name=None, notes=None, only_private_comments=None, organization_id=None, phone=None, photo=None, restricted_agent=None, role=None, shared=None, shared_agent=None, signature=None, suspended=None, tags=None, ticket_restriction=None, time_zone=None, two_factor_auth_enabled=None, updated_at=None, url=None, user_fields=None, verified=None, **kwargs)[source]
created
Comment: The time the user was created
custom_role
Comment: A custom role if the user is an agent on the Enterprise plan
last_login
Comment: The last time the user signed in to Zendesk Support
organization
Comment: The id of the organization the user is associated with
updated
Comment: The time the user was last updated
class zenpy.lib.api_objects.UserField(api=None, active=None, created_at=None, description=None, id=None, key=None, position=None, raw_description=None, raw_title=None, regexp_for_validation=None, title=None, type=None, updated_at=None, url=None, **kwargs)[source]
created
Comment: The time the ticket field was created
updated
Comment: The time of the last update of the ticket field
class zenpy.lib.api_objects.UserRelated(api=None, assigned_tickets=None, ccd_tickets=None, entry_subscriptions=None, forum_subscriptions=None, organization_subscriptions=None, requested_tickets=None, subscriptions=None, topic_comments=None, topics=None, votes=None, **kwargs)[source]
class zenpy.lib.api_objects.Variant(api=None, active=None, content=None, created_at=None, default=None, id=None, locale_id=None, outdated=None, updated_at=None, url=None, **kwargs)[source]
created
updated
class zenpy.lib.api_objects.Via(api=None, source=None, **kwargs)[source]
class zenpy.lib.api_objects.View(api=None, active=None, conditions=None, created_at=None, execution=None, id=None, position=None, raw_title=None, restriction=None, sla_id=None, title=None, updated_at=None, url=None, **kwargs)[source]
created
Comment: The time the view was created
sla
updated
Comment: The time of the last update of the view
class zenpy.lib.api_objects.ViewCount(api=None, channel=None, fresh=None, poll_wait=None, pretty=None, refresh=None, url=None, value=None, view_id=None, **kwargs)[source]
view
class zenpy.lib.api_objects.ViewRow(api=None, created=None, custom_fields=None, fields=None, group_id=None, priority=None, requester_id=None, score=None, subject=None, ticket=None, **kwargs)[source]
group
requester
class zenpy.lib.api_objects.VoiceCommentEvent(api=None, attachments=None, author_id=None, body=None, data=None, formatted_from=None, formatted_to=None, html_body=None, id=None, public=None, transcription_visible=None, trusted=None, type=None, **kwargs)[source]
author