Groupmemberships 1 endpoints

PUT /api/v2/users/{user_id}/group_memberships/{group_membership_id}/make_default Set Membership as Default

Allowed For:

Agents

operationId: GroupMemberships_setAsDefault

Parameters

Name	In	Required	Type	Description
user_id	path	optional	integer	The id of the user
group_membership_id	path	optional	integer	The ID of the group membership

Responses

200

Success response

PUT /api/v2/users/{user_id}/group_memberships/{group_membership_id}/make_default

Groupslapolicies 7 endpoints

GET /api/v2/group_slas/policies List Group SLA Policies

Allowed For

Admins

operationId: GroupSlaPolicies_list

Responses

200

Success response

GET /api/v2/group_slas/policies

POST /api/v2/group_slas/policies Create Group SLA Policy

Allowed For

Admins

operationId: GroupSlaPolicies_createNewPolicy

Responses

201

Created response

POST /api/v2/group_slas/policies

GET /api/v2/group_slas/policies/definitions Retrieve Supported Filter Definition Items

Allowed For

Admins

operationId: GroupSlaPolicies_getSupportedFilterDefinitionItems

Responses

200

Success response

GET /api/v2/group_slas/policies/definitions

PUT /api/v2/group_slas/policies/reorder Reorder Group SLA Policies

Allowed For

Admins

operationId: GroupSlaPolicies_reorder

Parameters

Name	In	Required	Type	Description
group_sla_policy_ids	query	optional	array	The ids of the Group SLA policies to reorder

Responses

200

Success response

PUT /api/v2/group_slas/policies/reorder

DELETE /api/v2/group_slas/policies/{group_sla_policy_id} Delete Group SLA Policy

Allowed For

Admins

operationId: GroupSlaPolicies_deletePolicy

Parameters

Name	In	Required	Type	Description
group_sla_policy_id	path	optional	integer	The id of the Group SLA policy

Responses

204

No Content response

DELETE /api/v2/group_slas/policies/{group_sla_policy_id}

GET /api/v2/group_slas/policies/{group_sla_policy_id} Show Group SLA Policy

Allowed For

Admins

operationId: GroupSlaPolicies_showPolicy

Parameters

Name	In	Required	Type	Description
group_sla_policy_id	path	optional	integer	The id of the Group SLA policy

Responses

200

Success response

GET /api/v2/group_slas/policies/{group_sla_policy_id}

PUT /api/v2/group_slas/policies/{group_sla_policy_id} Update Group SLA Policy

Updates the specified policy.

Allowed For

Admins

operationId: GroupSlaPolicies_updatePolicy

Parameters

Name	In	Required	Type	Description
group_sla_policy_id	path	optional	integer	The id of the Group SLA policy

Responses

200

Success response

PUT /api/v2/group_slas/policies/{group_sla_policy_id}

Groups 7 endpoints

GET /api/v2/groups List Groups

Pagination

Cursor pagination (recommended)
Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

Admins
Agents

operationId: Groups_list

Parameters

Name	In	Required	Type	Description
user_id	path	optional	integer	The id of the user
exclude_deleted	query	optional	boolean	Whether to exclude deleted entities

Responses

200

Success response

GET /api/v2/groups

POST /api/v2/groups Create Group

Allowed For

Admins
Agents assigned to a custom role with permissions to manage groups (Enterprise only)

operationId: Groups_createNewGroup

Responses

201

Created response

POST /api/v2/groups

GET /api/v2/groups/assignable List Assignable Groups

Pagination

Cursor pagination (recommended)
Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

Admins
Agents

operationId: Groups_listAssignableGroups

Responses

200

Success response

GET /api/v2/groups/assignable

GET /api/v2/groups/count Count Groups

Returns an approximate count of groups. If the count exceeds 100,000, it is updated every 24 hours.

The refreshed_at property of the count object is a timestamp that indicates when the count was last updated.

Note: When the count exceeds 100,000, refreshed_at may occasionally be null. This indicates that the count is being updated in the background, and the value property of the count object is limited to 100,000 until the update is complete.

Allowed For

Admins
Agents

operationId: Groups_getCount

Parameters

Name	In	Required	Type	Description
user_id	path	optional	integer	The id of the user

Responses

200

Success response

GET /api/v2/groups/count

DELETE /api/v2/groups/{group_id} Delete Group

Allowed For

Admins
Agents assigned to a custom role with permissions to manage groups (Enterprise only)

operationId: Groups_deleteGroup

Parameters

Name	In	Required	Type	Description
group_id	path	optional	integer	The ID of the group

Responses

204

No content response

DELETE /api/v2/groups/{group_id}

GET /api/v2/groups/{group_id} Show Group

Allowed For

Admins
Agents

operationId: Groups_showGroup

Parameters

Name	In	Required	Type	Description
group_id	path	optional	integer	The ID of the group

Responses

200

Success response

GET /api/v2/groups/{group_id}

PUT /api/v2/groups/{group_id} Update Group

Allowed For

Admins

operationId: Groups_updateGroup

Parameters

Name	In	Required	Type	Description
group_id	path	optional	integer	The ID of the group

Responses

200

Success response

PUT /api/v2/groups/{group_id}

Incrementalexport 7 endpoints

GET /api/v2/incremental/organizations Incremental Organization Export

Allowed For

Admins

Sideloading

See Organizations sideloads.

operationId: IncrementalExport_organizationsGet

Parameters

Name	In	Required	Type	Description
start_time	query	optional	integer	The time to start the incremental export from. Must be at least one minute in the past. Data isn’t provided for the most recent minute

Responses

200

Success response

GET /api/v2/incremental/organizations

GET /api/v2/incremental/ticket_events Incremental Ticket Event Export

Returns a stream of changes that occurred on tickets. Each event is tied
to an update on a ticket and contains all the fields that were updated in that
change. For more information, see:

You can include comments in the event stream by using the comment_events
sideload. See Sideloading below. If you don’t specify the sideload, any comment
present in the ticket update is described only by Boolean comment_present
and comment_public object properties in the event’s child_events array.
The comment itself is not included.

Allowed For

Admins

Sideloading

The endpoint supports the comment_events sideload. Any comment present in the ticket
update is listed as an object in the event’s child_events array. Example:

"child_events": [
  {
    "id": 91048994488,
    "via": {
      "channel": "api",
      "source": {"from":{},"to":{},"rel":null}},
    "via_reference_id":null,
    "type": "Comment",
    "author_id": 5031726587,
    "body": "This is a comment",
    "html_body": "&lt;div class="zd-comment"&gt;&lt;p dir="auto"&gt;This is a comment&lt;/p&gt;",
    "public": true,
    "attachments": [],
    "audit_id": 91048994468,
    "created_at": "2009-06-25T10:15:18Z",
    "event_type": "Comment"
  },
  ...
],
...

operationId: IncrementalExport_ticketEventsGetStream

Parameters

Name	In	Required	Type	Description
start_time	query	optional	integer	The time to start the incremental export from. Must be at least one minute in the past. Data isn’t provided for the most recent minute

Responses

200

Success response

GET /api/v2/incremental/ticket_events

GET /api/v2/incremental/tickets Incremental Ticket Export, Time Based

Returns the tickets that changed since the start time. For more information,
see Exporting tickets in Using the Incremental Exports API.

This endpoint supports time-based incremental exports.
For more information, see Time-based incremental exports in Using the Incremental Exports API. You can also return tickets using cursor-based pagination. See Incremental Ticket Export, Cursor Based.

The results include tickets that were updated by the system. See
Excluding system-updated tickets in Using the Incremental Exports API.

The endpoint can return tickets with an updated_at time that’s earlier than the
start_time time. The reason is that the API compares the start_time with the ticket’s
generated_timestamp value, not its updated_at value. The updated_at value is
updated only if the update generates a ticket event.
The generated_timestamp value is updated for all ticket updates, including system
updates. If a system update occurs after a ticket event, the unchanged
updated_at time will become earlier relative to the updated generated_timestamp
time.

Allowed For

Admins

Sideloading

See Tickets sideloads. For performance reasons,
last_audits sideloads aren’t supported.

operationId: IncrementalExport_timeBasedTickets

Parameters

Name	In	Required	Type	Description
start_time	query	optional	integer	The time to start the incremental export from. Must be at least one minute in the past. Data isn’t provided for the most recent minute

Responses

200

Success response

GET /api/v2/incremental/tickets

GET /api/v2/incremental/tickets/cursor Incremental Ticket Export, Cursor Based

Returns the tickets that changed since the start time. For more information,
see Exporting tickets in Using the Incremental Exports API.

This endpoint supports cursor-based incremental exports.
Cursor-based exports are highly encouraged because they provide more consistent performance and
response body sizes. For more information, see Cursor-based incremental exports in Using the Incremental Exports API.

Allowed For

Admins

Sideloading

See Tickets sideloads. For performance reasons,
last_audits sideloads aren’t supported.

operationId: IncrementalExport_ticketsChangedSinceStart

Parameters

Name	In	Required	Type	Description
start_time	query	optional	integer	The time to start the incremental export from. Must be at least one minute in the past. Data isn’t provided for the most recent minute
cursor	query	optional	string	The cursor pointer to work with for all subsequent exports after the initial request

Responses

200

Success response

GET /api/v2/incremental/tickets/cursor

GET /api/v2/incremental/users Incremental User Export, Time Based

Allowed For

Admins

Sideloading

See Users sideloads.

operationId: IncrementalExport_userExportTimeBased

Parameters

Name	In	Required	Type	Description
start_time	query	optional	integer	The time to start the incremental export from. Must be at least one minute in the past. Data isn’t provided for the most recent minute
per_page	query	optional	integer	The number of records to return per page

Responses

200

Success response

GET /api/v2/incremental/users

GET /api/v2/incremental/users/cursor Incremental User Export, Cursor Based

Allowed For

Admins

Sideloading

See Users sideloads.

operationId: IncrementalExport_userCursorGet

Parameters

Name	In	Required	Type	Description
start_time	query	optional	integer	The time to start the incremental export from. Must be at least one minute in the past. Data isn’t provided for the most recent minute
cursor	query	optional	string	The cursor pointer to work with for all subsequent exports after the initial request
per_page	query	optional	integer	The number of records to return per page

Responses

200

Success response

GET /api/v2/incremental/users/cursor

GET /api/v2/incremental/{incremental_resource}/sample Incremental Sample Export

Use this endpoint to test the incremental export format. It’s more strict in terms of rate limiting,
at 10 requests per 20 minutes instead of 10 requests per minute. It also returns only up to 50
results per request. Otherwise, it’s identical to the above APIs.

Use the incremental_resource parameter to specify the resource. Possible values are “tickets”, “ticket_events”, “users”, or “organizations”.

operationId: IncrementalExport_sampleGet

Parameters

Name	In	Required	Type	Description
start_time	query	optional	integer	The time to start the incremental export from. Must be at least one minute in the past. Data isn’t provided for the most recent minute
incremental_resource	path	optional	string	The resource requested for incremental sample export

Responses

200

Success response

GET /api/v2/incremental/{incremental_resource}/sample

Incrementalskillbasedrouting 3 endpoints

GET /api/v2/incremental/routing/attribute_values Incremental Attributes Values Export

Returns a stream of changes that occurred on routing attribute values.

Allowed For

Admins

Parameters

Optional

Name	Type	Comment
cursor	string	The `cursor` parameter is a non-human-readable argument you can use to move forward or backward in time. The cursor is a read-only URL parameter that’s only available in API responses. See Pagination.

operationId: IncrementalSkillBasedRouting_getAttributeValues

Responses

200

Success response

GET /api/v2/incremental/routing/attribute_values

GET /api/v2/incremental/routing/attributes Incremental Attributes Export

Returns a stream of changes that occurred on routing attributes.

Allowed For

Admins

Parameters

Optional

Name	Type	Comment
cursor	string	The `cursor` parameter is a non-human-readable argument you can use to move forward or backward in time. The cursor is a read-only URL parameter that’s only available in API responses. See Pagination.

operationId: IncrementalSkillBasedRouting_exportChanges

Responses

200

Success response

GET /api/v2/incremental/routing/attributes

GET /api/v2/incremental/routing/instance_values Incremental Instance Values Export

Returns a stream of changes that occurred on routing instance values. Changes are grouped by attribute_value_id,
with unassociate type events listed with associate type events by the associate event’s timestamp.

Allowed For

Admins

Parameters

Optional

Name	Type	Comment
cursor	string	The `cursor` parameter is a non-human-readable argument you can use to move forward or backward in time. The cursor is a read-only URL parameter that’s only available in API responses. See Pagination.

operationId: IncrementalSkillBasedRouting_routingInstanceValuesGet

Responses

200

Success response

GET /api/v2/incremental/routing/instance_values

Jobstatuses 3 endpoints

GET /api/v2/job_statuses List Job Statuses

Shows the statuses for background jobs. Statuses are sorted first by completion date and then by creation date in descending order.

Allowed For:

Agents

Pagination

Cursor pagination

See Pagination.

operationId: JobStatuses_list

Responses

200

Success Response

GET /api/v2/job_statuses

GET /api/v2/job_statuses/show_many Show Many Job Statuses

Accepts a comma-separated list of job status ids.

Allowed For:

Agents

operationId: JobStatuses_getMany

Parameters

Name	In	Required	Type	Description
ids	query	required	string	Comma-separated list of job status ids.

Responses

200

Success Response

GET /api/v2/job_statuses/show_many

GET /api/v2/job_statuses/{job_status_id} Show Job Status

Shows the status of a background job.

Allowed For:

Agents

operationId: JobStatuses_showStatus

Parameters

Name	In	Required	Type	Description
job_status_id	path	optional	string	the Id of the Job status

Responses

200

Success Response

GET /api/v2/job_statuses/{job_status_id}

Locales 6 endpoints

GET /api/v2/locales List Locales

Lists the translation locales available for the account.

Note: You can alter the list by passing an updated locale_ids array to the Update Account Settings endpoint.

Allowed For

Anyone

operationId: Locales_listAvailable

Responses

200

Success response

GET /api/v2/locales

GET /api/v2/locales/agent List Locales for Agent

Lists the translation locales that have been localized for agents on a specific account.

Allowed For

Anyone

operationId: Locales_listForAgent

Responses

200

Success response

GET /api/v2/locales/agent

GET /api/v2/locales/current Show Current Locale

This works like Show Locale, but instead of taking a locale id as an argument, it renders the locale of the user performing the request.

Allowed For

Anyone

operationId: Locales_getCurrentLocale

Responses

200

Success response

GET /api/v2/locales/current

GET /api/v2/locales/detect_best_locale Detect Best Language for User

Allowed For

Anyone

operationId: Locales_detectBestLocale

Responses

200

Success response

GET /api/v2/locales/detect_best_locale

GET /api/v2/locales/public List Available Public Locales

Lists the translation locales that are available to all accounts.

Allowed For

Anyone

operationId: Locales_listPublicAvailable

Responses

200

Success response

GET /api/v2/locales/public

GET /api/v2/locales/{locale_id} Show Locale

Allowed For

Anyone

operationId: Locales_showLocale

Parameters

Name	In	Required	Type	Description
locale_id	path	optional	string	The ID or the BCP-47 code of the locale. Examples: es-419, en-us, pr-br

Responses

200

Success Response

GET /api/v2/locales/{locale_id}

Lookuprelationships 2 endpoints

GET /api/v2/relationships/definitions/{target_type} Filter Definitions

Returns filter definitions based on the given target type. Target types
include users (zen:user), tickets (zen:ticket), organizations (zen:organization), or custom objects (zen:custom_object:CUSTOM_OBJECT_KEY).
The returned filter definitions are the options that you can use to build a custom field or ticket field’s
relationship_filter.

operationId: LookupRelationships_filterDefinitions

Parameters

Name	In	Required	Type	Description
target_type	path	required	string	The target type for which you would like to see filter definitions. The options are “zen:user”, “zen:ticket”, “zen:organization”, and “zen:custom_object:CUSTOM_OBJECT_KEY”
source_type	query	optional	string	The source type for which you would like to see filter definitions. The options are “zen:user”, “zen:ticket”, and “zen:organization”

Responses

200

Success response

GET /api/v2/relationships/definitions/{target_type}

GET /api/v2/{target_type}/{target_id}/relationship_fields/{field_id}/{source_type} Get sources by target

Returns a list of source objects whose values are populated with the id of a related target object. For example,
if you have a lookup field called “Success Manager” on a ticket, this endpoint can answer the question,
“What tickets (sources) is this user (found by target_type and target_id)
assigned as the ‘Success Manager’ (field referenced by field_id)?”

Allowed For

Agents

Pagination

Cursor pagination (recommended)
Offset pagination

See Pagination.

operationId: LookupRelationships_getSourcesByTarget

Parameters

Name	In	Required	Type	Description
target_type	path	required	string	The type of object the relationship field is targeting. The options are “zen:user”, “zen:ticket”, “zen:organization”, and “zen:custom_object:CUSTOM_OBJECT_KEY”
target_id	path	required	integer	The id of the object the relationship field is targeting
field_id	path	required	integer	The id of the lookup relationship field
source_type	path	required	string	The type of object the relationship field belongs to (example. ticket field belongs to a ticket object). The options are “zen:user”, “zen:ticket”, “zen:organization”, and “zen:custom_object:CUSTOM_OBJECT_KEY”

Responses

200

Success response

GET /api/v2/{target_type}/{target_id}/relationship_fields/{field_id}/{source_type}

Macros 14 endpoints

GET /api/v2/macros List Macros

Lists all shared and personal macros available to the current user. For admins, the API returns all macros for the account, including the personal macros of agents and other admins.

Pagination

Cursor pagination (recommended)
Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

Agents

operationId: Macros_list

Parameters

Name	In	Required	Type	Description
include	query	optional	string	A sideload to include in the response. See Sideloads
access	query	optional	string	Filter macros by access. Possible values are “personal”, “agents”, “shared”, or “account”. The “agents” value returns all personal macros for the account’s agents and is only available to admins.
active	query	optional	boolean	Filter by active macros if true or inactive macros if false
category	query	optional	integer	Filter macros by category
group_id	query	optional	integer	Filter macros by group
only_viewable	query	optional	boolean	If true, returns only macros that can be applied to tickets. If false, returns all macros the current user can manage. Default is false
sort_by	query	optional	string	Possible values are alphabetical, “created_at”, “updated_at”, “usage_1h”, “usage_24h”, “usage_7d”, or “usage_30d”. Defaults to alphabetical
sort_order	query	optional	string	One of “asc” or “desc”. Defaults to “asc” for alphabetical and position sort, “desc” for all others

Responses

200

Success Response

GET /api/v2/macros

POST /api/v2/macros Create Macro

Allowed For

Agents

operationId: Macros_createNewMacro

Request Body

application/json

schema MacrosCreateNewMacroRequest

Property	Type	Required
macro	object	optional
└ title	string	required
└ active	boolean	optional
└ actions	array	required
└ field	string	optional
└ value	string	optional
└ description	string	optional
└ restriction	object	optional
└ id	integer	optional
└ ids	array	optional
└ type	string	optional

Responses

200

POST /api/v2/macros

GET /api/v2/macros/actions List Supported Actions for Macros

Allowed For

Agents

operationId: Macros_listSupportedActions

Responses

200

Success Response

GET /api/v2/macros/actions

GET /api/v2/macros/active List Active Macros

Lists all active shared and personal macros available to the current user.

Allowed For

Agents

operationId: Macros_listActive

Parameters

Name	In	Required	Type	Description
include	query	optional	string	A sideload to include in the response. See Sideloads
access	query	optional	string	Filter macros by access. Possible values are “personal”, “agents”, “shared”, or “account”. The “agents” value returns all personal macros for the account’s agents and is only available to admins.
category	query	optional	integer	Filter macros by category
group_id	query	optional	integer	Filter macros by group
sort_by	query	optional	string	Possible values are alphabetical, “created_at”, “updated_at”, “usage_1h”, “usage_24h”, “usage_7d”, or “usage_30d”. Defaults to alphabetical
sort_order	query	optional	string	One of “asc” or “desc”. Defaults to “asc” for alphabetical and position sort, “desc” for all others

Responses

200

Success Response

GET /api/v2/macros/active

POST /api/v2/macros/attachments Create Unassociated Macro Attachment

Allows an attachment to be uploaded that can be associated with a macro at a later time.

Note: To ensure an uploaded attachment is not lost, associate it with a macro as soon as possible. From time to time, old attachments that are not not associated with any macro are purged.

Allowed For

Agents

operationId: Macros_createUnassociatedAttachment

Responses

201

Created Response

POST /api/v2/macros/attachments

GET /api/v2/macros/attachments/{attachment_id} Show Macro Attachment

Shows the properties of the specified macro attachment.

Allowed For

Agents

operationId: Macros_showAttachmentProperties

Parameters

Name	In	Required	Type	Description
attachment_id	path	optional	integer	The ID of the attachment

Responses

200

Success Response

GET /api/v2/macros/attachments/{attachment_id}

GET /api/v2/macros/categories List Macro Categories

Lists all macro categories available to the current user.

Allowed For

Agents

operationId: Macros_listCategories

Responses

200

Success Response

GET /api/v2/macros/categories

GET /api/v2/macros/definitions List Macro Action Definitions

Returns the definitions of the actions a macro can perform. For example,
one action can set the status of a ticket. The definition of the action
includes a title (“Status”), a type (“list”), and possible values. For a
list of support actions, see Actions reference.

Allowed For

Agents

operationId: Macros_listActionDefinitions

Responses

200

Success Response

GET /api/v2/macros/definitions

DELETE /api/v2/macros/destroy_many Bulk Delete Macros

Deletes the macros corresponding to the provided comma-separated list of IDs.

Allowed For

Agents

operationId: Macros_deleteMany

Parameters

Name	In	Required	Type	Description
ids	query	required	array	The IDs of the macros to delete

Responses

204

No Content

DELETE /api/v2/macros/destroy_many

GET /api/v2/macros/new Show Macro Replica

Returns an unpersisted macro representation derived from a ticket or macro.

The endpoint takes one of the following query parameters: macro_id or ticket_id. If you include both, macro_id is used.

Allowed For

Agents

operationId: Macros_showReplica

Parameters

Name	In	Required	Type	Description
macro_id	query	optional	integer	The ID of the macro to replicate
ticket_id	query	required	integer	The ID of the ticket from which to build a macro replica

Responses

200

Success Response

GET /api/v2/macros/new

GET /api/v2/macros/search Search Macros

Pagination

Offset pagination only

See Using Offset Pagination.

Allowed For

Agents

operationId: Macros_searchAgents

Parameters

Name	In	Required	Type	Description
include	query	optional	string	A sideload to include in the response. See Sideloads
access	query	optional	string	Filter macros by access. Possible values are “personal”, “agents”, “shared”, or “account”. The “agents” value returns all personal macros for the account’s agents and is only available to admins.
active	query	optional	boolean	Filter by active macros if true or inactive macros if false
category	query	optional	integer	Filter macros by category
group_id	query	optional	integer	Filter macros by group
only_viewable	query	optional	boolean	If true, returns only macros that can be applied to tickets. If false, returns all macros the current user can manage. Default is false
sort_by	query	optional	string	Possible values are alphabetical, “created_at”, “updated_at”, “usage_1h”, “usage_24h”, “usage_7d”, or “usage_30d”. Defaults to alphabetical
sort_order	query	optional	string	One of “asc” or “desc”. Defaults to “asc” for alphabetical and position sort, “desc” for all others
query	query	optional	string	Query string used to find macros with matching titles

Responses

200

Success Response

GET /api/v2/macros/search

PUT /api/v2/macros/update_many Update Many Macros

Updates the provided macros with the specified changes.

Allowed For

Agents

operationId: Macros_updateMany

Request Body

application/json

schema MacroUpdateManyInput

Property	Type	Required
macros	array	optional
└ id	integer	required
└ active	boolean	optional
└ position	integer	optional

Responses

200

Success Response

PUT /api/v2/macros/update_many

DELETE /api/v2/macros/{macro_id} Delete Macro

Allowed For

Agents, with restrictions applying on certain actions

operationId: Macros_deleteMacroById

Parameters

Name	In	Required	Type	Description
macro_id	path	optional	integer	The ID of the macro

Responses

204

No Content

DELETE /api/v2/macros/{macro_id}

GET /api/v2/macros/{macro_id} Show Macro

Allowed For

Agents

operationId: Macros_showMacro

Parameters

Name	In	Required	Type	Description
macro_id	path	optional	integer	The ID of the macro

Responses

200

Success Response

GET /api/v2/macros/{macro_id}