openapi: 3.0.3 info: title: Support API description: Zendesk Support API endpoints version: 2.0.0 tags: - name: Attachments - name: Sessions - name: Trigger Categories - name: Tags - name: Targets - name: Target Failures - name: Job Statuses - name: Automations - name: Tickets - name: Email Notifications - name: Lookup Relationships - name: Dynamic Content - name: Dynamic Content Item Variants - name: Push Notification Devices - name: Channel Framework - name: X Channel - name: Organizations - name: Triggers - name: Object Triggers - name: Custom Roles - name: Incremental Export - name: Account Settings - name: Ticket Metrics - name: Groups - name: Group Memberships - name: Incremental Skill Based Routing - name: Organization Memberships - name: Sharing Agreements - name: Search - name: Workspaces - name: Skill Based Routing - name: Resource Collections - name: Macros - name: Organization Subscriptions - name: Support Addresses - name: User Passwords - name: User Identities - name: Activity Stream - name: Group SLA Policies - name: SLA Policies - name: Ticket Audits - name: Ticket Metric Events - name: Conversation Log - name: Brands - name: Brand Agents - name: Users - name: Satisfaction Reasons - name: Ticket Forms - name: Ticket Form Statuses - name: Suspended Tickets - name: Satisfaction Ratings - name: Ticket Comments - name: Requests - name: Audit Logs - name: Views - name: Ticket Import - name: Organization Fields - name: User Fields - name: Ticket Fields - name: Ticket Skips - name: Bookmarks - name: Reseller - name: Basics - name: AssigneeFieldAssignableGroups - name: AssigneeFieldAssignableAgents - name: Custom Ticket Statuses - name: Locales - name: Custom Objects - name: Custom Object Fields - name: Custom Object Records - name: Essentials Card - name: Omnichannel Routing Queues - name: Deletion Schedules - name: OAuth Clients - name: OAuth Tokens - name: Grant Type Tokens - name: Global Clients - name: Approval Requests - name: Approval Workflow Instances servers: - url: https://{subdomain}.{domain}.com variables: domain: default: zendesk subdomain: default: example paths: /api/lotus/assignables/autocomplete.json: get: operationId: ListAssigneeFieldAssignableGroupsAndAgentsSearch tags: - AssigneeFieldAssignableGroups - AssigneeFieldAssignableAgents summary: List assignable groups and agents based on query matched against name description: | List assignable groups and agents based on query matched against name #### Allowed For * Agents parameters: - $ref: "#/components/parameters/AssigneeFieldSearchValue" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/AssigneeFieldAssignableGroupsAndAgentsSearchResponse" /api/lotus/assignables/groups.json: get: operationId: ListAssigneeFieldAssignableGroups tags: - AssigneeFieldAssignableAgents summary: List assignable groups on the AssigneeField description: | List assignable groups on the AssigneeField #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/AssigneeFieldAssignableGroupsResponse" /api/lotus/assignables/groups/{group_id}/agents.json: get: operationId: ListAssigneeFieldAssignableGroupAgents tags: - AssigneeFieldAssignableAgents summary: List assignable agents from a group on the AssigneeField description: | List assignable agents from a group on the AssigneeField #### Allowed For * Agents parameters: - $ref: "#/components/parameters/GroupId" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/AssigneeFieldAssignableGroupAgentsResponse" /api/v2/{target_type}/{target_id}/relationship_fields/{field_id}/{source_type}: get: operationId: GetSourcesByTarget tags: - Lookup Relationships summary: Get sources by target description: | 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](/api-reference/introduction/pagination/). parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - name: target_type in: path description: | 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" required: true schema: type: string - name: target_id in: path description: "The id of the object the relationship field is targeting " required: true schema: type: integer - name: field_id in: path description: "The id of the lookup relationship field " required: true schema: type: integer - name: source_type in: path description: | 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" required: true schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ReverseLookupResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/account/settings: get: operationId: ShowAccountSettings tags: - Account Settings summary: Show Settings description: | Shows the settings that are available for the account. #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/AccountSettingsResponse" put: operationId: UpdateAccountSettings tags: - Account Settings summary: Update Account Settings description: | Updates settings for the account. See [JSON Format](#json-format) above for the settings you can update. #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/AccountSettingsResponse" /api/v2/accounts: post: operationId: CreateTrialAccount tags: - Reseller summary: Create Trial Account responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/TrialAccountResponse" /api/v2/accounts/available: get: operationId: VerifySubdomainAvailability tags: - Reseller summary: Verify Subdomain Availability description: | Zendesk Support credentials are not required to access this endpoint. You can use any Zendesk Support subdomain. Returns "true" if the subdomain is available. parameters: - name: subdomain in: query description: "Specify the name of the subdomain you want to verify. The name can't contain underscores, hyphens, or spaces. " required: true schema: type: string responses: "200": description: Success response content: application/json: schema: type: object properties: success: type: boolean /api/v2/activities: parameters: - $ref: "#/components/parameters/ActivitySince" get: operationId: ListActivities tags: - Activity Stream summary: List Activities description: | Lists ticket activities in the last 30 days affecting the agent making the request. Also sideloads the following arrays of user records: - actors - All actors involved in the listed activities - users - All users involved in the listed activities #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ActivitiesResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/activities/{activity_id}: parameters: - $ref: "#/components/parameters/ActivityId" get: operationId: ShowActivity tags: - Activity Stream summary: Show Activity description: | Lists a specific activity. #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ActivityResponse" /api/v2/activities/count: get: operationId: CountActivities tags: - Activity Stream summary: Count Activities description: |- Returns an approximate count of ticket activities in the last 30 days affecting the agent making the request. If the count exceeds 100,000, the count will return a cached result. This cached result will update every 24 hours. The `count[refreshed_at]` property is a timestamp that indicates when the count was last updated. **Note**: When the count exceeds 100,000, `count[refreshed_at]` may occasionally be null. This indicates that the count is being updated in the background, and `count[value]` is limited to 100,000 until the update is complete. #### Allowed For * Agents responses: "200": description: Count of ticket activities content: application/json: schema: $ref: "#/components/schemas/ActivitiesCountResponse" /api/v2/any_channel/channelback/report_error: post: operationId: ReportChannelbackError tags: - Channel Framework summary: Report Channelback Error to Zendesk description: | #### Allowed For * Admins #### Request parameters The POST request takes a JSON object parameter which contains information about the problematic [channelback](/documentation/channel_framework/understanding-the-channel-framework/channelback/). | Name | Type | Required | Comments | ------------------ | ----------| --------- | ------------------- | instance_push_id | string | yes | The ID of the account to which data will be pushed. This was passed to the integration service when the administrator set up the account | external_id | string | yes | Unique identifier of the external resource from the original channelback (string) | description | string | no | A human readable description of the error | request_id | string | no | A unique identifier for the request #### Response format The response does not include a response body responses: "200": description: Success response content: application/json: schema: type: string description: Empty response /api/v2/any_channel/push: post: operationId: PushContentToSupport tags: - Channel Framework summary: Push Content to Support description: | Pushes Channel framework content to Zendesk. #### Allowed For * Admins #### Request parameters The POST request takes a JSON object parameter which contains data about all the resources that the client is pushing. | Name | Type | Required | Comments | ------------------ | ----------| --------- | ------------------- | instance_push_id | string | yes | The account ID where data will be pushed. This was passed to the integration service when the administrator set up the account | request_id | string | no | A unique identifier for the push request | external_resources | array | yes | The [resources](#external_resource-object) to push #### external_resource object | Name | Type | Max length | Mandatory | Comments |------------------- | ---------------------------------- |------------| --------- | ---------- | external_id | string | 255 | yes | Unique identifier of the external resource. Must be ASCII characters | internal_note | boolean | | no | If true creates a new internal note comment | message | string | 65535 | yes | Text to be converted to a ticket or comment | html_message | string | 65535 | no | HTML version of message | parent_id | string | 511 | no | Unique identifier of the external resource for which this is a response. Used to choose the correct thread. Responses may include `parent_id` or `thread_id`, but not both. See [Conversation threads](/documentation/channel_framework/understanding-the-channel-framework/pull_endpoint/#conversation-threads) | thread_id | string | 255 | no | Arbitrary identifier of the thread to which this item should belong. Responses may include `parent_id` or `thread_id`, but not both. See [Conversation threads](/documentation/channel_framework/understanding-the-channel-framework/pull_endpoint/#conversation-threads) | created_at | string | | yes | When the resource was created in the origin system, as an ISO 8601 extended format date-time. Example: '2015-09-08T22:48:09Z' | author | object | | yes | See [author object](#author-object) below | display_info | array | | no | Array of integration-specific data used by apps to modify the agent UI. See [display_info object](#display_info-object) below | allow_channelback | boolean | | no | If false, prevents the agent from making additional comments on the message in the Zendesk interface | fields | array | | no | Array of ticket fields to set in Zendesk and their values. See [fields array](#fields-array) | file_urls | array | 10 | no | Array of files to be imported into Zendesk. See [file urls](/documentation/channel_framework/understanding-the-channel-framework/pull_endpoint/#file-urls) in the Channel framework docs #### author object | Name | Type | Max chars | Mandatory | Comments |------------ | ------ |---------- |---------- |----------- | external_id | string | 255 | yes | Unique identifier of the user in the origin service | name | string | 255 | no | If not supplied, defaults to external id | image_url | string | 255 | no | URL to an image for the user | locale | String | 255 | no | The user's locale. Must be one of the supported [locales](/api-reference/ticketing/account-configuration/locales/#list-available-public-locales) in Zendesk | fields | array | | no | Array of items containing user field identifier ('id') and value of field ('value'.) For system fields ('notes' or 'details'), the identifier is the English name. For custom fields, the identifier may be the ID or the name #### display_info object | Name | Type | Max chars | Mandatory | Comments |----- | ------ |---------- |---------- |----------- | type | string | 255 | yes | Globally unique type identifier defined by the integration origin service. Examples: a GUID or URI | data | string | 65535 | yes | JSON data containing display hints #### fields array The `fields` array lists ticket fields to set in Zendesk and their values. Each item consists of a field identifier (`id`) and a value (`value`) for the field. For Zendesk system fields such as `subject`, the identifier is the English name. For custom fields, the identifier may be a field ID or a name. See [Ticket Fields](/api-reference/ticketing/tickets/ticket_fields/). The `fields` array can only set ticket values on ticket creation, not on ticket updates. #### Response format The response is a JSON object containing a single key: | Name | Type | Comments | --------- | -------- | ------------------- | results | array | An array of [result objects](#result-object) The `results` array contains an entry for each item in the incoming `external_resources` array, in the same order. For example, if you call `push` with 3 external resources, a successful response will include `results` with three entries, corresponding to your 3 resources. #### result object | Name | Type | Comments | -------------------- | ------------------------------ | ------------------- | external_resource_id | string | The external ID of the resource, as passed in | status | object | The status of the import for the indicated resource. See [status object](#status-object) #### status object | Name | Type | Comments | ----------- | ------ | ------------------- | code | string | A code indicating the status of the import of the resource, as described in [status codes](#status-codes) | description | string | In the case of an exception, a description of the exception. Otherwise, not present. #### status codes | Key | Description | ----------------------------------------- | ---------------- | success | The external resource was successfully converted to a ticket or comment | already_imported | Reimport of the external resource was skipped due to a pre-existing ticket or comment for the resource | could_not_locate_parent_external_resource | The parent resource, as identified by parent_id in the [request](#request-parameters), could not be found. The unrecognized parent ID is returned in the description of the [status](#status-object) | processing_error | An internal exception occurred while processing the resource. See `description` in the [status object](#status-object) | halted | This resource was not processed because processing of previous resources failed responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ChannelFrameworkPushResultsResponse" /api/v2/any_channel/validate_token: post: operationId: ValidateToken tags: - Channel Framework summary: Validate Token description: | #### Allowed For * Admins #### Request parameters The POST request takes a JSON object parameter which contains the token to be validated. | Name | Type | Required | Comments | ------------------ | ----------| --------- | ------------------- | instance_push_id | string | yes | The ID of the account to which data will be pushed. This was passed to the integration service when the administrator set up the account | request_id | string | no | A unique identifier for the push request #### Response format The response body is empty. responses: "200": description: Success response content: application/json: schema: type: string description: Empty response /api/v2/approval_workflow_instances: post: operationId: CreateApprovalWorkflowInstance tags: - Approval Workflow Instances summary: Create Approval Workflow Instance description: | Creates an approval workflow instance attached to a ticket. The request must include a name for the workflow and a ticket id to associate with the workflow instance. #### Allowed For * Agents responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/ApprovalWorkflowInstanceObject" /api/v2/approval_workflow_instances/{approval_workflow_instance_id}/approval_requests: parameters: - $ref: "#/components/parameters/ApprovalWorkflowInstanceId" post: operationId: CreateApprovalRequest tags: - Approval Requests summary: Create an Approval Request description: | Creates an approval request that is attached to a ticket. The request must include all of the following information: - A subject and message for the approval - A ticket the request should be associated with - A [workflow instance id](/api-reference/ticketing/approvals/approval_workflow_instances/#approval-workflow-instances) for the request - An assignee that will act as an approver #### Allowed For * Agents requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ApprovalRequestCreateRequest" responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/ApprovalRequestObject" /api/v2/approval_workflow_instances/{approval_workflow_instance_id}/approval_requests/{approval_request_id}: parameters: - $ref: "#/components/parameters/ApprovalWorkflowInstanceId" - $ref: "#/components/parameters/ApprovalRequestId" get: operationId: ShowApprovalRequest tags: - Approval Requests summary: Show Approval Request description: | Shows an approval request. #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ApprovalRequestObject" /api/v2/approval_workflow_instances/{approval_workflow_instance_id}/approval_requests/{approval_request_id}/decision: parameters: - $ref: "#/components/parameters/ApprovalWorkflowInstanceId" - $ref: "#/components/parameters/ApprovalRequestId" patch: operationId: UpdateDecisionApprovalRequest tags: - Approval Requests summary: Update Approval Request Status description: | Updates the approver's decision about an approval request. #### Allowed For * Agents requestBody: required: true content: application/json: schema: type: object properties: notes: type: string description: Notes for the decision status: type: string description: The status of the approval request enum: - approved - rejected - pending - withdrawn responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ApprovalRequestObject" /api/v2/approval_workflow_instances/{approval_workflow_instance_id}/approval_requests/search: parameters: - $ref: "#/components/parameters/ApprovalWorkflowInstanceId" post: operationId: SearchApprovals tags: - Approval Requests summary: Get Approvals by Approval Workflow Id description: | Returns a list of approvals associated with a specific [workflow instance](/api-reference/ticketing/approvals/approval_workflow_instances/#approval-workflow-instances). Results can be filtered by approval request status. #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ApprovalRequestsSearchResponse" /api/v2/attachments/{attachment_id}: get: operationId: ShowAttachment tags: - Attachments summary: Show Attachment description: | Shows attachment details. You can get the value of the `attachment_id` parameter by listing the ticket's comments. See [List Comments](/api-reference/ticketing/tickets/ticket_comments/#list-comments). Each comment in the list has an `attachments` list that specifies an `id` for each attachment. #### Allowed for * Agents parameters: - $ref: "#/components/parameters/AttachmentId" responses: "200": description: Success Response content: application/json: schema: $ref: "#/components/schemas/AttachmentResponse" put: operationId: UpdateAttachment tags: - Attachments summary: Update Attachment for Malware description: | Toggles enabling or restricting agent access to attachments with detected malware. #### Allowed For * Admins parameters: - $ref: "#/components/parameters/AttachmentId" requestBody: content: application/json: schema: $ref: "#/components/schemas/AttachmentUpdateRequest" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/AttachmentResponse" /api/v2/audit_logs: get: operationId: ListAuditLogs tags: - Audit Logs summary: List Audit Logs description: | #### Allowed For * Admins on accounts that have audit log access #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - name: filter[source_type] in: query description: Filter audit logs by the source type. For example, user or rule schema: type: string - name: filter[source_id] in: query description: Filter audit logs by the source id. Requires `filter[source_type]` to also be set schema: type: integer - name: filter[actor_id] in: query description: Filter audit logs by the actor id schema: type: integer - name: filter[ip_address] in: query description: Filter audit logs by the ip address schema: type: string - name: filter[created_at] in: query description: Filter audit logs by the time of creation. When used, you must specify `filter[created_at]` twice in your request, first with the start time and again with an end time schema: type: string - name: filter[action] in: query description: Filter audit logs by the action schema: type: string - name: sort in: query description: Cursor pagination only. Sort audit logs. Default is `sort=-created_at` schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/AuditLogsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/audit_logs/{audit_log_id}: parameters: - $ref: "#/components/parameters/AuditLogId" get: operationId: ShowAuditLog tags: - Audit Logs summary: Show Audit Log description: | #### Allowed For * Admins on accounts that have audit-log access responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/AuditLogResponse" /api/v2/audit_logs/export: post: operationId: ExportAuditLogs tags: - Audit Logs summary: Export Audit Logs description: | #### Allowed For * Admins on accounts that have audit log access parameters: - name: filter[source_type] in: query description: Filter audit logs by the source type. For example, user or rule schema: type: string - name: filter[source_id] in: query description: Filter audit logs by the source id. Requires `filter[source_type]` to also be set. schema: type: integer - name: filter[actor_id] in: query description: Filter audit logs by the actor id schema: type: integer - name: filter[ip_address] in: query description: Filter audit logs by the ip address schema: type: string - name: filter[created_at] in: query description: Filter audit logs by the time of creation. When used, you must specify `filter[created_at]` twice in your request, first with the start time and again with an end time schema: type: string - name: filter[action] in: query description: Filter audit logs by the action schema: type: string responses: "202": description: Accepted description content: application/json: schema: type: string description: Empty response /api/v2/autocomplete/tags: parameters: - $ref: "#/components/parameters/TagNameFragment" get: operationId: AutocompleteTags tags: - Tags summary: Search Tags description: | Returns an array of registered and recent tag names that start with the characters specified in the `name` query parameter. You must specify at least 2 characters. #### Pagination * Offset pagination only See [Using Offset Pagination](/api-reference/ticketing/introduction/#using-offset-pagination). #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TagsByObjectIdResponse" /api/v2/automations: get: operationId: ListAutomations tags: - Automations summary: List Automations description: | Lists all automations for the current account. #### Allowed For * Agents #### Available Parameters You can pass in any combination of the following optional filters: | Name | Type | Comment | ---------- | ------- | ------- | active | boolean | Only active automations if true, inactive automations if false | sort_by | string | Possible values are "alphabetical", "created_at", "updated_at", "usage_1h", "usage_24h", or "usage_7d". Defaults to "position" | sort_order | string | One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others #### Sideloads The following sideloads are supported. The usage sideloads are only supported on the Support Professional or Suite Growth plan or above. | Name | Will sideload | ---------------- | ------------- | app_installation | The app installation that requires each automation, if present | permissions | The permissions for each automation | usage_1h | The number of times each automation has been used in the past hour | usage_24h | The number of times each automation has been used in the past day | usage_7d | The number of times each automation has been used in the past week | usage_30d | The number of times each automation has been used in the past thirty days #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/AutomationsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateAutomation tags: - Automations summary: Create Automation description: | Creates an automation. New automations must be unique and have at least one condition that is true only once or an action that nullifies at least one of the conditions. Active automations can have overlapping conditions but can't be identical. The request must include the following conditions in the `all` array: - At least one time-based condition - At least one condition that checks one of the following fields: `status`, `type`, `group_id`, `assignee_id`, or `requester_id`. #### Allowed For * Agents responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/AutomationResponse" /api/v2/automations/{automation_id}: parameters: - $ref: "#/components/parameters/AutomationId" get: operationId: ShowAutomation tags: - Automations summary: Show Automation description: | #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/AutomationResponse" put: operationId: UpdateAutomation tags: - Automations summary: Update Automation description: | Updates an automation. Updated automations must be unique and have at least one condition that is true only once or an action that nullifies at least one of the conditions. Active automations can have overlapping conditions but can't be identical. The request must include the following conditions in the `all` array: - At least one time-based condition - At least one condition that checks one of the following fields: 'status', 'type', 'group_id', 'assignee_id', or 'requester_id' **Note**: Updating a condition or action updates both the `conditions` and `actions` arrays, clearing all existing values of both arrays. Include all your conditions and actions when updating any condition or action. **Note**: You might be restricted from updating some default automations. #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/AutomationResponse" delete: operationId: DeleteAutomation tags: - Automations summary: Delete Automation description: | **Note**: You might be restricted from deleting some default automations. #### Allowed For * Agents responses: "204": description: No Content response /api/v2/automations/active: get: operationId: ListActiveAutomations tags: - Automations summary: List Active Automations description: | Lists all active automations. #### Allowed For * Agents #### Available Parameters You can pass in any combination of the following optional filters: | Name | Type | Comment | ---------- | ------ | ------- | sort_by | string | Possible values are "alphabetical", "created_at", "updated_at", "usage_1h", "usage_24h", or "usage_7d". Defaults to "position" | sort_order | string | One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others #### Sideloads The following sideloads are supported: | Name | Will sideload | ---------------- | ------------- | app_installation | The app installation that requires each automation, if present | permissions | The permissions for each automation | usage_1h | The number of times each automation has been used in the past hour | usage_24h | The number of times each automation has been used in the past day | usage_7d | The number of times each automation has been used in the past week | usage_30d | The number of times each automation has been used in the past thirty days responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/AutomationsResponse" /api/v2/automations/destroy_many: delete: operationId: BulkDeleteAutomations tags: - Automations summary: Bulk Delete Automations description: | Deletes the automations corresponding to the provided comma-separated list of IDs. **Note**: You might be restricted from deleting some default automations. If included in a bulk deletion, the unrestricted automations will be deleted. #### Allowed For * Agents #### Request Parameters The DELETE request takes one parameter, an `ids` object that lists the automations to delete. | Name | Description | ---- | ----------- | ids | The IDs of the automations to delete #### Example request ```js { "ids": "25,23,27,22" } ``` parameters: - name: ids in: query description: The IDs of the automations to delete schema: type: array items: type: integer responses: "204": description: No Content response /api/v2/automations/search: parameters: - $ref: "#/components/parameters/AutomationSearchQuery" - $ref: "#/components/parameters/AutomationActive" - $ref: "#/components/parameters/AutomationSortBy" - $ref: "#/components/parameters/AutomationSortOrder" - $ref: "#/components/parameters/AutomationInclude" get: operationId: SearchAutomations tags: - Automations summary: Search Automations description: | #### Pagination * Offset pagination only See [Using Offset Pagination](/api-reference/ticketing/introduction/#using-offset-pagination). #### Allowed For * Agents #### Sideloads The following sideloads are supported. For more information, see [Side-loading](/documentation/ticketing/using-the-zendesk-api/side_loading/). | Name | Will sideload | ---------------- | ------------- | app_installation | The app installation that requires each automation, if present | permissions | The permissions for each automation | usage_1h | The number of times each automation has been used in the past hour | usage_24h | The number of times each automation has been used in the past day | usage_7d | The number of times each automation has been used in the past week | usage_30d | The number of times each automation has been used in the past thirty days responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/AutomationsResponse" /api/v2/automations/update_many: put: operationId: UpdateManyAutomations tags: - Automations summary: Update Many Automations description: | **Note**: You might be restricted from updating some default automations. If included in a bulk update, the unrestricted automations will be updated. #### Allowed For * Agents #### Request Parameters The PUT request expects an `automations` object that lists the automations to update. Each automation may have the following properties: | Name | Mandatory | Description | -------- | --------- | ----------- | id | yes | The ID of the automation to update | position | no | The new position of the automation | active | no | The active status of the automation (true or false) #### Example Request ```js { "automations": [ {"id": 25, "position": 3}, {"id": 23, "position": 5}, {"id": 27, "position": 9}, {"id": 22, "position": 7} ] } ``` responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/AutomationsResponse" /api/v2/bookmarks: get: operationId: ListBookmarks tags: - Bookmarks summary: List Bookmarks description: |- #### Allowed For - Agents responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/BookmarksResponse" post: operationId: CreateBookmark tags: - Bookmarks summary: Create Bookmark description: |- #### Allowed For - Agents requestBody: content: application/json: schema: $ref: "#/components/schemas/BookmarkCreateRequest" responses: "200": description: Successfully created content: application/json: schema: $ref: "#/components/schemas/BookmarkResponse" "201": description: Successfully created content: application/json: schema: $ref: "#/components/schemas/BookmarkResponse" /api/v2/bookmarks/{bookmark_id}: parameters: - $ref: "#/components/parameters/BookmarkId" delete: operationId: DeleteBookmark tags: - Bookmarks summary: Delete Bookmark description: |- #### Allowed For - Agents (own bookmarks only) If the bookmark already exists with a specified ticket id, the response status will be `http Status: 200 OK`. responses: "204": description: No content /api/v2/brand_agents: get: operationId: ListBrandAgents tags: - Brand Agents summary: List Brand Agent Memberships description: | Returns a list of all brand agent memberships for your account. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For: * Admins parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - name: user_id in: query description: Filter by user ID required: false schema: type: integer - name: brand_id in: query description: Filter by brand ID required: false schema: type: integer responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/BrandAgentsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/brand_agents/{brand_agent_id}: get: operationId: ShowBrandAgentById tags: - Brand Agents summary: Show Brand Agent Membership description: | Returns a brand agent membership for your account. #### Allowed For * Admins parameters: - $ref: "#/components/parameters/BrandAgentId" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/BrandAgentResponse" /api/v2/brands: get: operationId: ListBrands tags: - Brands summary: List Brands description: |- Returns a list of all brands for your account sorted by name. #### Allowed for * Admins * Agents with the `assign_tickets_to_any_brand` permission can list all brands for the account * Agents without the `assign_tickets_to_any_brand` permission can only list brands they are members of #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/BrandsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateBrand tags: - Brands summary: Create Brand description: |- #### Allowed for - Admins requestBody: content: application/json: schema: $ref: "#/components/schemas/BrandCreateRequest" responses: "201": description: Successful response content: application/json: schema: $ref: "#/components/schemas/BrandResponse" /api/v2/brands/{brand_id}: get: operationId: ShowBrand tags: - Brands summary: Show a Brand description: |- Returns a brand for your account. #### Allowed for * Admins, Agents parameters: - $ref: "#/components/parameters/BrandId" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/BrandResponse" put: operationId: UpdateBrand tags: - Brands summary: Update a Brand description: |- Returns an updated brand. #### Allowed for * Admins #### Updating a Brand's Image A brand image can be updated by uploading a local file using the update brand endpoint. See the **Using curl** sections below for more information. parameters: - $ref: "#/components/parameters/BrandId" requestBody: content: application/json: schema: $ref: "#/components/schemas/BrandUpdateRequest" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/BrandResponse" image/jpg: {} image/png: {} delete: operationId: DeleteBrand tags: - Brands summary: Delete a Brand description: |- Deletes a brand. #### Allowed for - Admins parameters: - $ref: "#/components/parameters/BrandId" responses: "204": description: No Content response /api/v2/brands/{brand_id}/check_host_mapping: get: operationId: CheckHostMappingValidityForExistingBrand tags: - Brands summary: Check Host Mapping Validity for an Existing Brand description: |- Returns a JSON object determining whether a host mapping is valid for the given brand. #### Allowed for - Admins parameters: - $ref: "#/components/parameters/BrandId" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/HostMappingObject" /api/v2/brands/check_host_mapping: get: operationId: CheckHostMappingValidity tags: - Brands summary: Check Host Mapping Validity description: |- Returns a JSON object determining whether a host mapping is valid for a given subdomain. #### Allowed for * Admins parameters: - $ref: "#/components/parameters/HostMapping" - $ref: "#/components/parameters/Subdomain" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/HostMappingObject" /api/v2/channels/twitter/monitored_twitter_handles: get: operationId: ListMonitoredTwitterHandles tags: - X Channel summary: List Monitored X Handles description: | #### Allowed For * Admins * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TwitterChannelsResponse" /api/v2/channels/twitter/monitored_twitter_handles/{monitored_twitter_handle_id}: parameters: - $ref: "#/components/parameters/MonitoredTwitterHandleId" get: operationId: ShowMonitoredTwitterHandle tags: - X Channel summary: Show Monitored X Handle description: | #### Allowed For * Admins * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TwitterChannelResponse" /api/v2/channels/twitter/tickets: post: operationId: CreateTicketFromTweet tags: - X Channel summary: Create Ticket from Tweet description: | Turns a tweet into a ticket. You must provide the tweet id as well as the id of a monitored X (formerly Twitter) handle configured for your account. The submitter of the ticket is set to be the user submitting the API request. #### Allowed For * Agents responses: "201": description: description content: application/json: schema: type: string description: Empty response /api/v2/channels/twitter/tickets/{comment_id}/statuses: parameters: - $ref: "#/components/parameters/CommentId" get: operationId: GettingTwicketStatus tags: - X Channel summary: List Ticket statuses description: | #### Allowed For * Agents parameters: - name: ids in: query description: Optional comment ids to retrieve tweet information for only particular comments schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TwitterChannelTwicketStatusResponse" /api/v2/channels/voice/agents/{agent_id}/tickets/{ticket_id}/display: post: operationId: OpenTicketInAgentBrowser tags: - Basics summary: Open Ticket in Agent's Browser description: |- Allows you to instruct an agent's browser to open a ticket. When the message is successfully delivered to an agent's browser: ```http Status: 200 OK ``` When `agent_id` or `ticket_id` is invalid: ```http Status: 404 Not Found ``` #### Allowed For * Agents parameters: - $ref: "#/components/parameters/AgentId" - $ref: "#/components/parameters/TicketId" responses: "200": description: Successful response content: application/json: schema: type: string description: empty "404": description: When the `agent_id` or `ticket_id` is invalid content: application/json: schema: type: string description: Invalid attribute /api/v2/channels/voice/agents/{agent_id}/users/{user_id}/display: post: operationId: OpenUsersProfileInAgentBrowser tags: - Basics summary: Open a User's Profile in an Agent's Browser description: |- Allows you to instruct an agent's browser to open a user's profile. When the message is successfully delivered to an agent's browser: ```http Status: 200 OK ``` When `agent_id` or `user_id` is invalid: ```http Status: 404 Not Found ``` #### Allowed For * Agents parameters: - $ref: "#/components/parameters/AgentId" - $ref: "#/components/parameters/UserId" responses: "200": description: Successful response content: application/json: schema: type: string description: empty "404": description: When the `agent_id` or `user_id` is invalid content: application/json: schema: type: string description: Invalid attribute /api/v2/channels/voice/tickets: post: operationId: CreateTicketOrVoicemailTicket tags: - Basics summary: Create Ticket or Voicemail Ticket description: |- #### Allowed For * Agents ### Creating tickets #### Introduction Creating tickets using Talk Partner Edition follows the same conventions as the Create Ticket endpoint. See [Create Ticket](/api-reference/ticketing/tickets/tickets/#create-ticket). #### Request parameters The POST request takes a mandatory `ticket` object that lists the values to set when the ticket is created. You may also include an optional `display_to_agent` value such as the ID of the agent that will see the newly created ticket. The `display_to_agent` is validated before creating the ticket, returning a 422 error if it is invalid. Tickets created using this endpoint must have a `via_id` parameter. See the following section for possible values. #### Zendesk Talk Integration Via IDs Tickets created using this endpoint must have one of the following `via_id` parameters: | ID | Description | ---------| ------------- | 44 | Voicemail | 45 | Phone call (inbound) | 46 | Phone call (outbound) ### Creating voicemail tickets #### Request parameters The POST request takes a mandatory `ticket` object that lists the values to set when the ticket is created. The ticket must have a `voice_comment` with the following values: | Name | Type | Comment | ------------------ | ----------------------| ------- | from | string | Incoming phone number | to | string | Dialed phone number | recording_url | string | URL of the recording | started_at | date | [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) timestamp of the call starting time | call_duration | integer | Duration in seconds of the call | answered_by_id | integer | The agent who answered the call | transcription_text | string | Transcription of the call (optional) | location | string | Location of the caller (optional) requestBody: content: application/json: schema: $ref: "#/components/schemas/TicketCreateVoicemailTicketRequest" responses: "201": description: Successful response content: application/json: schema: $ref: "#/components/schemas/TicketResponse" "404": description: When the `ticket_id` is invalid content: application/json: schema: type: string description: Invalid attribute "422": description: When the `agent_id` is invalid content: application/json: schema: type: string description: Invalid attribute /api/v2/chat_file_redactions/{ticket_id}: parameters: - $ref: "#/components/parameters/TicketId" put: operationId: RedactChatCommentAttachment tags: - Ticket Comments summary: Redact Chat Comment Attachment description: | Permanently removes one or more chat attachments from a chat ticket. **Note**: This does not work on active chats. For chat tickets that predate March 2020, consider using [Redact Ticket Comment In Agent Workspace](#redact-ticket-comment-in-agent-workspace). #### Allowed For - Agents [Agent Workspace](https://support.zendesk.com/hc/en-us/articles/360024218473) must enabled for the account. Deleting tickets must be enabled for agents. #### Request Body Properties | Name | Type | Required | Description | | ------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | chat_id | string | true | The `chat_id` in the `ChatStartedEvent` event in the ticket audit. See [Ticket Audits](/api-reference/ticketing/tickets/ticket_audits) | | chat_indexes | array | false | The array of `chat_index` in the `ChatFileAttachment` event in the ticket audit. See [Ticket Audits](/api-reference/ticketing/tickets/ticket_audits). Mandatory if `message_ids` is not used | | message_ids | array | false | The array of `message_id` in the `ChatFileAttachment` event in the ticket audit that is part of a `ChatStartedEvent` history. Used when redacting a ChatFileAttachment that is part of a conversation history. Mandatory if `chat_indexes` is not used | To get the required body properties, make a request to the [Ticket Audits](/api-reference/ticketing/tickets/ticket_audits) endpoint. Example response: ```http Status 200 OK { "audits": [ "events": [ { "id": 1932802680168, "type": "ChatStartedEvent", "value": { "visitor_id": "10502823-16EkM3T6VNq7KMd", "chat_id": "2109.10502823.Sjuj2YrBpXwei", "history": [ { "chat_index": 0, "type": "ChatFileAttachment", "filename": "image1.jpg" }, { "chat_index": 1, "type": "ChatFileAttachment", "filename": "image2.jpg" } ] } } ] ] } ``` responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketChatCommentRedactionResponse" /api/v2/chat_redactions/{ticket_id}: parameters: - $ref: "#/components/parameters/TicketId" put: operationId: RedactChatComment tags: - Ticket Comments summary: Redact Chat Comment description: "Permanently removes words or strings from a chat ticket's comment.\ \ \n\nWrap `` tags around the content in the chat comment you want\ \ redacted. Example: \n\n```json\n{\n \"text\": \"My ID number is 847564!\"\ \n}\n```\n\nThe characters contained in the tag will be replaced by the \u2587\ \ symbol.\n\n**Note**: This does not work on active chats. For chat tickets\ \ that predate March 2020, consider using [Redact Ticket Comment In Agent\ \ Workspace](#redact-ticket-comment-in-agent-workspace).\n\n#### Allowed For\n\ \n- Agents\n\n[Agent Workspace](https://support.zendesk.com/hc/en-us/articles/360024218473)\ \ must enabled for the account. Deleting tickets must be enabled for agents.\n\ \n#### Request Body Properties\n\n| Name | Type | Required\ \ | Description \ \ \ \ \ \ |\n| ------------------------ | ------- | --------\ \ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------\ \ |\n| chat_id | string | true | The `chat_id` in the\ \ `ChatStartedEvent` event in the ticket audit. See [Ticket Audits](/api-reference/ticketing/tickets/ticket_audits)\ \ \ \ |\n| chat_index | integer\ \ | false | The `chat_index` in the `ChatMessage` event in the ticket audit.\ \ See [Ticket Audits](/api-reference/ticketing/tickets/ticket_audits). Mandatory\ \ if `message_id` is not used \ \ |\n| message_id | string | false\ \ | The `message_id` of the `ChatMessage` event in the ticket audit that\ \ is part of a `ChatStartedEvent` history. Used when redacting a ChatMessage\ \ that is part of a conversation history. Mandatory if `chat_index` is not\ \ used |\n| text | string | true\ \ | The `message` in the `ChatMessage` event in the ticket audit. See\ \ [Ticket Audits](/api-reference/ticketing/tickets/ticket_audits). Wrap `message`\ \ with `` tags \ \ |\n\nTo get the required body properties, make a\ \ request to the [Ticket Audit](/api-reference/ticketing/tickets/ticket_audits)\ \ endpoint. Example response:\n\n```http\nStatus 200 OK\n{\n \"audits\":\ \ [\n \"events\": [\n {\n \"id\": 1932802680168,\n \"\ type\": \"ChatStartedEvent\",\n \"value\": {\n \"visitor_id\"\ : \"10502823-16EkM3T6VNq7KMd\",\n \"chat_id\": \"2109.10502823.Sjuj2YrBpXwei\"\ ,\n \"history\": [\n {\n \"chat_index\":\ \ 0,\n \"type\": \"ChatMessage\",\n \"message\"\ : \"My ID number is 847564!\"\n }\n ]\n }\n \ \ }\n ]\n ]\n}\n```\n" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketChatCommentRedactionResponse" /api/v2/comment_redactions/{ticket_comment_id}: parameters: - $ref: "#/components/parameters/TicketCommentId" put: operationId: RedactTicketCommentInAgentWorkspace tags: - Ticket Comments summary: Redact Ticket Comment In Agent Workspace description: "Redaction allows you to permanently remove words, strings, or\ \ attachments from a ticket comment.\n\nIn the `html_body` of the comment,\ \ wrap the content you want redacted in `` tags. Example:\n\n```json\n\ {\n \"html_body\": \"
My ID\ \ number is 847564!
\",\n \"ticket_id\":100\n}\n```\n\ \nThe characters in the redact tag will be replaced by the \u2587 symbol.\n\ \nTo redact HTML elements such inline images, anchor tags, and links, add\ \ the `redact` tag attribute to the element as well as the `` tag\ \ to inner text, if any. Example: \n\n`some\ \ link`\n\nThe `redact` attribute only redacts the tag. Any inner\ \ text will be left behind if not enclosed in a `` tag.\n\nRedaction\ \ is permanent and can not be undone. Data is permanently deleted from Zendesk\ \ servers with no way to recover it.\n\nThis endpoint provides all the same\ \ functionality that the [Redact String in Comment](/api-reference/ticketing/tickets/ticket_comments/#redact-string-in-comment)\ \ endpoint provides, plus:\n\n- Redaction of comments in closed tickets\n\n\ - Redaction of comments in archived tickets\n\n- Redaction of formatted text\ \ (bold, italics, hyperlinks)\n\n**Limitations**: When content is redacted\ \ from an email comment, the content is also redacted from the original email\ \ through a background job. It may take a while for the changes to be completed.\n\ \n**Note**: We recommend using this endpoint instead of the [Redact String\ \ in Comment](/api-reference/ticketing/tickets/ticket_comments/#redact-string-in-comment)\ \ endpoint, which will eventually be deprecated.\n\n#### Allowed For\n\n-\ \ Agents\n\n[Agent Workspace](https://support.zendesk.com/hc/en-us/articles/360024218473)\ \ must be enabled on the account. For professional accounts, deleting tickets\ \ must be enabled for agents. On Enterprise accounts, you can assign agents\ \ to a custom role with permissions to redact ticket content.\n\n#### Request\ \ Body Properties\n\n| Name | Type | Required | Description\ \ \ \ |\n| -------------------------|\ \ ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------\ \ |\n| ticket_id | integer | true | The ID of the ticket\ \ \ \ |\n| html_body \ \ | string | false | The `html_body` of the comment containing\ \ `` tags or `redact` attributes \ \ |\n| external_attachment_urls | array | false | Array of attachment\ \ URLs belonging to the comment to be redacted. See [`content_url` property\ \ of Attachment](/api-reference/ticketing/tickets/ticket-attachments/) |\n" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketCommentResponse" /api/v2/custom_objects: get: operationId: ListCustomObjects tags: - Custom Objects summary: List Custom Objects description: |- Lists all undeleted custom objects for the account #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CustomObjectsResponse" post: operationId: CreateCustomObject tags: - Custom Objects summary: Create Custom Object description: | Creates an object describing all the properties required to create a custom object record #### Allowed For * Admins requestBody: content: application/json: schema: $ref: "#/components/schemas/CustomObjectsCreateRequest" responses: "201": description: Created content: application/json: schema: $ref: "#/components/schemas/CustomObjectResponse" /api/v2/custom_objects/{custom_object_key}: get: operationId: ShowCustomObject tags: - Custom Objects summary: Show Custom Object description: | Returns an object with the specified key #### Allowed For * Agents parameters: - $ref: "#/components/parameters/CustomObjectKey" responses: "200": description: Custom Object content: application/json: schema: $ref: "#/components/schemas/CustomObjectResponse" patch: operationId: UpdateCustomObject tags: - Custom Objects summary: Update Custom Object description: |- Updates an individual custom object. The updating rules are as follows: * Takes a `custom_object` object that specifies the properties to update * The `key` property cannot be updated #### Allowed For * Admins parameters: - $ref: "#/components/parameters/CustomObjectKey" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CustomObjectResponse" delete: operationId: DeleteCustomObject tags: - Custom Objects summary: Delete Custom Object description: |- Permanently deletes the custom object with the specified key #### Allowed For * Admins parameters: - $ref: "#/components/parameters/CustomObjectKey" responses: "204": description: No content response /api/v2/custom_objects/{custom_object_key}/fields: get: operationId: ListCustomObjectFields tags: - Custom Object Fields summary: List Custom Object Fields description: |- Lists all undeleted custom fields for the specified object. #### Allowed For * Agents #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - $ref: "#/components/parameters/CustomObjectKey" - $ref: "#/components/parameters/IncludeStandardFields" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CustomObjectFieldsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateCustomObjectField tags: - Custom Object Fields summary: Create Custom Object Field description: | Creates any of the following custom field types: * text (default when no "type" is specified) * textarea * checkbox * date * integer * decimal * regexp * dropdown * lookup * multiselect See [About custom field types](https://support.zendesk.com/hc/en-us/articles/203661866) in Zendesk help. #### Allowed For * Admins parameters: - $ref: "#/components/parameters/CustomObjectKey" requestBody: content: application/json: schema: $ref: "#/components/schemas/CustomObjectFieldsCreateRequest" responses: "201": description: Created content: application/json: schema: $ref: "#/components/schemas/CustomObjectFieldResponse" /api/v2/custom_objects/{custom_object_key}/fields/{custom_object_field_key_or_id}: get: operationId: ShowCustomObjectField tags: - Custom Object Fields summary: Show Custom Object Field description: | Returns a custom field for a specific object using a provided key or id of the field. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/CustomObjectKey" - $ref: "#/components/parameters/CustomObjectFieldKeyOrId" responses: "200": description: Custom Object Field content: application/json: schema: $ref: "#/components/schemas/CustomObjectFieldResponse" patch: operationId: UpdateCustomObjectField tags: - Custom Object Fields summary: Update Custom Object Field description: |- Updates individual custom object fields. The updating rules are as follows: * Takes a `custom_object_field` object that specifies the properties to update * The `key` property cannot be updated * If updating a standard field, only the `title`, `description`, and `properties` attributes can be updated. * The `properties` parameter is comprised of four parts and can't be changed if any records exist for the object. * `autoincrement_enabled`: A Boolean that enables and disables autonumbering. Must be false if is_unique is true. * `autoincrement_prefix`: A string value that is used as a prefix to the autogenerated numbers. It can't exceed 30 characters. * `autoincrement_padding`: An integer specifying the starting number of digits in the autogenerated numbers. This value may be between 0-9. However, if you create records in excess of of these digits, additional digits are added as necessary. * `autoincrement_next_sequence`: An integer that will be used as the next number in the autonumbering sequence. It can't be negative or less than the current autonumbering value. * `is_unique`: A Boolean that enforces uniqueness for manually entered record names. When true, custom object record names must be unique. Must be false if autoincrement_enabled is true. #### Allowed For * Admins parameters: - $ref: "#/components/parameters/CustomObjectKey" - $ref: "#/components/parameters/CustomObjectFieldKeyOrId" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CustomObjectFieldResponse" delete: operationId: DeleteCustomObjectField tags: - Custom Object Fields summary: Delete Custom Object Field description: |- Deletes a field with the specified key. Note: You can't delete standard fields. #### Allowed For * Admins parameters: - $ref: "#/components/parameters/CustomObjectKey" - $ref: "#/components/parameters/CustomObjectFieldKeyOrId" responses: "204": description: No content response /api/v2/custom_objects/{custom_object_key}/fields/reorder: put: operationId: ReorderCustomObjectFields tags: - Custom Object Fields summary: Reorder Custom Fields of an Object description: | Sets a preferred order of custom fields for a specific object by providing field ids in the desired order. #### Allowed For * Admins parameters: - $ref: "#/components/parameters/CustomObjectKey" responses: "200": description: Reordered content: application/json: schema: type: string description: Empty response /api/v2/custom_objects/{custom_object_key}/jobs: post: operationId: CustomObjectRecordBulkJobs tags: - Custom Object Records summary: Custom Object Record Bulk Jobs description: | Queues a background job to perform bulk actions on up to 100 custom object records per single request. Takes a `job` object with two nested fields: * `action`, one of: * `"create"` * `"delete"` * `"delete_by_external_id"` * `"create_or_update_by_external_id"` * `"create_or_update_by_name"` * `"update"` * `items` * For a `"create"` action, an array of JSON objects representing the custom object records being created * For a `"delete"` action, an array of strings representing Zendesk record ids * For a `"delete_by_external_id"` action, an array of strings representing external ids * For a `"create_or_update_by_external_id"` action, an array of JSON objects representing the custom object records being created or updated by external id * For a `"create_or_update_by_name"` action, an array of JSON objects representing the custom object records being created or updated by name. The `is_unique` property on the custom object's name field must be enabled. * For an `"update"` action, an array of JSON objects representing the custom object records being updated Note: If autonumbering is selected for the custom object's name field, record names aren't allowed in the request body because they are generated automatically. If uniqueness is enabled, the record names must be unique. #### Allowed For * Agents #### Response ### This endpoint returns a `job_status` [JSON object](/api-reference/ticketing/ticket-management/job_statuses/#json-format) and queues a background job to do the work. Use the [Show Job Status](/api-reference/ticketing/ticket-management/job_statuses/#show-job-status) endpoint to check for the job's completion. Only a certain number of jobs can be queued or running at the same time. See [Job limit](/api-reference/introduction/rate-limits/#job-limit) for more information. parameters: - $ref: "#/components/parameters/CustomObjectKey" requestBody: content: application/json: schema: $ref: "#/components/schemas/CustomObjectRecordsBulkCreateRequest" responses: "201": description: Created content: application/json: schema: $ref: "#/components/schemas/CustomObjectRecordsJobsResponse" /api/v2/custom_objects/{custom_object_key}/limits/field_limit: get: operationId: CustomObjectFieldsLimit tags: - Custom Object Fields summary: Custom Object Fields Limit description: |- List the current count and the limit for a custom object's fields #### Allowed For * Agents parameters: - $ref: "#/components/parameters/CustomObjectKey" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CustomObjectLimitsResponse" /api/v2/custom_objects/{custom_object_key}/records: get: operationId: ListCustomObjectRecords tags: - Custom Object Records summary: List Custom Object Records description: |- Lists all undeleted custom object records for the specified object #### Pagination * [Cursor pagination](/api-reference/introduction/pagination/#cursor-pagination) only. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/CustomObjectKey" - name: filter[ids] in: query description: Optional comma-separated list of ids to filter records by. If one or more ids are specified, only matching records are returned. The ids must be unique and are case sensitive. schema: type: string - name: filter[external_ids] in: query description: Optional comma-separated list of external ids to filter records by. If one or more ids are specified, only matching records are returned. The ids must be unique and are case sensitive. schema: type: string - name: sort in: query description: "One of `id`, `updated_at`, `-id`, or `-updated_at`. The `-` denotes the sort will be descending. " schema: type: string - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CustomObjectRecordsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateCustomObjectRecord tags: - Custom Object Records summary: Create Custom Object Record description: | Creates a custom object record according to all the properties described by a custom object definition. If `autoincrement_enabled` is true, record names aren't allowed in the request body because they are generated automatically. If `is_unique` is true, record names must be unique. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/CustomObjectKey" requestBody: content: application/json: schema: $ref: "#/components/schemas/CustomObjectRecordsCreateRequest" responses: "201": description: Created content: application/json: schema: $ref: "#/components/schemas/CustomObjectRecordResponse" patch: operationId: UpsertCustomObjectRecordByExternalIdOrName tags: - Custom Object Records summary: Set Custom Object Record by External Id Or Name description: | If a record exists for the given external id or name, updates it. Only the specified attributes are updated. Otherwise, creates a new record with the provided external id, name and other attributes. The `is_unqiue` property on the custom object's name field must be enabled in order to update or create by name. External id and name cannot be used together in the same request. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/CustomObjectKey" - $ref: "#/components/parameters/CustomObjectRecordExternalId" - $ref: "#/components/parameters/CustomObjectRecordName" requestBody: content: application/json: schema: $ref: "#/components/schemas/CustomObjectRecordsUpsertRequest" responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/CustomObjectRecordResponse" delete: operationId: DeleteCustomObjectRecordByExternalIdOrName tags: - Custom Object Records summary: Delete Custom Object Record by External Id Or Name description: | Deletes a record with the specified external id or name. The `is_unique` property on the custom object's name field must be enabled in order to delete by name. External id and name cannot be used together in the same request. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/CustomObjectKey" - $ref: "#/components/parameters/CustomObjectRecordExternalId" - $ref: "#/components/parameters/CustomObjectRecordName" responses: "204": description: No content response /api/v2/custom_objects/{custom_object_key}/records/{custom_object_record_id}: get: operationId: ShowCustomObjectRecord tags: - Custom Object Records summary: Show Custom Object Record description: | Returns a custom record for a specific object using a provided id. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/CustomObjectKey" - $ref: "#/components/parameters/CustomObjectRecordId" responses: "200": description: Custom Object Record content: application/json: schema: $ref: "#/components/schemas/CustomObjectRecordResponse" patch: operationId: UpdateCustomObjectRecord tags: - Custom Object Records summary: Update Custom Object Record description: |- Updates an individual custom object record. The updating rules are as follows: * Takes a `custom_object_record` object that specifies the properties to update * The custom object fields should be nested inside a `custom_object_fields` object #### Allowed For * Agents parameters: - $ref: "#/components/parameters/CustomObjectKey" - $ref: "#/components/parameters/CustomObjectRecordId" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CustomObjectRecordResponse" delete: operationId: DeleteCustomObjectRecord tags: - Custom Object Records summary: Delete Custom Object Record description: |- Deletes a record with the specified id #### Allowed For * Agents parameters: - $ref: "#/components/parameters/CustomObjectKey" - $ref: "#/components/parameters/CustomObjectRecordId" responses: "204": description: No content response /api/v2/custom_objects/{custom_object_key}/records/autocomplete: get: operationId: AutocompleteCustomObjectRecordSearch tags: - Custom Object Records summary: Autocomplete Custom Object Record Search description: |- Retrieves an array of custom object records that have a field value that matches the value specified in the `name` parameter. #### Pagination * [Cursor pagination](/api-reference/introduction/pagination/#cursor-pagination) only. * Returns the first 10,000 records sorted by relevancy with page limits. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/CustomObjectKey" - name: name in: query description: Part of a name of the record you are searching for schema: type: string - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - name: field_id in: query description: "The id of the lookup field. If the field has a relationship filter, the filter is applied to the results. Must be used with `source` param. " schema: type: string - name: source in: query description: 'One of "zen:user", "zen:ticket", "zen:organization", or "zen:custom_object:CUSTOM_OBJECT_KEY". Represents the object `field_id` belongs to. Must be used with field_id param. ' schema: type: string - name: requester_id in: query description: "The id of the requester. For use with dynamic filters. " schema: type: integer - name: assignee_id in: query description: "The id of the selected assignee. For use with dynamic filters. " schema: type: integer - name: organization_id in: query description: "The id of the organization the requester belongs to. For use with dynamic filters. " schema: type: integer responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CustomObjectRecordsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/custom_objects/{custom_object_key}/records/count: get: operationId: CountCustomObjectRecords tags: - Custom Object Records summary: Count Custom Object Records description: |- Returns a total count of records for a specific custom object as well as the time the count was refreshed. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/CustomObjectKey" responses: "200": description: Success response content: application/json: schema: type: object properties: count: type: object additionalProperties: properties: refreshed_at: description: The time the last count was performed format: date-time readOnly: true type: string value: description: Number of records at the time of the latest count operation readOnly: true type: integer /api/v2/custom_objects/{custom_object_key}/records/search: get: operationId: SearchCustomObjectRecords tags: - Custom Object Records summary: Search Custom Object Records description: |- Returns an array of custom object records that meet the search criteria #### Pagination * [Cursor pagination](/api-reference/introduction/pagination/#cursor-pagination) only. * Returns the records sorted by relevancy with page limits. Without a `sort` parameter, only the first 10,000 records are returned. With a `sort` parameter, all records are returned. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - $ref: "#/components/parameters/CustomObjectKey" - name: query in: query description: | The query parameter is used to search text-based fields for records that match specific query terms. The query can be multiple words or numbers. Every record that matches the beginning of any word or number in the query string is returned.

Fuzzy search is supported for the following text-based field types: : Text fields, Multi Line Text fields, and RegExp fields.

For example, you might want to search for records related to Tesla vehicles: `query=Tesla`. In this example the API would return every record for the given custom object where any of the supported text fields contain the word 'Tesla'.

You can include multiple words or numbers in your search. For example: `query=Tesla Honda 2020`. This search phrase would be URL encoded as `query=Tesla%20Honda%202020` and return every record for the custom object for which any of the supported text fields contained 'Tesla', 'Honda', or '2020'. schema: type: string - name: sort in: query description: "One of `name`, `created_at`, `updated_at`, `-name`, `-created_at`, or `-updated_at`. The `-` denotes the sort will be descending. Defaults to sorting by relevance. " schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CustomObjectRecordsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: FilteredSearchCustomObjectRecords tags: - Custom Object Records summary: Filtered Search of Custom Object Records description: |- Returns an array of custom object records that meet the search and filter criteria. Filters can contain either an individual [comparison object](#comparison-object) or an array of [comparison objects](#comparison-object) within logical namespaces. A filter is a JSON object that has the following properties: | Name | Type | Required | Description | --------- | ------ | -------- | ----------- | ATTRIBUTE | object | no | A [comparison object](#comparison-object) specifying an attribute value condition to be met for records to match.

Examples are marked below. | $and | array | no | Array of conjunctive filter objects (logical AND) | $or | array | no | Array of conjunctive filter objects (logical OR) ##### Examples ```js { "filter": { "custom_object_fields.field_key": { "$eq": "value" } // ATTRIBUTE } } ``` ```js // $or { "filter": { "$or": [ { "custom_object_fields.field_key": { "$eq": "value" } }, // ATTRIBUTE { "external_id": { "$eq": "Record123" } } // ATTRIBUTE ] } } ``` #### Comparison Object A comparison object defines a condition a record must meet to be considered a match. The condition is based on an attribute value or object type. A comparison object is a JSON object that has the following properties: | Name | Type | Required | Description | --------- | ------------- | -------- | ----------- | FIELD_KEY | string | yes | When filtering on a custom field, they must be namedspaced with `custom_object_fields.`. ex. `custom_object_fields.field_key`

When filtering on a standard field, no namespace is required. The following fields are considered standard: `created_at`, `updated_at`, `created_by_user`, `updated_by_user`, `name`, `external_id` | OPERATOR | string | yes | [Supported operators](/documentation/custom-data/v2/searching-custom-object-records/) vary by the value's data type | VALUE | string, array | yes | The value you're filtering for #### Pagination * [Cursor pagination](/api-reference/introduction/pagination/#cursor-pagination) only. * Returns the records sorted by relevancy with page limits. Without a `sort` parameter, only the first 10,000 records are returned. With a `sort` parameter, all records are returned. #### Allowed For * Agents * End users (when an admin [configures](https://support.zendesk.com/hc/en-us/articles/6034260247066) the custom object to be accessible to end users) parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - $ref: "#/components/parameters/CustomObjectKey" - name: query in: query description: | The query parameter is used to search text-based fields for records that match specific query terms. The query can be multiple words or numbers. Every record that matches the beginning of any word or number in the query string is returned.

Fuzzy search is supported for the following text-based field types: Text fields, Multi Line Text fields, and RegExp fields.

For example, you might want to search for records related to Tesla vehicles: `query=Tesla`. In this example the API would return every record for the given custom object where any of the supported text fields contain the word 'Tesla'.

You can include multiple words or numbers in your search. For example: `query=Tesla Honda 2020`. This search phrase would be URL encoded as `query=Tesla%20Honda%202020` and return every record for the custom object for which any of the supported text fields contained 'Tesla', 'Honda', or '2020'. schema: type: string - name: sort in: query description: "One of `name`, `created_at`, `updated_at`, `-name`, `-created_at`, or `-updated_at`. The `-` denotes the sort will be descending. Defaults to sorting by relevance. " schema: type: string requestBody: content: application/json: schema: oneOf: - $ref: "#/components/schemas/CustomObjectRecordsFilteredSearchRequestBasic" - $ref: "#/components/schemas/CustomObjectRecordsFilteredSearchRequestComplex" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CustomObjectRecordsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/custom_objects/{custom_object_key}/triggers: parameters: - $ref: "#/components/parameters/CustomObjectKey" get: operationId: ListObjectTriggers tags: - Object Triggers summary: List Object Triggers description: "Lists all triggers for the specified custom object.\n\n#### Allowed\ \ For \n* Agents\n" parameters: - $ref: "#/components/parameters/TriggerActive" - $ref: "#/components/parameters/TriggerSortBy" - $ref: "#/components/parameters/TriggerSortOrder" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ObjectTriggersResponse" post: operationId: CreateObjectTrigger tags: - Object Triggers summary: Create Object Trigger description: | Creates a new object trigger for a specified object. #### Allowed For * Administrators * Agents in custom roles with the `manage_triggers` permission (Enterprise only) requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ObjectTriggerRequest" responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/ObjectTriggerResponse" /api/v2/custom_objects/{custom_object_key}/triggers/{trigger_id}: parameters: - $ref: "#/components/parameters/CustomObjectKey" - $ref: "#/components/parameters/TriggerId" get: operationId: GetObjectTrigger tags: - Object Triggers summary: Show Object Trigger description: | Returns details of a specific object trigger. #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ObjectTriggerResponse" put: operationId: UpdateObjectTrigger tags: - Object Triggers summary: Update Object Trigger description: | Updates a specified object trigger. **Note**: Updating a condition or action updates both the conditions and actions arrays, clearing all existing values of both arrays. Include all your conditions and actions when updating any condition or action. #### Allowed For * Administrators * Agents in custom roles with the `manage_triggers` permission (Enterprise only) requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ObjectTriggerRequest" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ObjectTriggerResponse" delete: operationId: DeleteObjectTrigger tags: - Object Triggers summary: Delete Object Trigger description: | Deletes a specified object trigger. #### Allowed For * Administrators * Agents in custom roles with the `manage_triggers` permission (Enterprise only) responses: "204": description: No Content response /api/v2/custom_objects/{custom_object_key}/triggers/active: parameters: - $ref: "#/components/parameters/CustomObjectKey" - $ref: "#/components/parameters/TriggerSortBy" - $ref: "#/components/parameters/TriggerSortOrder" get: operationId: ListActiveObjectTriggers tags: - Object Triggers summary: List Active Object Triggers description: | Lists all active object triggers. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Administrators * Agents in custom roles with the `manage_triggers` permission (Enterprise only) parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ObjectTriggersResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/custom_objects/{custom_object_key}/triggers/definitions: parameters: - $ref: "#/components/parameters/CustomObjectKey" get: operationId: ListObjectTriggersDefinitions tags: - Object Triggers summary: List Object Trigger Action and Condition Definitions description: "Lists the conditions and actions of all triggers for the specified\ \ custom object.\n\n#### Allowed For \n* Agents\n" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ObjectTriggerDefinitionResponse" /api/v2/custom_objects/{custom_object_key}/triggers/destroy_many: parameters: - $ref: "#/components/parameters/CustomObjectKey" - $ref: "#/components/parameters/TriggerIds" delete: operationId: DeleteManyObjectTriggers tags: - Object Triggers summary: Delete Many Object Triggers description: "Deletes the object triggers corresponding to the provided comma-separated\ \ list of ids. \n\n**Note**: You can only bulk-delete triggers associated\ \ with one object at a time, specified by the `custom_object_key` in the request.\n\ \n#### Allowed For\n\n* Administrators\n* Agents in custom roles with the\ \ `manage_triggers` permission (Enterprise only)\n\n#### Request Parameters\n\ \nThe DELETE request takes an `ids` object that lists the\nobject triggers\ \ to delete. All of the specified object trigger `ids` must be associated\ \ with a single object.\n\n| Name | Description\n| ---- | -----------\n| ids\ \ | The ids of the triggers to delete\n\n#### Example request\n\n```js\n\ {\n \"ids\": \"25,23,27,22\"\n}\n```\n" responses: "204": description: No content response /api/v2/custom_objects/{custom_object_key}/triggers/search: parameters: - $ref: "#/components/parameters/CustomObjectKey" - $ref: "#/components/parameters/TriggerSearchQuery" - $ref: "#/components/parameters/TriggerSearchFilter" - $ref: "#/components/parameters/TriggerActive" - $ref: "#/components/parameters/TriggerSort" - $ref: "#/components/parameters/TriggerSortBy" - $ref: "#/components/parameters/TriggerSortOrder" - $ref: "#/components/parameters/TriggerInclude" get: operationId: SearchObjectTriggers tags: - Object Triggers summary: Search Object Triggers description: | Returns a list of object triggers that meet your filter or search criteria. #### Pagination * Offset pagination only See [Using Offset Pagination](/api-reference/ticketing/introduction/#using-offset-pagination). #### Allowed For * Agents #### Filter Use the `filter` query parameter to filter an object trigger search by one or more attributes. For example, the following `filter` argument filters object triggers by the `title` attribute: ```json { "json": { "title": "test" } } ``` responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ObjectTriggersResponse" /api/v2/custom_objects/{custom_object_key}/triggers/update_many: parameters: - $ref: "#/components/parameters/CustomObjectKey" put: operationId: UpdateManyObjectTriggers tags: - Object Triggers summary: Update Many Object Triggers description: | Updates the position or the active status of multiple object triggers. Any additional properties are ignored. **Note**: You can only bulk-update triggers associated with one object at a time, specified by the `custom_object_key` in the request. #### Allowed For * Administrators * Agents in custom roles with the `manage_triggers` permission (Enterprise only) #### Request Parameters The PUT request expects a `triggers` object that lists the object triggers to update. All of the specified object trigger `ids` must be associated with a single object. You can specify the following properties for each object trigger you're updating: | Name | Mandatory | Description | -------- | --------- | ----------- | id | yes | The ID of the object trigger to update | position | no | The new position of the object trigger | active | no | The active status of the object trigger (true or false) #### Example Request ```js { "triggers": [ {"id": 25, "position": 3}, {"id": 23, "active": true}, {"id": 27, "position": 9, "active": false}, {"id": 22, "position": 7} ] } ``` requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ObjectTriggerBulkUpdateRequest" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ObjectTriggersResponse" /api/v2/custom_objects/limits/object_limit: get: operationId: CustomObjectsLimit tags: - Custom Objects summary: Custom Objects Limit description: |- List the current count and the limit for custom objects #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CustomObjectLimitsResponse" /api/v2/custom_objects/limits/record_limit: get: operationId: CustomObjectRecordsLimit tags: - Custom Object Records summary: Custom Object Records Limit description: |- List the current count and the limit for custom object records #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CustomObjectLimitsResponse" /api/v2/custom_roles: get: operationId: ListCustomRoles tags: - Custom Roles summary: List Custom Roles description: | #### Availability * Accounts on the Enterprise plan or above #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CustomRolesResponse" post: operationId: CreateCustomRole tags: - Custom Roles summary: Create Custom Role description: | #### Availability * Accounts on the Enterprise plan or above #### Allowed for * Administrators * Agents with the `manage_roles` permission responses: "200": description: Created response content: application/json: schema: $ref: "#/components/schemas/CustomRoleResponse" /api/v2/custom_roles/{custom_role_id}: parameters: - $ref: "#/components/parameters/CustomRoleId" get: operationId: ShowCustomRoleById tags: - Custom Roles summary: Show Custom Role description: | #### Availability * Accounts on the Enterprise plan or above #### Allowed for * Administrators * Agents with the `manage_roles` permission responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CustomRoleResponse" put: operationId: UpdateCustomRoleById tags: - Custom Roles summary: Update Custom Role description: | #### Availability * Accounts on the Enterprise plan or above #### Allowed for * Administrators Agents with the `manage_roles` permission responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CustomRoleResponse" delete: operationId: DeleteCustomRoleById tags: - Custom Roles summary: Delete Custom Role description: | #### Availability * Accounts on the Enterprise plan or above #### Allowed for * Administrators * Agents with the `manage_roles` permission responses: "204": description: No Contetnt response /api/v2/custom_status/default: put: operationId: BulkUpdateDefaultCustomStatus tags: - Custom Ticket Statuses summary: Bulk Update Default Custom Ticket Status description: | Updates the default values for many custom ticket statuses at once. #### Allowed For * Admins requestBody: content: application/json: schema: $ref: "#/components/schemas/BulkUpdateDefaultCustomStatusRequest" responses: "200": description: Updated content: application/json: schema: $ref: "#/components/schemas/BulkUpdateDefaultCustomStatusResponse" /api/v2/custom_statuses: get: operationId: ListCustomStatuses tags: - Custom Ticket Statuses summary: List Custom Ticket Statuses description: | Lists all undeleted custom ticket statuses for the account. No pagination is provided. #### Allowed For * End Users parameters: - name: status_categories in: query description: Filter the list of custom ticket statuses by a comma-separated list of status categories schema: type: string - name: active in: query description: If true, show only active custom ticket statuses. If false, show only inactive custom ticket statuses. If the filter is not used, show all custom ticket statuses schema: type: boolean - name: default in: query description: If true, show only default custom ticket statuses. If false, show only non-default custom ticket statuses. If the filter is not used, show all custom ticket statuses schema: type: boolean responses: "200": description: List custom ticket statuses content: application/json: schema: $ref: "#/components/schemas/CustomStatusesResponse" post: operationId: CreateCustomStatus tags: - Custom Ticket Statuses summary: Create Custom Ticket Status description: | Takes a `custom_status` object that specifies the custom ticket status properties to create. #### Allowed For * Admins requestBody: content: application/json: schema: $ref: "#/components/schemas/CustomStatusCreateRequest" responses: "201": description: Created content: application/json: schema: $ref: "#/components/schemas/CustomStatusResponse" /api/v2/custom_statuses/{custom_status_id}: get: operationId: ShowCustomStatus tags: - Custom Ticket Statuses summary: Show Custom Ticket Status description: | Returns the custom ticket status object. #### Allowed For * End Users parameters: - $ref: "#/components/parameters/CustomStatusId" responses: "200": description: Custom Status content: application/json: schema: $ref: "#/components/schemas/CustomStatusResponse" put: operationId: UpdateCustomStatus tags: - Custom Ticket Statuses summary: Update Custom Ticket Status description: | Takes a `custom_status` object that specifies the properties to update. #### Allowed For * Admins parameters: - $ref: "#/components/parameters/CustomStatusId" requestBody: content: application/json: schema: $ref: "#/components/schemas/CustomStatusUpdateRequest" responses: "200": description: Updated content: application/json: schema: $ref: "#/components/schemas/CustomStatusResponse" /api/v2/custom_statuses/{custom_status_id}/ticket_form_statuses: parameters: - $ref: "#/components/parameters/CustomStatusId" post: operationId: CreateTicketFormStatusesForCustomStatus tags: - Custom Ticket Statuses - Ticket Form Statuses summary: Create Ticket Form Statuses for a Custom Status description: | Creates one or many tickets form status associations for a custom status. #### Allowed For * Admins requestBody: content: application/json: schema: type: object properties: ticket_form_status: type: array items: type: object properties: ticket_form_id: type: integer description: The id of the ticket form responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketFormStatusesResponse" /api/v2/deleted_tickets: get: operationId: ListDeletedTickets tags: - Tickets summary: List Deleted Tickets description: |- Returns a maximum of 100 deleted tickets per page. See [Pagination](/api-reference/introduction/pagination/). The results includes all deleted (and not yet archived) tickets that have not yet been [scrubbed](https://support.zendesk.com/hc/en-us/articles/4408845703194#topic_fv5_w51_sdb) in the past 30 days. Archived tickets are not included in the results. See [About archived tickets](https://support.zendesk.com/hc/en-us/articles/203657756) in the Support Help Center. The tickets are ordered chronologically by created date, from oldest to newest. The first ticket listed may not be the oldest ticket in your account due to [ticket archiving](https://support.zendesk.com/hc/en-us/articles/203657756). #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents #### Rate Limit You can make 10 requests every 1 minute using this endpoint. When making requests beyond page 100, you can make 5 requests every 1 minute. The rate limiting mechanism behaves as described in [Monitoring your request activity](/api-reference/ticketing/account-configuration/usage_limits/#monitoring-your-request-activity) in the API introduction. parameters: - $ref: "#/components/parameters/TicketSortBy" - $ref: "#/components/parameters/TicketSortOrder" - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/ListDeletedTicketsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/deleted_tickets/{ticket_id}: delete: operationId: DeleteTicketPermanently tags: - Tickets summary: Delete Ticket Permanently description: |- Permanently deletes a soft-deleted ticket. See [Soft delete](https://support.zendesk.com/hc/en-us/articles/4408834005530#topic_zrm_wbj_1db) in the Zendesk GDPR docs. To soft delete a ticket, use the [Delete Ticket](#delete-ticket) endpoint. This endpoint enqueues a ticket deletion job and returns a payload with the jobs status. If the job succeeds, the ticket is permanently deleted. This operation can't be undone. This endpoint returns a `job_status` [JSON object](/api-reference/ticketing/ticket-management/job_statuses/#json-format) and queues a background job to do the work. Use the [Show Job Status](/api-reference/ticketing/ticket-management/job_statuses/#show-job-status) endpoint to check for the job's completion. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/TicketId" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" /api/v2/deleted_tickets/{ticket_id}/restore: put: operationId: RestoreDeletedTicket tags: - Tickets summary: Restore a Previously Deleted Ticket description: |- #### Allowed For * Agents parameters: - $ref: "#/components/parameters/TicketId" responses: "200": description: Empty response content: application/json: schema: type: string description: Empty response /api/v2/deleted_tickets/destroy_many: delete: operationId: BulkPermanentlyDeleteTickets tags: - Tickets summary: Delete Multiple Tickets Permanently description: |- Permanently deletes up to 100 soft-deleted tickets. See [Soft delete](https://support.zendesk.com/hc/en-us/articles/4408834005530#topic_zrm_wbj_1db) in the Zendesk GDPR docs. To soft delete tickets, use the [Bulk Delete Tickets](#bulk-delete-tickets) endpoint. This endpoint accepts a comma-separated list of up to 100 ticket ids. It enqueues a ticket deletion job and returns a payload with the jobs status. If one ticket fails to be deleted, the endpoint still attempts to delete the others. If the job succeeds, the tickets that were successfully deleted are permanently deleted. This operation can't be undone. This endpoint returns a `job_status` [JSON object](/api-reference/ticketing/ticket-management/job_statuses/#json-format) and queues a background job to do the work. Use the [Show Job Status](/api-reference/ticketing/ticket-management/job_statuses/#show-job-status) endpoint to check for the job's completion. Only a certain number of jobs can be queued or running at the same time. See [Job limit](/api-reference/introduction/rate-limits/#job-limit) for more information. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/TicketIds" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" /api/v2/deleted_tickets/restore_many: put: operationId: BulkRestoreDeletedTickets tags: - Tickets summary: Restore Previously Deleted Tickets in Bulk description: |- #### Allowed For * Agents parameters: - $ref: "#/components/parameters/TicketIds" responses: "200": description: Empty response content: application/json: schema: type: string description: Empty response /api/v2/deleted_users: get: operationId: ListDeletedUsers tags: - Users summary: List Deleted Users description: | Returns deleted users, including permanently deleted users. If the results contains permanently deleted users, the users' properties that normally contain personal data, such as `email` and `phone`, are null. The `name` property is "Permanently Deleted User". #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/DeletedUsersResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/deleted_users/{deleted_user_id}: parameters: - $ref: "#/components/parameters/DeletedUserId" get: operationId: ShowDeletedUser tags: - Users summary: Show Deleted User description: | Returns users that have been deleted but not permanently yet. See [Permanently Delete User](#permanently-delete-user). #### Allowed For: * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/DeletedUserResponse" delete: operationId: PermanentlyDeleteUser tags: - Users summary: Permanently Delete User description: | Before permanently deleting a user, you must delete the user first. See [Delete User](/api-reference/ticketing/users/users/#delete-user). WARNING: Permanently deleting a user deletes all of their information. This information is not recoverable. #### Permanent user deletion rate limit You can permanently delete 700 users every 10 minutes. The rate limiting mechanism behaves as described in [Rates Limits](/api-reference/introduction/rate-limits/#monitoring-your-request-activity) in the API introduction. Zendesk recommends that you obey the Retry-After header values. #### Allowed For * Admins and [agents in custom roles with permission](https://support.zendesk.com/hc/en-us/articles/4408882153882#topic_cxn_hig_bd) to manage end users or team members responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/DeletedUserResponse" /api/v2/deleted_users/count: get: operationId: CountDeletedUsers tags: - Users summary: Count Deleted Users description: | Returns an approximate count of deleted users, including permanently deleted users. If the count exceeds 100,000, it is updated every 24 hours. The response includes a `refreshed_at` property in a `count` object that contains a timestamp indicating when the count was last updated. **Note**: When the count exceeds 100,000, `count[refreshed_at]` may occasionally be null. This indicates that the count is being updated in the background, and `count[value]` is limited to 100,000 until the update is complete. #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CountResponse" /api/v2/deletion_schedules: get: operationId: ListDeletionSchedules tags: - Deletion Schedules summary: List Deletion Schedules description: | Lists all deletion schedules for the account. Deletion schedules are used to automatically delete data from the account after a certain period of time. #### Allowed For * Admins responses: "200": description: Success Response content: application/json: schema: type: object properties: deletion_schedules: type: array items: $ref: "#/components/schemas/DeletionSchedule" post: operationId: CreateDeletionSchedule tags: - Deletion Schedules summary: Create Deletion Schedule description: | Creates a new deletion schedule. #### Allowed For * Admins requestBody: required: true content: application/json: schema: type: object properties: deletion_schedule: $ref: "#/components/schemas/DeletionSchedule" responses: "201": description: Success Response content: application/json: schema: type: object properties: deletion_schedule: $ref: "#/components/schemas/DeletionSchedule" /api/v2/deletion_schedules/{deletion_schedule_id}: get: operationId: GetDeletionSchedule tags: - Deletion Schedules summary: Get Deletion Schedule description: | Gets a deletion schedule by its id. #### Allowed For * Admins parameters: - $ref: "#/components/parameters/DeletionScheduleId" responses: "200": description: Success Response content: application/json: schema: type: object properties: deletion_schedule: $ref: "#/components/schemas/DeletionSchedule" put: operationId: UpdateDeletionSchedule tags: - Deletion Schedules summary: Update Deletion Schedule description: | Updates a deletion schedule by its id. **Note**: Updating a condition updates the conditions array, clearing all existing values of the array. Include all your conditions when updating any condition. #### Allowed For * Admins parameters: - $ref: "#/components/parameters/DeletionScheduleId" requestBody: required: true content: application/json: schema: type: object properties: deletion_schedule: $ref: "#/components/schemas/DeletionSchedule" responses: "200": description: Success Response content: application/json: schema: type: object properties: deletion_schedule: $ref: "#/components/schemas/DeletionSchedule" delete: operationId: DeleteDeletionSchedule tags: - Deletion Schedules summary: Delete Deletion Schedule description: | Deletes a deletion schedule by its id. #### Allowed For * Admins parameters: - $ref: "#/components/parameters/DeletionScheduleId" responses: "204": description: Success Response /api/v2/dynamic_content/items: get: operationId: ListDynamicContents tags: - Dynamic Content summary: List Items description: | Returns a list of all dynamic content items for your account if accessed as an admin or agents who have permission to manage dynamic content. #### Allowed For * Admins, Agents #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/DynamicContentsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateDynamicContent tags: - Dynamic Content summary: Create Item description: | Create a new content item, with one or more variants in the item's `variants` array. See [Specifying item variants](#specifying-item-variants). The `default_locale_id` and variant `locale_id` values must be one of the locales the account has active. You can get the list with the [List Locales](/api-reference/ticketing/account-configuration/locales/#list-locales) endpoint. #### Allowed For * Admins, Agents responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/DynamicContentResponse" /api/v2/dynamic_content/items/{dynamic_content_item_id}: parameters: - $ref: "#/components/parameters/DynamicContentItemId" get: operationId: ShowDynamicContentItem tags: - Dynamic Content summary: Show Item description: | #### Allowed For * Admins, Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/DynamicContentResponse" put: operationId: UpdateDynamicContentItem tags: - Dynamic Content summary: Update Item description: | The only attribute you can change is the name. To add a variant to the item, or to update or delete the variants of the item, use the [Item Variants API](/api-reference/ticketing/ticket-management/dynamic_content_item_variants/#update-many-variants). #### Allowed For * Admins, Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/DynamicContentResponse" delete: operationId: DeleteDynamicContentItem tags: - Dynamic Content summary: Delete Item description: | #### Allowed For * Admins, Agents responses: "204": description: No Content response /api/v2/dynamic_content/items/{dynamic_content_item_id}/variants: parameters: - $ref: "#/components/parameters/DynamicContentItemId" get: operationId: DynamicContentListVariants tags: - Dynamic Content Item Variants summary: List Variants description: | Returns all the variants of the specified dynamic content item. #### Allowed For * Admins * Agents who have permission to manage dynamic content #### Pagination * Cursor pagination See [Pagination](/api-reference/introduction/pagination/). parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/DynamicContentVariantsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateDynamicContentVariant tags: - Dynamic Content Item Variants summary: Create Variant description: | You can only create one variant for each locale id. If a locale variant already exists, the request is rejected. #### Allowed For * Admins, Agents responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/DynamicContentVariantResponse" /api/v2/dynamic_content/items/{dynamic_content_item_id}/variants/{dynammic_content_variant_id}: parameters: - $ref: "#/components/parameters/DynamicContentItemId" - $ref: "#/components/parameters/DynamicContentVariantId" get: operationId: ShowDynamicContentVariant tags: - Dynamic Content Item Variants summary: Show Variant description: | #### Allowed For * Admins, Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/DynamicContentVariantResponse" put: operationId: UpdateDynamicContentVariant tags: - Dynamic Content Item Variants summary: Update Variant description: | Updates the specified variant. You don't need to include all the properties. If you just want to update content, for example, then include just that. You can't switch the active state of the default variant of an item. Similarly, you can't switch the default to false if the variant is the default. You must make another variant default instead. #### Allowed For * Admins, Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/DynamicContentVariantResponse" delete: operationId: DeleteDynamicContentVariant tags: - Dynamic Content Item Variants summary: Delete Variant description: | #### Allowed For * Admins, Agents responses: "204": description: No Content response /api/v2/dynamic_content/items/{dynamic_content_item_id}/variants/create_many: parameters: - $ref: "#/components/parameters/DynamicContentItemId" post: operationId: CreateManyDynamicContentVariants tags: - Dynamic Content Item Variants summary: Create Many Variants description: | #### Allowed For * Admins, Agents responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/DynamicContentVariantsResponse" /api/v2/dynamic_content/items/{dynamic_content_item_id}/variants/update_many: parameters: - $ref: "#/components/parameters/DynamicContentItemId" put: operationId: UpdateManyDynamicContentVariants tags: - Dynamic Content Item Variants summary: Update Many Variants description: | Updates one or more variants. See [Update Variant](/api-reference/ticketing/ticket-management/dynamic_content_item_variants/#update-variant). You must specify the variants by id in the body. To get the variant ids, see [List Variants](/api-reference/ticketing/ticket-management/dynamic_content_item_variants/#list-variants). #### Allowed For * Admins, Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/DynamicContentVariantsResponse" /api/v2/dynamic_content/items/show_many: get: operationId: ShowManyDynamicContents tags: - Dynamic Content summary: Show Many Items description: | #### Stability * Development #### Allowed For * Admins, Agents parameters: - name: identifiers in: query description: Identifiers for the dynamic contents schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/DynamicContentsResponse" /api/v2/email_notifications: parameters: - $ref: "#/components/parameters/EmailNotificationsFilter" - $ref: "#/components/parameters/IncrementalPage" - $ref: "#/components/parameters/Sort" get: operationId: ListEmailNotifications tags: - Email Notifications summary: List Email Notifications description: | #### Allowed For * Agents #### Filters * By notification: `api/v2/email_notifications.json?filter[notification_id]=7824075373693` * By comment: `api/v2/email_notifications.json?filter[comment_id]=7824075373565` * By ticket: `api/v2/email_notifications.json?filter[ticket_id]=623` #### Pagination By default, a maximum of 100 email notifications are included per page. Use cursor-based pagination parameters (`page[after]` and `page[before]`) to navigate the records (can't be used together in the same request). See [Pagination](/api-reference/introduction/pagination/) for more details. * Limit items per-page: `api/v2/email_notifications.json?page[size]=25` * Retrieve next page: `api/v2/email_notifications.json?page[size]=25&page[after]=xxx` * Retrieve previous page: `api/v2/email_notifications.json?page[size]=25&page[before]=yyy` The values `xxx` and `yyy` are placeholder values that represent cursors. #### Sorting By default, email notifications are sorted by creation time (newest first). The query parameter is not supported for this endpoint. * By creation time (oldest first): `api/v2/email_notifications.json?sort=created_at` * By creation time (newest first): `api/v2/email_notifications.json?sort=-created_at` * By modification time (recently updated first): `api/v2/email_notifications.json?sort=updated_at` * By modification time (recently updated last): `api/v2/email_notifications.json?sort=-updated_at` parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/EmailNotificationsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/email_notifications/{notification_id}: parameters: - $ref: "#/components/parameters/NotificationId" get: operationId: ShowEmailNotification tags: - Email Notifications summary: Show Email Notification description: | Shows details on an email notification. You can get the value of the `notification_id` parameter by listing the ticket's outbound emails. #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/EmailNotificationResponse" /api/v2/email_notifications/show_many: parameters: - $ref: "#/components/parameters/NotificationIds" - $ref: "#/components/parameters/CommentIds" - $ref: "#/components/parameters/EmailNotificationsByTicketIds" get: operationId: ShowManyEmailNotifications tags: - Email Notifications summary: Show Many Email Notifications description: | Shows details of many email notifications. Allows you to query by providing a list of notifications, comments, or tickets IDs. #### Allowed For * Agents #### Filters * By notification: `?ids=8433702508541,8433348111869` * By comment: `?comment_ids=8433348111741,8433544226045,8433702508413` * By ticket: `?ticket_ids=730,723` responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/EmailNotificationResponse" /api/v2/group_memberships: get: operationId: ListGroupMemberships tags: - Group Memberships summary: List Memberships description: | #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For: * Agents parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/GroupMembershipsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateGroupMembership tags: - Group Memberships summary: Create Membership description: | Assigns an agent to a given group. #### Allowed For * Admins * Agents assigned to a custom role with permissions to manage group memberships (Enterprise only) requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/GroupMembershipRequest" responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/GroupMembershipResponse" /api/v2/group_memberships/{group_membership_id}: parameters: - $ref: "#/components/parameters/GroupMembershipId" get: operationId: ShowGroupMembershipById tags: - Group Memberships summary: Show Membership description: | The 'id' is the group membership id, not a group id. #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/GroupMembershipResponse" delete: operationId: DeleteGroupMembership tags: - Group Memberships summary: Delete Membership description: | Immediately removes a user from a group and schedules a job to unassign all working tickets that are assigned to the given user and group combination. #### Allowed For * Admins * Agents assigned to a custom role with permissions to manage group memberships (Enterprise only) responses: "204": description: No content response /api/v2/group_memberships/assignable: get: operationId: ListAssignableGroupMemberships tags: - Group Memberships summary: List Assignable Memberships description: | Returns a maximum of 100 group memberships per page. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For: * Agents parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/GroupMembershipsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/group_memberships/create_many: post: operationId: GroupMembershipBulkCreate tags: - Group Memberships summary: Bulk Create Memberships description: | Assigns up to 100 agents to given groups. #### Allowed For * Admins * Agents assigned to a custom role with permissions to manage group memberships (Enterprise only) #### Response This endpoint returns a `job_status` [JSON object](/api-reference/ticketing/ticket-management/job_statuses/#json-format) and queues a background job to do the work. Use the [Show Job Status](/api-reference/ticketing/ticket-management/job_statuses/#show-job-status) endpoint to check for the job's completion. responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" /api/v2/group_memberships/destroy_many: delete: operationId: GroupMembershipBulkDelete tags: - Group Memberships summary: Bulk Delete Memberships description: | Immediately removes users from groups and schedules a job to unassign all working tickets that are assigned to the given user and group combinations. #### Allowed For * Admins * Agents assigned to a custom role with permissions to manage group memberships (Enterprise only) parameters: - name: ids in: query description: Id of the group memberships to delete. Comma separated schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" /api/v2/group_slas/policies: get: operationId: ListGroupSLAPolicies tags: - Group SLA Policies summary: List Group SLA Policies description: | #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/GroupSLAPoliciesResponse" post: operationId: CreateGroupSLAPolicy tags: - Group SLA Policies summary: Create Group SLA Policy description: | #### Allowed For * Admins responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/GroupSLAPolicyResponse" /api/v2/group_slas/policies/{group_sla_policy_id}: parameters: - $ref: "#/components/parameters/GroupSLAPolicyId" get: operationId: ShowGroupSLAPolicy tags: - Group SLA Policies summary: Show Group SLA Policy description: | #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/GroupSLAPolicyResponse" put: operationId: UpdateGroupSLAPolicy tags: - Group SLA Policies summary: Update Group SLA Policy description: | Updates the specified policy. #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/GroupSLAPolicyResponse" delete: operationId: DeleteGroupSLAPolicy tags: - Group SLA Policies summary: Delete Group SLA Policy description: | #### Allowed For * Admins responses: "204": description: No Content response /api/v2/group_slas/policies/definitions: get: operationId: RetrieveGroupSLAPolicyFilterDefinitionItems tags: - Group SLA Policies summary: Retrieve Supported Filter Definition Items description: | #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/GroupSLAPolicyFilterDefinitionResponse" /api/v2/group_slas/policies/reorder: put: operationId: ReorderGroupSLAPolicies tags: - Group SLA Policies summary: Reorder Group SLA Policies description: | #### Allowed For * Admins parameters: - name: group_sla_policy_ids in: query description: The ids of the Group SLA policies to reorder schema: type: array items: type: string responses: "200": description: Success response content: application/json: schema: type: string description: Empty response /api/v2/groups: get: operationId: ListGroups tags: - Groups summary: List Groups description: | #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Admins * Agents parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - $ref: "#/components/parameters/ExcludeDeleted" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/GroupsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateGroup tags: - Groups summary: Create Group description: | #### Allowed For * Admins * Agents assigned to a custom role with permissions to manage groups (Enterprise only) requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/GroupCreateRequest" responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/GroupResponse" /api/v2/groups/{group_id}: parameters: - $ref: "#/components/parameters/GroupId" get: operationId: ShowGroupById tags: - Groups summary: Show Group description: | #### Allowed For * Admins * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/GroupResponse" put: operationId: UpdateGroup tags: - Groups summary: Update Group description: | #### Allowed For * Admins requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/GroupUpdateRequest" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/GroupResponse" delete: operationId: DeleteGroup tags: - Groups summary: Delete Group description: | #### Allowed For * Admins * Agents assigned to a custom role with permissions to manage groups (Enterprise only) responses: "204": description: No content response /api/v2/groups/assignable: get: operationId: ListAssignableGroups tags: - Groups summary: List Assignable Groups description: | #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Admins * Agents parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/GroupsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/groups/count: get: operationId: CountGroups tags: - Groups summary: Count Groups description: | 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 responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/GroupsCountObject" /api/v2/imports/tickets: post: operationId: TicketImport tags: - Ticket Import summary: Ticket Import description: |- #### Allowed For * Admins parameters: - $ref: "#/components/parameters/ArchiveImmediately" requestBody: content: application/json: schema: $ref: "#/components/schemas/TicketImportRequest" responses: "201": description: Successfully created content: application/json: schema: $ref: "#/components/schemas/TicketResponse" /api/v2/imports/tickets/create_many: post: operationId: TicketBulkImport tags: - Ticket Import summary: Ticket Bulk Import description: |- Accepts an array of up to 100 ticket objects. #### Allowed For * Admins parameters: - $ref: "#/components/parameters/ArchiveImmediately" requestBody: content: application/json: schema: $ref: "#/components/schemas/TicketBulkImportRequest" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" /api/v2/incremental/{incremental_resource}/sample: parameters: - $ref: "#/components/parameters/IncrementalUnixTime" - $ref: "#/components/parameters/IncrementalResource" get: operationId: IncrementalSampleExport tags: - Incremental Export summary: Incremental Sample Export description: | 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". responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TimeBasedExportIncrementalTicketsResponse" /api/v2/incremental/organizations: parameters: - $ref: "#/components/parameters/IncrementalUnixTime" - $ref: "#/components/parameters/IncrementalPage" get: operationId: IncrementalOrganizationExport tags: - Incremental Export summary: Incremental Organization Export description: | #### Allowed For * Admins #### Sideloading See [Organizations sideloads](/documentation/ticketing/using-the-zendesk-api/side_loading/#supported-endpoints). responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ExportIncrementalOrganizationsResponse" /api/v2/incremental/routing/attribute_values: get: operationId: IncrementalSkilBasedRoutingAttributeValuesExport tags: - Incremental Skill Based Routing summary: Incremental Attributes Values Export description: | 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](#pagination). responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/IncrementalSkillBasedRouting" /api/v2/incremental/routing/attributes: get: operationId: IncrementalSkilBasedRoutingAttributesExport tags: - Incremental Skill Based Routing summary: Incremental Attributes Export description: | 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](#pagination). responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/IncrementalSkillBasedRouting" /api/v2/incremental/routing/instance_values: get: operationId: IncrementalSkilBasedRoutingInstanceValuesExport tags: - Incremental Skill Based Routing summary: Incremental Instance Values Export description: "Returns a stream of changes that occurred on routing instance\ \ values. Changes are grouped by `attribute_value_id`,\nwith associate type\ \ events listed alongside unassociate type events based on the unassociate\ \ event\u2019s timestamp.\n\n#### Allowed For\n\n* Admins\n\n#### Parameters\n\ \nOptional\n\n| Name | Type | Comment\n| ------ | ------ | -------\n|\ \ 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](#pagination).\n" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/IncrementalSkillBasedRouting" /api/v2/incremental/ticket_events: parameters: - $ref: "#/components/parameters/IncrementalUnixTime" get: operationId: IncrementalTicketEvents tags: - Incremental Export summary: Incremental Ticket Event Export description: | Returns a stream of changes that occurred on tickets, excluding events occuring within one minute of the request. 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: - [Exporting ticket events](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#exporting-ticket-events) in [Using the Incremental Exports API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api) - [Time-based incremental exports](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#time-based-incremental-exports) in [Using the Incremental Exports API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api) 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: ```js "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": "<div class="zd-comment"><p dir="auto">This is a comment</p>", "public": true, "attachments": [], "audit_id": 91048994468, "created_at": "2009-06-25T10:15:18Z", "event_type": "Comment" }, ... ], ... ``` responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ExportIncrementalTicketEventsResponse" /api/v2/incremental/ticket_metric_events: get: operationId: ListTicketMetricEvents tags: - Ticket Metric Events summary: List Ticket Metric Events description: |- Returns ticket metric events that occurred on or after the start time. Cursor pagination returns a maximum of 100 records per page. Events are listed in chronological order. If the results are not paginated, events will be returned as a time-based incremental export. See [Time-based incremental exports](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#time-based-incremental-exports). #### Pagination * Cursor pagination See [Pagination](/api-reference/introduction/pagination/). #### Allowed For * Admins parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - name: start_time in: query description: "The Unix UTC epoch time of the oldest event you're interested in. Example: 1332034771." required: true schema: type: integer - name: include_changes in: query description: This optional parameter enhances incremental data retrieval, delivering a consistent and accurate representation of data changes. schema: type: boolean responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/TicketMetricEventsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/incremental/tickets: parameters: - $ref: "#/components/parameters/IncrementalUnixTime" get: operationId: IncrementalTicketExportTime tags: - Incremental Export summary: Incremental Ticket Export, Time Based description: | Returns the tickets that changed since the start time. For more information, see [Exporting tickets](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#exporting-tickets) in [Using the Incremental Exports API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api). This endpoint supports time-based incremental exports. For more information, see [Time-based incremental exports](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#time-based-incremental-exports) in [Using the Incremental Exports API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api). You can also return tickets using cursor-based pagination. See [Incremental Ticket Export, Cursor Based](#incremental-ticket-export-cursor-based). The results include tickets that were updated by the system. See [Excluding system-updated tickets](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#excluding-system-updated-tickets-time-based-exports) in [Using the Incremental Exports API](/documentation/ticketing/managing-tickets/using-the-incremental-export-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](#incremental-ticket-event-export). 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](/documentation/ticketing/using-the-zendesk-api/side_loading/#supported-endpoints). For performance reasons, `last_audits` sideloads aren't supported. responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TimeBasedExportIncrementalTicketsResponse" /api/v2/incremental/tickets/cursor: parameters: - $ref: "#/components/parameters/IncrementalUnixTime" - $ref: "#/components/parameters/IncrementalCursor" get: operationId: IncrementalTicketExportCursor tags: - Incremental Export summary: Incremental Ticket Export, Cursor Based description: | Returns the tickets that changed since the start time. For more information, see [Exporting tickets](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#exporting-tickets) in [Using the Incremental Exports API](/documentation/ticketing/managing-tickets/using-the-incremental-export-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](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#cursor-based-incremental-exports) in [Using the Incremental Exports API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api). #### Allowed For * Admins #### Sideloading See [Tickets sideloads](/documentation/ticketing/using-the-zendesk-api/side_loading/#supported-endpoints). For performance reasons, `last_audits` sideloads aren't supported. responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CursorBasedExportIncrementalTicketsResponse" /api/v2/incremental/users: parameters: - $ref: "#/components/parameters/IncrementalUnixTime" - $ref: "#/components/parameters/IncrementalPage" get: operationId: IncrementalUserExportTime tags: - Incremental Export summary: Incremental User Export, Time Based description: | #### Allowed For * Admins #### Sideloading See [Users sideloads](/documentation/ticketing/using-the-zendesk-api/side_loading/#supported-endpoints). responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TimeBasedExportIncrementalUsersResponse" /api/v2/incremental/users/cursor: parameters: - $ref: "#/components/parameters/IncrementalUnixTime" - $ref: "#/components/parameters/IncrementalCursor" - $ref: "#/components/parameters/IncrementalPage" get: operationId: IncrementalUserExportCursor tags: - Incremental Export summary: Incremental User Export, Cursor Based description: | #### Allowed For * Admins #### Sideloading See [Users sideloads](/documentation/ticketing/using-the-zendesk-api/side_loading/#supported-endpoints). responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CursorBasedExportIncrementalUsersResponse" /api/v2/job_statuses: get: operationId: ListJobStatuses tags: - Job Statuses summary: List Job Statuses description: | 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](/api-reference/introduction/pagination/). parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success Response content: application/json: schema: $ref: "#/components/schemas/JobStatusesResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/job_statuses/{job_status_id}: parameters: - $ref: "#/components/parameters/JobStatusId" get: operationId: ShowJobStatus tags: - Job Statuses summary: Show Job Status description: | Shows the status of a background job. #### Allowed For: * Agents responses: "200": description: Success Response content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" /api/v2/job_statuses/show_many: get: operationId: ShowManyJobStatuses tags: - Job Statuses summary: Show Many Job Statuses description: | Accepts a comma-separated list of job status ids. #### Allowed For: * Agents parameters: - name: ids in: query description: Comma-separated list of job status ids. required: true schema: type: string responses: "200": description: Success Response content: application/json: schema: $ref: "#/components/schemas/JobStatusesResponse" /api/v2/locales: get: operationId: ListLocales tags: - Locales summary: List Locales description: | 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](/api-reference/ticketing/account-configuration/account_settings/#update-account-settings) endpoint. #### Allowed For * Anyone responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/LocalesResponse" /api/v2/locales/{locale_id}: parameters: - $ref: "#/components/parameters/LocaleId" get: operationId: ShowLocaleById tags: - Locales summary: Show Locale description: | #### Allowed For * Anyone responses: "200": description: Success Response content: application/json: schema: $ref: "#/components/schemas/LocaleResponse" /api/v2/locales/agent: get: operationId: ListLocalesForAgent tags: - Locales summary: List Locales for Agent description: | Lists the translation locales that have been localized for agents on a specific account. #### Allowed For * Anyone responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/LocalesResponse" /api/v2/locales/current: get: operationId: ShowCurrentLocale tags: - Locales summary: Show Current Locale description: | This works like [Show Locale](#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 responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/LocaleResponse" /api/v2/locales/detect_best_locale: get: operationId: DetectBestLocale tags: - Locales summary: Detect Best Language for User description: | #### Allowed For * Anyone responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/LocaleResponse" /api/v2/locales/public: get: operationId: ListAvailablePublicLocales tags: - Locales summary: List Available Public Locales description: | Lists the translation locales that are available to all accounts. #### Allowed For * Anyone responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/LocalesResponse" /api/v2/macros: get: operationId: ListMacros tags: - Macros summary: List Macros description: | 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](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - $ref: "#/components/parameters/MacroInclude" - $ref: "#/components/parameters/MacroAccess" - $ref: "#/components/parameters/MacroActive" - $ref: "#/components/parameters/MacroCategory" - $ref: "#/components/parameters/MacroGroupId" - $ref: "#/components/parameters/MacroOnlyViewable" - $ref: "#/components/parameters/MacroSortBy" - $ref: "#/components/parameters/MacroSortOrder" responses: "200": description: Success Response content: application/json: schema: $ref: "#/components/schemas/MacrosResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateMacro tags: - Macros summary: Create Macro description: | #### Allowed For * Agents requestBody: content: application/json: schema: type: object properties: macro: $ref: "#/components/schemas/MacroInput" responses: "200": description: OK content: application/json: schema: type: object properties: macro: $ref: "#/components/schemas/MacroObject" /api/v2/macros/{macro_id}: parameters: - $ref: "#/components/parameters/MacroId" get: operationId: ShowMacro tags: - Macros summary: Show Macro description: | #### Allowed For * Agents responses: "200": description: Success Response content: application/json: schema: $ref: "#/components/schemas/MacroResponse" put: operationId: UpdateMacro tags: - Macros summary: Update Macro description: | #### Allowed For * Agents requestBody: content: application/json: schema: type: object properties: macro: $ref: "#/components/schemas/MacroInput" responses: "200": description: OK content: application/json: schema: type: object properties: macro: $ref: "#/components/schemas/MacroObject" delete: operationId: DeleteMacro tags: - Macros summary: Delete Macro description: | #### Allowed For * Agents, with restrictions applying on certain actions responses: "204": description: No Content /api/v2/macros/{macro_id}/apply: parameters: - $ref: "#/components/parameters/MacroId" get: operationId: ShowChangesToTicket tags: - Macros summary: Show Changes to Ticket description: | Returns the changes the macro would make to a ticket. It doesn't actually change a ticket. You can use the response data in a subsequent API call to the [Tickets](/api-reference/ticketing/tickets/tickets/) endpoint to update the ticket. The response includes only the ticket fields that would be changed by the macro. To get the full ticket object after the macro is applied, see [Show Ticket After Changes](#show-ticket-after-changes). #### Allowed For * Agents responses: "200": description: Success Response content: application/json: schema: $ref: "#/components/schemas/MacroApplyTicketResponse" /api/v2/macros/{macro_id}/attachments: parameters: - $ref: "#/components/parameters/MacroId" get: operationId: ListMacroAttachments tags: - Macros summary: List Macro Attachments description: | Lists the attachments associated with a macro. #### Allowed For * Agents responses: "200": description: Success Response content: application/json: schema: $ref: "#/components/schemas/MacroAttachmentsResponse" post: operationId: CreateAssociatedMacroAttachment tags: - Macros summary: Create Macro Attachment description: | Allows an attachment to be uploaded and associated with a macro at the same time. **Note:** A macro can be associated with up to five attachments. #### Allowed For * Agents responses: "201": description: Success Response content: application/json: schema: $ref: "#/components/schemas/MacroAttachmentResponse" /api/v2/macros/actions: get: operationId: ListMacrosActions tags: - Macros summary: List Supported Actions for Macros description: | #### Allowed For * Agents responses: "200": description: Success Response content: application/json: schema: type: object properties: actions: type: array items: type: object additionalProperties: true /api/v2/macros/active: get: operationId: ListActiveMacros tags: - Macros summary: List Active Macros description: | Lists all active shared and personal macros available to the current user. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/MacroInclude" - $ref: "#/components/parameters/MacroAccess" - $ref: "#/components/parameters/MacroCategory" - $ref: "#/components/parameters/MacroGroupId" - $ref: "#/components/parameters/MacroSortBy" - $ref: "#/components/parameters/MacroSortOrder" responses: "200": description: Success Response content: application/json: schema: $ref: "#/components/schemas/MacrosResponse" /api/v2/macros/attachments: post: operationId: CreateMacroAttachment tags: - Macros summary: Create Unassociated Macro Attachment description: | 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 responses: "201": description: Created Response content: application/json: schema: $ref: "#/components/schemas/MacroAttachmentResponse" /api/v2/macros/attachments/{attachment_id}: parameters: - $ref: "#/components/parameters/AttachmentId" get: operationId: ShowMacroAttachment tags: - Macros summary: Show Macro Attachment description: | Shows the properties of the specified macro attachment. #### Allowed For * Agents responses: "200": description: Success Response content: application/json: schema: $ref: "#/components/schemas/MacroAttachmentResponse" /api/v2/macros/categories: get: operationId: ListMacroCategories tags: - Macros summary: List Macro Categories description: | Lists all macro categories available to the current user. #### Allowed For * Agents responses: "200": description: Success Response content: application/json: schema: $ref: "#/components/schemas/MacroCategoriesResponse" /api/v2/macros/definitions: get: operationId: ListMacroActionDefinitions tags: - Macros summary: List Macro Action Definitions description: | 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](/documentation/ticketing/reference-guides/actions-reference). #### Allowed For * Agents responses: "200": description: Success Response content: application/json: schema: type: object properties: definitions: type: object properties: actions: type: array items: type: object additionalProperties: true /api/v2/macros/destroy_many: delete: operationId: DeleteManyMacros tags: - Macros summary: Bulk Delete Macros description: | Deletes the macros corresponding to the provided comma-separated list of IDs. #### Allowed For * Agents parameters: - name: ids in: query description: The IDs of the macros to delete required: true schema: type: array items: type: integer responses: "204": description: No Content /api/v2/macros/new: parameters: - $ref: "#/components/parameters/MacroIdQuery" - name: ticket_id in: query description: The ID of the ticket from which to build a macro replica required: true schema: type: integer get: operationId: ShowDerivedMacro tags: - Macros summary: Show Macro Replica description: | 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 responses: "200": description: Success Response content: application/json: schema: $ref: "#/components/schemas/MacroResponse" /api/v2/macros/search: parameters: - $ref: "#/components/parameters/MacroInclude" - $ref: "#/components/parameters/MacroAccess" - $ref: "#/components/parameters/MacroActive" - $ref: "#/components/parameters/MacroCategory" - $ref: "#/components/parameters/MacroGroupId" - $ref: "#/components/parameters/MacroOnlyViewable" - $ref: "#/components/parameters/MacroSearchSortBy" - $ref: "#/components/parameters/MacroSortOrder" - $ref: "#/components/parameters/MacroQuery" get: operationId: SearchMacro tags: - Macros summary: Search Macros description: | #### Pagination * Offset pagination only See [Using Offset Pagination](/api-reference/ticketing/introduction/#using-offset-pagination). #### Allowed For * Agents responses: "200": description: Success Response content: application/json: schema: $ref: "#/components/schemas/MacrosResponse" /api/v2/macros/update_many: put: operationId: UpdateManyMacros tags: - Macros summary: Update Many Macros description: | Updates the provided macros with the specified changes. #### Allowed For * Agents requestBody: content: application/json: schema: $ref: "#/components/schemas/MacroUpdateManyInput" responses: "200": description: Success Response content: application/json: schema: $ref: "#/components/schemas/MacrosResponse" /api/v2/oauth/clients: get: operationId: ListOAuthClients tags: - OAuth Clients summary: List Clients description: | #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Admins parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/OAuthClientsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateOAuthClient tags: - OAuth Clients summary: Create Client description: | #### Allowed For * Admins responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/OauthClientResponse" /api/v2/oauth/clients/{oauth_client_id}: parameters: - $ref: "#/components/parameters/OAuthClientId" get: operationId: ShowClient tags: - OAuth Clients summary: Show Client description: | #### Allowed for * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/OauthClientResponse" put: operationId: UpdateClient tags: - OAuth Clients summary: Update Client description: | #### Allowed for * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/OauthClientResponse" delete: operationId: DeleteClient tags: - OAuth Clients summary: Delete Client description: | #### Allowed for * Admins responses: "204": description: No content response /api/v2/oauth/clients/{oauth_client_id}/generate_secret: parameters: - $ref: "#/components/parameters/OAuthClientId" put: operationId: ClientGenerateSecret tags: - OAuth Clients summary: Generate Secret description: | #### Allowed for * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/OauthClientResponse" /api/v2/oauth/global_clients: get: operationId: ListGlobalOAuthClients tags: - Global Clients summary: List Global OAuth Clients description: | Returns all the global OAuth clients that users on your account have authorized. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Admins parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/GlobalClientsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/oauth/tokens: parameters: - $ref: "#/components/parameters/OAuthClientIdQuery" - $ref: "#/components/parameters/OAuthGlobalClientIdQuery" - $ref: "#/components/parameters/OAuthAllTokensQuery" get: operationId: ListOAuthTokens tags: - OAuth Tokens summary: List Tokens description: | Returns the properties of the tokens for the current user. Admins can view OAuth token properties for all users using the [all](/api-reference/ticketing/oauth/oauth_tokens/#parameters) parameter. The [client_id](/api-reference/ticketing/oauth/oauth_tokens/#parameters) parameter can be included to filter that list by a global or local OAuth client ID. For security reasons, only the first 10 characters of each access token are included. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Admins parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/OAuthTokensResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateOAuthToken tags: - OAuth Tokens summary: Create Token description: | Returns an OAuth access token with a specified [scope](#scopes). Refresh tokens aren't used. An access token doesn't expire but it can be [revoked](#revoke-token). For a tutorial, see [Creating and using OAuth tokens with the API](/documentation/ticketing/working-with-oauth/creating-and-using-oauth-tokens-with-the-api/). **Note**: For OAuth authorization code, use the [Create Token for Grant Type](/api-reference/ticketing/oauth/grant_type_tokens/#create-token-for-grant-type) endpoint. The two APIs don't share the same path, JSON format, or request parameters. However, both APIs return access tokens that can be used to [authenticate API requests](/api-reference/ticketing/introduction/#oauth-access-token). #### Allowed For * Admins #### Request parameters The POST request takes a "token" object that contains an OAuth client's resource id and scopes. | Name | Type | Description | --------- | ------- | -------------------------------------------------- | client_id | integer | The resource `id` of an [OAuth client](/api-reference/ticketing/oauth/oauth_clients/#json-format) (not the client's unique identifier). For the ids, see [List Clients](/api-reference/ticketing/oauth/oauth_clients/#list-clients) | scopes | array | Valid scopes for the token. See [Scopes](#scopes) below #### Scopes The **scopes** parameter defines whether requests authenticated with the token can post, put, and delete data, or only get data. **Note**: Don't confuse the **scopes** parameter (plural) with the **scope** parameter (singular) for [grant-type tokens](/api-reference/ticketing/oauth/grant_type_tokens/). The **scopes** parameter is an array of strings, each specifying a resource name and an access setting. Access is either "read" or "write". If you don't specify a resource, access to all resources is assumed. If you don't specify the access, read and write access are assumed. The syntax is as follows: `"scopes": [resource:scope, ...]` where `resource` is optional. **Examples** `"scopes": ["read"]` `"scopes": ["tickets:read"]` To give read and write access to a resource, specify both scopes: `"scopes": ["users:read", "users:write"]` To give write access only to one resource and read access to everything else: `"scopes": ["organizations:write", "read"]` **Note**: The endpoint returns an access token even if you specify an invalid scope. Any request you make with the token will return a "Forbidden" error. **Available scopes** * `read` - gives access to GET endpoints. Includes permission to sideload related resources * `write` - gives access to POST, PUT, and DELETE endpoints * `impersonate` - allows Zendesk Support admins to make requests on behalf of end users. See [Making API requests on behalf of end users](/documentation/ticketing/using-the-zendesk-api/making-api-requests-on-behalf-of-end-users/) **Resources that can be scoped** * tickets * users * auditlogs (read only) * organizations * hc * apps * triggers * automations * targets * webhooks * macros * requests * satisfaction_ratings * dynamic_content * any_channel (write only) * web_widget (write only) responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/OAuthTokenResponse" /api/v2/oauth/tokens/{oauth_token_id}: parameters: - $ref: "#/components/parameters/OAuthTokenId" get: operationId: ShowToken tags: - OAuth Tokens summary: Show Token description: | Returns the properties of the specified token. For security reasons, only the first 10 characters of the access token are included. In the first endpoint, `id` is a token id, not the full token. In the second endpoint, include an `Authorization: Bearer` header with the full token to get its associated properties. Example: ```sh curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens/current.json \ -H 'Authorization: Bearer ${authToken}' \ -v -u {email_address}/token:{api_token} ``` #### Allowed for * Admins, Agents, End Users responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/OAuthTokenResponse" delete: operationId: RevokeOAuthToken tags: - OAuth Tokens summary: Revoke Token description: | #### Allowed for * Admins, Agents, End Users responses: "204": description: No content response /api/v2/object_layouts/{object_type}/essentials_card: parameters: - $ref: "#/components/parameters/EssentialsCardKey" get: operationId: ShowEssentialsCard tags: - Essentials Card summary: Show Essentials Card description: | Gets the essentials card for an object type. #### Allowed For * Admins and agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/EssentialsCardResponse" put: operationId: UpdateEssentialsCard tags: - Essentials Card summary: Update Essentials Card description: | Updates the essentials card for an object type. #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/EssentialsCardResponse" delete: operationId: DeleteEssentialsCard tags: - Essentials Card summary: Delete Essentials Card description: | Delete the essentials card for an object type. #### Allowed For * Admins and agents responses: "204": description: Success response /api/v2/object_layouts/essentials_cards: get: operationId: ShowEssentialsCards tags: - Essentials Card summary: List of Essentials Cards description: | Gets the list of essentials cards. #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/EssentialsCardsResponse" /api/v2/organization_fields: get: operationId: ListOrganizationFields tags: - Organization Fields summary: List Organization Fields description: | Returns a list of custom organization fields in your account. Fields are returned in the order that you specify in your organization fields configuration in Zendesk Support. Clients should cache this resource for the duration of their API usage and map the key for each organization field to the values returned under the `organization_fields` attribute on the [organization](/api-reference/ticketing/organizations/organizations/) resource. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/OrganizationFieldsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateOrganizationField tags: - Organization Fields summary: Create Organization Field description: | Creates any of the following custom field types: * text (default when no "type" is specified) * textarea * checkbox * date * integer * decimal * regexp * dropdown * lookup * multiselect See [About custom field types](https://support.zendesk.com/hc/en-us/articles/203661866) in Zendesk help. #### Allowed For * Admins responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/OrganizationFieldResponse" /api/v2/organization_fields/{organization_field_id}: parameters: - $ref: "#/components/parameters/OrganizationFieldId" get: operationId: ShowOrganizationField tags: - Organization Fields summary: Show Organization Field description: | #### Allowed for * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/OrganizationFieldResponse" put: operationId: UpdateOrganizationField tags: - Organization Fields summary: Update Organization Field description: | #### Updating a Dropdown (Tagger) or Multiselect Field Dropdown and multiselect fields return an array of `custom_field_options` which specify the name, value, and order of dropdown or multiselect options. When updating a dropdown or multiselect field, note the following information: - All options must be passed on update. Options that are not passed will be removed. As a result, these values will be removed from any organizations - To create a new option, pass a null `id` along with the `name` and `value` - To update an existing option, pass its `id` along with the `name` and `value` - To reorder an option, reposition it in the `custom_field_options` array relative to the other options - To remove an option, omit it from the list of options upon update #### Example Request ```bash curl https://{subdomain}.zendesk.com/api/v2/organization_fields/{organization_field_id}.json \ -H "Content-Type: application/json" -X PUT \ -d '{"organization_field": {"custom_field_options": [{"id": 124, "name": "Option 2", "value": "option_2"}, {"id": 123, "name": "Option 1", "value": "option_1"}, {"id": 125, "name": "Option 3", "value": "option_3"}]}}' \ -v -u {email_address}/token:{api_token} ``` #### Allowed for * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/OrganizationFieldResponse" delete: operationId: DeleteOrganizationField tags: - Organization Fields summary: Delete Organization Field description: | #### Allowed for * Admins responses: "204": description: No Content response /api/v2/organization_fields/reorder: put: operationId: ReorderOrganizationField tags: - Organization Fields summary: Reorder Organization Field description: | #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: type: string description: Empty response /api/v2/organization_memberships: get: operationId: ListOrganizationMemberships tags: - Organization Memberships summary: List Memberships description: | Returns a list of organization memberships for the account, user or organization in question. **Note**: When returning organization memberships for a user, organization memberships are sorted with the default organization first, and then by organization name. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For - Agents - End users parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/OrganizationMembershipsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateOrganizationMembership tags: - Organization Memberships summary: Create Membership description: | Assigns a user to a given organization. Returns an error with status 422 if the user is already assigned to the organization. #### Allowed For * Admins * Agents when creating a new organization membership for an end user responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/OrganizationMembershipResponse" /api/v2/organization_memberships/{organization_membership_id}: parameters: - $ref: "#/components/parameters/OrganizationMembershipId" get: operationId: ShowOrganizationMembershipById tags: - Organization Memberships summary: Show Membership description: | #### Allowed for * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/OrganizationMembershipResponse" delete: operationId: DeleteOrganizationMembership tags: - Organization Memberships summary: Delete Membership description: | Immediately removes a user from an organization and schedules a job to unassign all working tickets currently assigned to the user and organization combination. The `organization_id` of the unassigned tickets is set to null. #### Allowed for * Admins * Agents when deleting an organization membership for an end user responses: "204": description: No Content response /api/v2/organization_memberships/create_many: post: operationId: CreateManyOrganizationMemberships tags: - Organization Memberships summary: Create Many Memberships description: | Accepts an array of up to 100 organization membership objects. This endpoint returns a `job_status` [JSON object](/api-reference/ticketing/ticket-management/job_statuses/#json-format) and queues a background job to do the work. Use the [Show Job Status](/api-reference/ticketing/ticket-management/job_statuses/#show-job-status) endpoint to check for the job's completion. Only a certain number of jobs can be queued or running at the same time. See [Job limit](/api-reference/introduction/rate-limits/#job-limit) for more information. #### Allowed For * Admins * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" /api/v2/organization_memberships/destroy_many: delete: operationId: DeleteManyOrganizationMemberships tags: - Organization Memberships summary: Bulk Delete Memberships description: | Immediately removes a user from an organization and schedules a job to unassign all working tickets currently assigned to the user and organization combination. The `organization_id` of the unassigned tickets is set to null. #### Response This endpoint returns a `job_status` [JSON object](/api-reference/ticketing/ticket-management/job_statuses/#json-format) and queues a background job to do the work. Use the [Show Job Status](/api-reference/ticketing/ticket-management/job_statuses/#show-job-status) endpoint to check for the job's completion. Only a certain number of jobs can be queued or running at the same time. See [Job limit](/api-reference/introduction/rate-limits/#job-limit) for more information. #### Allowed For * Agents parameters: - name: ids in: query description: The IDs of the organization memberships to delete schema: type: array items: type: integer responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" /api/v2/organization_merges/{organization_merge_id}: parameters: - $ref: "#/components/parameters/OrganizationMergeId" get: operationId: ShowOrganizationMerge tags: - Organizations summary: Show Organization Merge description: | Retrieves the details of a specific organization merge operation. This endpoint is useful for obtaining the status and outcome of a merge that was previously initiated. It provides information such as the winning and losing organization IDs, the status of the merge, and the associated URLs. This endpoint can be used to determine if a merge is still in progress, has completed successfully, or has encountered an error. #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/OrganizationMergeResponse" /api/v2/organization_subscriptions: get: operationId: ListOrganizationSubscriptions tags: - Organization Subscriptions summary: List Organization Subscriptions description: |- #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For: * Agents * End users For end users, the response will only list the subscriptions created by the requesting end user. parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/OrganizationSubscriptionsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateOrganizationSubscription tags: - Organization Subscriptions summary: Create Organization Subscription description: |- #### Allowed For: * Agents * End users End users can only subscribe to shared organizations in which they're members. requestBody: content: application/json: schema: $ref: "#/components/schemas/OrganizationSubscriptionCreateRequest" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/OrganizationSubscriptionResponse" /api/v2/organization_subscriptions/{organization_subscription_id}: get: operationId: ShowOrganizationSubscription tags: - Organization Subscriptions summary: Show Organization Subscription description: |- #### Allowed For: * Agents * End users For end users, the response will only list the subscriptions created by the requesting end user. parameters: - $ref: "#/components/parameters/OrganizationSubscriptionId" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/OrganizationSubscriptionResponse" delete: operationId: DeleteOrganizationSubscription tags: - Organization Subscriptions summary: Delete Organization Subscription description: |- #### Allowed For: * Agents * End users parameters: - $ref: "#/components/parameters/OrganizationSubscriptionId" responses: "204": description: No content /api/v2/organizations: get: operationId: ListOrganizations tags: - Organizations summary: List Organizations description: | #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents, with certain restrictions If the agent has a custom agent role that restricts their access to only users in their own organization, a 403 Forbidden error is returned. See [Creating custom agent roles](https://support.zendesk.com/hc/en-us/articles/203662026-Creating-custom-roles-and-assigning-agents#topic_cxn_hig_bd) in Zendesk help. parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/OrganizationsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateOrganization tags: - Organizations summary: Create Organization description: | You must provide a unique `name` for each organization. Normally the system doesn't allow records to be created with identical names. However, a race condition can occur if you make two or more identical POSTs very close to each other, causing the records to have identical organization names. #### Allowed For * Admins * Agents assigned to a custom role with permissions to manage organizations (Enterprise only) requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateOrganizationRequest" responses: "201": description: Created content: application/json: schema: $ref: "#/components/schemas/OrganizationResponse" /api/v2/organizations/{organization_id}: parameters: - $ref: "#/components/parameters/OrganizationId" get: operationId: ShowOrganization tags: - Organizations summary: Show Organization description: | #### Allowed For * Admins * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/OrganizationResponse" put: operationId: UpdateOrganization tags: - Organizations summary: Update Organization description: | #### Allowed For * Admins * Agents Agents with no permissions restrictions can only update "notes" on organizations. **Note:** Updating an organization's `domain_names` property overwrites all existing `domain_names` values. To prevent this, submit a complete list of `domain_names` for the organization in your request. #### Example Request ```js { "organization": { "notes": "Something interesting" } } ``` responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/OrganizationResponse" "429": description: Too Many Requests content: application/json: schema: $ref: "#/components/schemas/Errors" delete: operationId: DeleteOrganization tags: - Organizations summary: Delete Organization description: | #### Allowed For * Admins * Agents assigned to a custom role with permissions to manage organizations (Enterprise only) responses: "204": description: No Content Response /api/v2/organizations/{organization_id}/merge: parameters: - $ref: "#/components/parameters/OrganizationId" post: operationId: CreateOrganizationMerge tags: - Organizations summary: Merge Organization With Another Organization description: "Merges two organizations by moving all users, tickets, and domain\ \ names from the organization specified by `{organization_id}` to the organization\ \ specified by `winner_id`. After the merge:\n\n- The \"losing\" organization\ \ will be deleted.\n- Other organization fields and their values will not\ \ be carried over to the \"winning\" organization.\n- The merge operation\ \ creates an `Organization Merge` record which contains a status indicating\ \ the progress of the merge.\n\n**Note**: This operation is irreversible.\n\ \n#### Merge Statuses\n\n| Status | Description |\n|--------|-------------|\n\ | new | A job has been queued to merge the two organizations. |\n| in progress\ \ | The job to merge the two organizations has started. |\n| error | An error\ \ occurred during the merge job. The merge can be retried by repeating the\ \ API call. | \n| complete | The merge has been completed successfully. |\n\ \n#### Allowed For\n\n* Admins\n" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/OrganizationMergeRequest" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/OrganizationMergeResponse" /api/v2/organizations/{organization_id}/merges: parameters: - $ref: "#/components/parameters/OrganizationId" get: operationId: ListOrganizationMerges tags: - Organizations summary: List Organization Merges description: | Retrieves a list of all organization merge operations associated with a given organization. This endpoint allows you to track the history of merge actions for an organization, including ongoing and completed merges. Each entry in the list contains details such as the ID of the merge, the winning and losing organization IDs, the current status of the merge, and a URL to access the `Organization Merge` record. #### Pagination - Cursor pagination is used for this endpoint. - A maximum of 100 records can be returned per page. See [Pagination](/api-reference/introduction/pagination/) for more details. #### Allowed For * Admins parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/OrganizationMergeListResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/organizations/{organization_id}/related: parameters: - $ref: "#/components/parameters/OrganizationId" get: operationId: OrganizationRelated tags: - Organizations summary: Show Organization's Related Information description: | #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/OrganizationsRelatedResponse" /api/v2/organizations/autocomplete: parameters: - $ref: "#/components/parameters/OrganizationQueryFragment" - $ref: "#/components/parameters/LookupRelationshipAutocompleteFieldIdFragment" - $ref: "#/components/parameters/LookupRelationshipAutocompleteSourceFragment" get: operationId: AutocompleteOrganizations tags: - Organizations summary: Autocomplete Organizations description: | Returns an array of organizations whose name starts with the value specified in the `name` parameter. #### Pagination * Offset pagination only See [Using Offset Pagination](/api-reference/ticketing/introduction/#using-offset-pagination). #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/OrganizationsResponse" "400": description: Bad request content: application/json: schema: $ref: "#/components/schemas/Errors" "429": description: Too Many Requests content: application/json: schema: $ref: "#/components/schemas/Errors" "500": description: Internal Server Error content: application/json: schema: $ref: "#/components/schemas/Errors" /api/v2/organizations/count: get: operationId: CountOrganizations tags: - Organizations summary: Count Organizations description: | Returns an approximate count of organizations. 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. When the count exceeds 100,000, the `refreshed_at` property 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 * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CountOrganizationResponse" /api/v2/organizations/create_many: post: operationId: CreateManyOrganizations tags: - Organizations summary: Create Many Organizations description: | Accepts an array of up to 100 organization objects. #### Response This endpoint returns a `job_status` [JSON object](/api-reference/ticketing/ticket-management/job_statuses/#json-format) and queues a background job to do the work. Use the [Show Job Status](/api-reference/ticketing/ticket-management/job_statuses/#show-job-status) endpoint to check for the job's completion. Only a certain number of jobs can be queued or running at the same time. See [Job limit](/api-reference/introduction/rate-limits/#job-limit) for more information. #### Allowed For * Agents, with restrictions applying on certain actions responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" /api/v2/organizations/create_or_update: post: operationId: CreateOrUpdateOrganization tags: - Organizations summary: Create Or Update Organization description: | Creates an organization if it doesn't already exist, or updates an existing organization. Using this method means one less call to check if an organization exists before creating it. You need to specify the id or external id when updating an organization to avoid a duplicate error response. Name is not available as a matching criteria. #### Allowed For * Agents, with restrictions on certain actions responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/OrganizationResponse" "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/OrganizationResponse" /api/v2/organizations/destroy_many: parameters: - $ref: "#/components/parameters/OrganizationIds" - $ref: "#/components/parameters/OrganizationExternalIds" delete: operationId: DeleteManyOrganizations tags: - Organizations summary: Bulk Delete Organizations description: | Accepts a comma-separated list of up to 100 organization ids or external ids. #### Response This endpoint returns a `job_status` [JSON object](/api-reference/ticketing/ticket-management/job_statuses/#json-format) and queues a background job to do the work. Use the [Show Job Status](/api-reference/ticketing/ticket-management/job_statuses/#show-job-status) endpoint to check for the job's completion. Only a certain number of jobs can be queued or running at the same time. See [Job limit](/api-reference/introduction/rate-limits/#job-limit) for more information. #### Allowed For * Admins * Agents assigned to a custom role with permissions to manage organizations (Enterprise only) responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" /api/v2/organizations/search: parameters: - $ref: "#/components/parameters/OrganizationExternalId" - $ref: "#/components/parameters/OrganizationName" get: operationId: SearchOrganizations tags: - Organizations summary: Search Organizations description: | Returns an array of organizations matching the criteria. You may search by an organization's `external_id` or `name`, but not both: #### Searching by `external_id` If you set the `external_id` value of an organization to associate it to an external record, you can use it to search for the organization. For an organization to be returned, its `external_id` must exactly match the value provided (case insensitive). #### Searching by `name` For an organization to be returned, its `name` must exactly match the value provided (case insensitive). #### Allowed For: * Admins * Agents assigned to a custom role with permissions to add or modify organizations (Enterprise only) See [Creating custom agent roles](https://support.zendesk.com/hc/en-us/articles/203662026#topic_cxn_hig_bd) in the Support Help Center. responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/OrganizationsResponse" /api/v2/organizations/show_many: parameters: - $ref: "#/components/parameters/OrganizationIds" - $ref: "#/components/parameters/OrganizationExternalIds" get: operationId: ShowManyOrganizations tags: - Organizations summary: Show Many Organizations description: | Accepts a comma-separated list of up to 100 organization ids or external ids. #### Allowed For * Admins * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/OrganizationsResponse" /api/v2/organizations/update_many: parameters: - $ref: "#/components/parameters/OrganizationIds" - $ref: "#/components/parameters/OrganizationExternalIds" put: operationId: UpdateManyOrganizations tags: - Organizations summary: Update Many Organizations description: | Bulk or batch updates up to 100 organizations. #### Bulk update To make the same change to multiple organizations, use the following endpoint and data format: `https://{subdomain}.zendesk.com/api/v2/organizations/update_many.json?ids=1,2,3` ```js { "organization": { "notes": "Priority" } } ``` #### Batch update To make different changes to multiple organizations, use the following endpoint and data format: `https://{subdomain}.zendesk.com/api/v2/organizations/update_many.json` ```js { "organizations": [ { "id": 1, "notes": "Priority" }, { "id": 2, "notes": "Normal" } ] } ``` #### Response This endpoint returns a `job_status` [JSON object](/api-reference/ticketing/ticket-management/job_statuses/#json-format) and queues a background job to do the work. Use the [Show Job Status](/api-reference/ticketing/ticket-management/job_statuses/#show-job-status) endpoint to check for the job's completion. Only a certain number of jobs can be queued or running at the same time. See [Job limit](/api-reference/introduction/rate-limits/#job-limit) for more information. #### Allowed For * Admins * Agents Agents with no permissions restrictions can only update "notes" on organizations. responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" /api/v2/problems: get: operationId: ListTicketProblems tags: - Tickets summary: List Ticket Problems description: |- The response is always ordered by `updated_at` in descending order #### Allowed For * Agents #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/ListTicketProblemsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/problems/autocomplete: post: operationId: AutocompleteProblems tags: - Tickets summary: Autocomplete Problems description: |- Returns tickets whose type is "problem" and whose subject contains the string specified in the `text` parameter. You can specify the `text` parameter in the request body rather than the query string. Example: `{"text": "fire"}` #### Allowed For * Agents parameters: - name: text in: query description: The text to search for schema: type: string requestBody: content: application/json: schema: type: object properties: text: type: string description: The text to search for responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/ListTicketProblemsResponse" /api/v2/push_notification_devices/destroy_many: post: operationId: PushNotificationDevices tags: - Push Notification Devices summary: Bulk Unregister Push Notification Devices description: |- Unregisters the mobile devices that are receiving push notifications. Specify the devices as an array of mobile device tokens. #### Allowed for * Admins requestBody: content: application/json: schema: $ref: "#/components/schemas/PushNotificationDevicesRequest" responses: "200": description: Successful response content: application/json: schema: type: string description: empty /api/v2/queues: get: operationId: ListQueues tags: - Omnichannel Routing Queues summary: List queues description: | Returns all active queues for an account. #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/QueuesResponse" post: operationId: CreateQueue tags: - Omnichannel Routing Queues summary: Create Queue description: | Creates a queue. Accepts a JSON queue definition as the request body. #### Allowed For * Admins responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/QueueResponse" /api/v2/queues/{queue_id}: parameters: - $ref: "#/components/parameters/OcrQueueId" get: operationId: ShowQueueById tags: - Omnichannel Routing Queues summary: Show Queue description: | Returns a queue for the given queue id. #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/QueueResponse" put: operationId: UpdateQueue tags: - Omnichannel Routing Queues summary: Update Queue description: | Updates the queue definition for a given queue id. #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/QueueResponse" delete: operationId: DeleteQueue tags: - Omnichannel Routing Queues summary: Delete Queue description: | Deletes the queue and related records. #### Allowed For * Admins responses: "204": description: No content response /api/v2/queues/definitions: get: operationId: ListQueueDefinitions tags: - Omnichannel Routing Queues summary: List Queue Definitions description: | Returns the definitions of the queues and the definitions of the conditions under which a queue can execute. The definition of the action includes a title ("Status"), a type ("list"), and possible values. The definition of the condition includes the same fields as well as the possible operators. #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/DefinitionsResponse" /api/v2/queues/order: patch: operationId: ReorderQueues tags: - Omnichannel Routing Queues summary: Reorder Queues description: | Alters the evaluation order of OCR queues in the account. The evaluation order is set in a `queue_ids` array in the request body. You must include every queue id in your account to reorder the OCR queues. If not, the endpoint will return 400 Bad Request. #### Allowed For * Admins responses: "204": description: No Content /api/v2/recipient_addresses: get: operationId: ListSupportAddresses tags: - Support Addresses summary: List Support Addresses description: | Lists all the support addresses for the account. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Admins * Agents parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SupportAddressesResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateSupportAddress tags: - Support Addresses summary: Create Support Address description: | Adds a Zendesk or external support address to your account. To add a Zendesk address, use the following syntax: `{local-part}@{accountname}.zendesk.com`. Example: 'sales-team@example.zendesk.com'. The [local-part](https://en.wikipedia.org/wiki/Email_address#Local-part) can be anything you like. To add an external email address such as help@omniwearshop.com, the email must already exist and you must set up forwarding on your email server. The exact steps depend on your mail server. See [Forwarding incoming email to Zendesk Support](https://support.zendesk.com/hc/en-us/articles/203663266). After setting up forwarding, run the [Verify Support Address Forwarding](#verify-support-address-forwarding) endpoint. The address won't work in Zendesk Support until it's been verified. #### Allowed For * Admins * Agents with permission to manage channels and extensions. See the system permissions in [Creating custom roles and assigning agents (Enterprise)](https://support.zendesk.com/hc/en-us/articles/203662026-Creating-custom-roles-and-assigning-agents-Enterprise-#topic_cxn_hig_bd) in the Support Help Center responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/SupportAddressResponse" /api/v2/recipient_addresses/{support_address_id}: parameters: - $ref: "#/components/parameters/SupportAddressId" get: operationId: ShowSupportAddress tags: - Support Addresses summary: Show Support Address description: | #### Allowed For * Admins * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SupportAddressResponse" put: operationId: UpdateSupportAddress tags: - Support Addresses summary: Update Support Address description: | Updates an existing support address for your account. You can't use this endpoint to update a support address's `email` property. Instead, you can create a new address using the [Create Support Address](#create-support-address) endpoint. #### Allowed For * Admins * Agents with permission to manage channels and extensions. See the system permissions in [Creating custom roles and assigning agents (Enterprise)](https://support.zendesk.com/hc/en-us/articles/203662026-Creating-custom-roles-and-assigning-agents-Enterprise-#topic_cxn_hig_bd) in the Support Help Center responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SupportAddressResponse" delete: operationId: DeleteRecipientAddress tags: - Support Addresses summary: Delete Support Address description: | Deletes a support address. #### Allowed For * Admins * Agents with permission to manage channels and extensions. See the system permissions in [Creating custom roles and assigning agents (Enterprise)](https://support.zendesk.com/hc/en-us/articles/203662026-Creating-custom-roles-and-assigning-agents-Enterprise-#topic_cxn_hig_bd) in the Support Help Center responses: "204": description: No Content response /api/v2/recipient_addresses/{support_address_id}/verify: parameters: - $ref: "#/components/parameters/SupportAddressId" put: operationId: VerifySupportAddressForwarding tags: - Support Addresses summary: Verify Support Address Forwarding description: | Sends a test email to the specified support address to verify that email forwarding for the address works. An external support address won't work in Zendesk Support until it's verified. **Note**: You don't need to verify Zendesk system support addresses. The endpoint takes the following body: `{"type": "forwarding"}`. The value of the `type` property defaults to "forwarding" if none is specified, but the values "spf" and "dns" are also accepted. Use this endpoint after [adding](#create-support-address) an external support address to Zendesk Support and setting up forwarding on your email server. See [Forwarding incoming email to Zendesk Support](https://support.zendesk.com/hc/en-us/articles/203663266). The endpoint doesn't return the results of the test. Instead, use the [Show Support Address](#show-support-address) endpoint to check that the `forwarding_status` property is "verified". Other verification checks can also be performed using this API. These include SPF checks and DNS checks. When calling the endpoint with `type` set to "spf", it will queries the DNS records to check that the SPF records for Zendesk are present for outbound emails. When calling the endpoint with `type` set to "dns", it runs checks on your CNAME records to make sure they are set up properly in your DNS. #### Allowed For * Admins * Agents with permission to manage channels and extensions. See the system permissions in [Creating custom roles and assigning agents (Enterprise)](https://support.zendesk.com/hc/en-us/articles/203662026-Creating-custom-roles-and-assigning-agents-Enterprise-#topic_cxn_hig_bd) in the Support Help Center responses: "200": description: Success response content: application/json: schema: type: string description: Empty response /api/v2/relationships/definitions/{target_type}: get: operationId: GetRelationshipFilterDefinitions tags: - Lookup Relationships summary: Filter Definitions description: | 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`. parameters: - name: target_type in: path description: | 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" required: true schema: type: string - name: source_type in: query description: | The source type for which you would like to see filter definitions. The options are "zen:user", "zen:ticket", and "zen:organization" schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/RelationshipFilterDefinitionResponse" /api/v2/requests: get: operationId: ListRequests tags: - Requests summary: List Requests description: | #### Allowed for * End Users #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - name: sort_by in: query description: Possible values are "updated_at", "created_at" schema: type: string - name: sort_order in: query description: One of "asc", "desc". Defaults to "asc" schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/RequestsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateRequest tags: - Requests summary: Create Request description: | Accepts a `request` object that sets one or more properties. #### Allowed for * End users * Anonymous users (rate limit of 5 requests per hour for [trial accounts](/documentation/developer-tools/getting-started/getting-a-trial-or-sponsored-account-for-development/)) #### Additional properties In addition to the writable request properties in the [JSON Format table](#json-format) above, you can set the following properties when creating a request. | Name | Type | Mandatory | Comment | ---------------- | -------| --------- | ------- | comment | object | yes | Describes the problem, incident, question, or task. See [Request comments](#request-comments) | collaborators | array | no | Adds collaborators (cc's) to the request. An email notification is sent to them when the ticket is created. See [Setting collaborators](/documentation/ticketing/managing-tickets/creating-and-managing-requests#setting-collaborators) | requester | object | yes* | \*Required for anonymous requests. Specifies the requester of the anonymous request. See [Creating anonymous requests](/documentation/ticketing/managing-tickets/creating-and-managing-requests#creating-anonymous-requests) #### Creating follow-up requests Once a ticket is closed (as distinct from solved), it can't be reopened. However, you can create a new request that references the closed ticket. To create the follow-up request, include a `via_followup_source_id` property in the `request` object that specifies the closed ticket. The parameter only works with closed tickets. It has no effect with other tickets. responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/RequestResponse" /api/v2/requests/{request_id}: parameters: - $ref: "#/components/parameters/RequestId" get: operationId: ShowRequest tags: - Requests summary: Show Request description: | #### Sideloads The following sideloads are supported: | Name | Will sideload | ---------------- | ------------- | users | The email ccs for a request by side-loading users #### Allowed For * End Users responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/RequestResponse" put: operationId: UpdateRequest tags: - Requests summary: Update Request description: | Updates a request with a comment or collaborators (cc's). The end user who created the request can also use it to mark the request as solved. The endpoint can't be used to update other request attributes. #### Writable properties This endpoint can only update the following properties in the request. | Name | Type | Required | Description | | ------------------------ | ------- | -------- | ---------------------------------------------------- | | comment | object | no | Adds a comment to the request. See [Request comments](#request-comments) | | solved | boolean | no | Marks the request as solved. Example: `{"request": {"solved": "true"}}`. End users can mark requests as solved only if the request's `can_be_solved_by_me` property is true. The property is true only when the ticket is assigned to an agent and the ticket type is not a problem but a question, task, or incident | | additional_collaborators | array | no | Adds collaborators to the request. An email notification is sent to them when the ticket is updated. See [Adding collaborators](/documentation/ticketing/managing-tickets/creating-and-managing-requests#adding-collaborators) | #### Allowed For * End users responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/RequestResponse" /api/v2/requests/{request_id}/comments: parameters: - $ref: "#/components/parameters/RequestId" get: operationId: ListComments tags: - Requests summary: Listing Comments description: | #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). #### Sorting By default, comments are sorted by creation date in ascending order. When using cursor pagination, use the following parameter to change the sort order: | Name | Type | Required | Comments | ------ | ------ | -------- | -------- | `sort` | string | no | Possible values are "created_at" (ascending order) or "-created_at" (descending order) When using offset pagination, use the following parameters to change the sort order: | Name | Type | Required | Comments | ------------ | ------ | -------- | -------- | `sort_by` | string | no | One of `created_at`, `updated_at` | `sort_order` | string | no | One of `asc`, `desc` #### Allowed For * End Users parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - name: sort in: query description: 'Specifies how to sort the comments. Possible values are "created_at" (ascending order) or "-created_at" (descending order) ' schema: type: string enum: - created_at - -created_at - name: since in: query description: Filters the comments from the given datetime schema: type: string - name: role in: query description: One of "agent", "end_user". If not specified it does not filter schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketCommentsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/requests/{request_id}/comments/{ticket_comment_id}: parameters: - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/TicketCommentId" get: operationId: ShowComment tags: - Requests summary: Getting Comments description: | #### Allowed For * End Users responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketCommentResponse" /api/v2/requests/search: get: operationId: SearchRequests tags: - Requests summary: Search Requests description: | Examples: * `GET /api/v2/requests/search.json?query=printer` * `GET /api/v2/requests/search.json?query=printer&organization_id=1` * `GET /api/v2/requests/search.json?query=printer&cc_id=true` * `GET /api/v2/requests/search.json?query=printer&status=hold,open` #### Pagination * Offset pagination only See [Using Offset Pagination](/api-reference/ticketing/introduction/#using-offset-pagination). #### Results limit The Search Requests endpoint returns up to 1,000 results per query, with a maximum of 100 results per page. See [Pagination](/api-reference/ticketing/introduction/#pagination). If you request a page past the limit (`page=11` at 100 results per page), a 422 Insufficient Resource Error is returned. #### Allowed For * End Users parameters: - name: query in: query description: The syntax and matching logic for the string is detailed in the [Zendesk Support search reference](https://support.zendesk.com/hc/en-us/articles/203663226). See also [Query basics](/api-reference/ticketing/ticket-management/search/#query-basics) in the Tickets API doc. schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/RequestsResponse" /api/v2/resource_collections: get: operationId: ListResourceCollections tags: - Resource Collections summary: List Resource Collections description: | Lists resource collections for the account. #### Allowed for * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ResourceCollectionsResponse" post: operationId: CreateResourceCollection tags: - Resource Collections summary: Create Resource Collection description: | Creates a resource collection from a provided `payload` object. The `payload` object is specified the same way as the content of a requirements.json file in a Zendesk app. See [Specifying Apps Requirements](/documentation/apps/app-developer-guide/apps_requirements/) in the Zendesk Apps framework docs. The response includes a [job status](/api-reference/ticketing/ticket-management/job_statuses/) for creation of the specified resources. #### Allowed for * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" /api/v2/resource_collections/{resource_collection_id}: parameters: - $ref: "#/components/parameters/ResourceCollectionId" get: operationId: RetrieveResourceCollection tags: - Resource Collections summary: Show Resource Collection description: | Retrieves details for a specified resource collection. #### Allowed for * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ResourceCollectionResponse" put: operationId: UpdateResourceCollection tags: - Resource Collections summary: Update Resource Collection description: | Updates a resource collection using a provided `payload` object. The `payload` object is specified the same way as the content of a requirements.json file in a Zendesk app. See [Specifying Apps Requirements](/documentation/apps/app-developer-guide/apps_requirements/) in the Zendesk Apps framework docs. The response includes a [job status](/api-reference/ticketing/ticket-management/job_statuses/) for the resource updates. #### Allowed for * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" delete: operationId: DeleteResourceCollection tags: - Resource Collections summary: Delete Resource Collection description: | Deletes a specified resource collection. The response includes a [job status](/api-reference/ticketing/ticket-management/job_statuses/) for deletion of the collection's resources. #### Allowed for * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" /api/v2/routing/agents/{user_id}/instance_values: parameters: - $ref: "#/components/parameters/UserId" get: operationId: ListAGentAttributeValues tags: - Skill Based Routing summary: List Agent Attribute Values description: | Returns an attribute value. #### Allowed For * Agents and admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SkillBasedRoutingAttributeValuesResponse" post: operationId: SetAgentAttributeValues tags: - Skill Based Routing summary: Set Agent Attribute Values description: | Adds the specified attributes if no attributes exists, or replaces all existing attributes with the specified attributes. #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SkillBasedRoutingAttributeValuesResponse" /api/v2/routing/agents/instance_values: get: operationId: ListManyAgentsAttributeValues tags: - Skill Based Routing summary: List Attribute Values for Many Agents description: | Accepts a comma-separated list of up to 100 agent ids and returns attribute values for each agent in the list. #### Allowed For * Admins * [Agents in custom role with permission to manage skills](https://support.zendesk.com/hc/en-us/articles/4408882153882-Creating-custom-roles-and-assigning-agents) #### Pagination * [Cursor pagination](/api-reference/introduction/pagination/#cursor-pagination) only. Note: `page[before]` and `page[after]` can't be used together in the same request. parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - name: filter[agent_ids] in: query description: A comma-separated list of agent ids required: true schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ManySkillBasedRoutingAttributeValuesResponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/SkillBasedRoutingAttributeValuesError" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/routing/agents/instance_values/job: post: operationId: BulkSetAgentAttributeValuesJob tags: - Skill Based Routing - Job Statuses summary: Bulk Set Agent Attribute Values Job description: | Adds, replaces or removes multiple attributes for up to 100 agents. #### Allowed For * Admins * [Agents in custom role with permission to manage skills](https://support.zendesk.com/hc/en-us/articles/4408882153882-Creating-custom-roles-and-assigning-agents) #### Available Parameters The request takes a data object with the following properties: | Name | Type | Required | Description | | ---------- | ------ | -------- | ------------------------------------------------------------------------------------------------- | | action | string | true | The action to perform on the attribute values. One of the following: "upsert", "update", "delete" | | attributes | object | true | The attribute values to update. See [Attribute Values](#attribute-values) | | items | array | true | The list of agent ids | Action can be one of the following: * upsert: Adds new attribute values to the agents * update: Replaces all the current attribute values of the agents with the new values * delete: Removes specified attribute values from the agents This endpoint returns a `job_status` [JSON object](/api-reference/ticketing/ticket-management/job_statuses/#json-format) and queues a background job to do the work. Use the [Show Job Status](/api-reference/ticketing/ticket-management/job_statuses/#show-job-status) endpoint to check for the job's completion. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/BulkSkillBasedRoutingAttributeValuesRequest" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/SkillBasedRoutingAttributeValuesError" /api/v2/routing/attributes: get: operationId: ListAccountAttributes tags: - Skill Based Routing summary: List Account Attributes description: | Returns a list of attributes for the account. #### Sideloads The following sideloads are supported: | Name | Will sideload | ---------------- | ------------- | attribute_values | The attribute values available on the account #### Allowed For * Agents and admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SkillBasedRoutingAttributesResponse" post: operationId: CreateAttribute tags: - Skill Based Routing summary: Create Attribute description: | Creates an attribute. #### Allowed For * Agents responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/SkillBasedRoutingAttributeResponse" /api/v2/routing/attributes/{attribute_id}: parameters: - $ref: "#/components/parameters/SkillBasedRoutingAttributeId" get: operationId: ShowAttribute tags: - Skill Based Routing summary: Show Attribute description: | Returns an attribute. #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SkillBasedRoutingAttributeResponse" put: operationId: UpdateAttribute tags: - Skill Based Routing summary: Update Attribute description: | Updates an attribute. #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SkillBasedRoutingAttributeResponse" delete: operationId: DeleteAttribute tags: - Skill Based Routing summary: Delete Attribute description: | Deletes an attribute. #### Allowed For * Admins responses: "204": description: No Content response /api/v2/routing/attributes/{attribute_id}/values: parameters: - $ref: "#/components/parameters/SkillBasedRoutingAttributeId" get: operationId: ListAttributeValues tags: - Skill Based Routing summary: List Attribute Values for an Attribute description: | Returns a list of attribute values for a provided attribute. #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SkillBasedRoutingAttributeValuesResponse" post: operationId: CreateAttributeValue tags: - Skill Based Routing summary: Create Attribute Value description: | Creates an attribute value. #### Allowed For * Admins responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/SkillBasedRoutingAttributeValueResponse" /api/v2/routing/attributes/{attribute_id}/values/{attribute_value_id}: parameters: - $ref: "#/components/parameters/SkillBasedRoutingAttributeId" - $ref: "#/components/parameters/SkillBasedRoutingAttributeValueId" get: operationId: ShowAttributeValue tags: - Skill Based Routing summary: Show Attribute Value description: | Returns an attribute value. #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SkillBasedRoutingAttributeValueResponse" patch: operationId: UpdateAttributeValue tags: - Skill Based Routing summary: Update Attribute Value description: | Updates the name and ticket conditions of a skill. When a ticket is created, the skill is applied to a ticket if the ticket meets the specified condition or conditions. See the [Conditions reference](/documentation/ticketing/reference-guides/conditions-reference/) for more information. #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SkillBasedRoutingAttributeValueResponse" delete: operationId: DeleteAttributeValue tags: - Skill Based Routing summary: Delete Attribute Value description: | Deletes an attribute value. #### Allowed For * Agents responses: "204": description: No Content response /api/v2/routing/attributes/definitions: get: operationId: ListRoutingAttributeDefinitions tags: - Skill Based Routing summary: List Routing Attribute Definitions description: | Returns the condition definitions that can be configured to apply attributes to a ticket. #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SkillBasedRoutingAttributeDefinitions" /api/v2/routing/requirements/fulfilled: get: operationId: ListTicketsFullfilledByUser tags: - Skill Based Routing summary: List Tickets Fulfilled by a User description: | Returns a list of ticket ids that contain attributes matching the current user's attributes. Accepts a `ticket_ids` parameter for relevant tickets to check for matching attributes. #### Allowed For * Agents and admins parameters: - name: ticket_ids in: query description: The IDs of the relevant tickets to check for matching attributes required: true schema: type: integer responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SkillBasedRoutingTicketFulfilledResponse" /api/v2/routing/tickets/{ticket_id}/instance_values: parameters: - $ref: "#/components/parameters/TicketId" get: operationId: ListTicketAttributeValues tags: - Skill Based Routing summary: List Ticket Attribute Values description: | Returns a list of attributes values for the ticket. #### Allowed For * Agents and admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SkillBasedRoutingAttributeValuesResponse" post: operationId: SetTicketAttributeValues tags: - Skill Based Routing summary: Set Ticket Attribute Values description: | Adds the specified attributes if no attributes exists, or replaces all existing attributes with the specified attributes. Invalid or deleted attributes are ignored. #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SkillBasedRoutingAttributeValuesResponse" /api/v2/satisfaction_ratings: get: operationId: ListSatisfactionRatings tags: - Satisfaction Ratings summary: List Satisfaction Ratings description: | #### Allowed For * Admins #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). #### Filters | Parameter | Value | ---------- | ----- | score | offered, unoffered, received, received\_with\_comment, received\_without\_comment,
good, good\_with\_comment, good\_without\_comment,
bad, bad\_with\_comment, bad\_without\_comment | start_time | Time of the oldest satisfaction rating, as a [Unix epoch time](https://www.epochconverter.com/) | end_time | Time of the most recent satisfaction rating, as a [Unix epoch time](https://www.epochconverter.com/) If you specify an unqualified score such as `good`, the results include all the records with and without comments. Examples: * `/api/v2/satisfaction_ratings.json?score=bad` * `/api/v2/satisfaction_ratings.json?score=bad&start_time=1498151194` * `/api/v2/satisfaction_ratings.json?start_time=1340384793&end_time=1371920793` parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - name: score in: query description: 'Filters the results by score. Possible values are "offered", "unoffered", "received", "received_with_comment", "received_without_comment", "good", "good_with_comment", "good_without_comment", "bad", "bad_with_comment", "bad_without_comment" ' schema: type: string enum: - offered - unoffered - received - received_with_comment - received_without_comment - good - good_with_comment - good_without_comment - bad - bad_with_comment - bad_without_comment - name: start_time in: query description: "Time of the oldest satisfaction rating, as a [Unix epoch time](https://www.epochconverter.com/) " schema: type: integer - name: end_time in: query description: "Time of the most recent satisfaction rating, as a [Unix epoch time](https://www.epochconverter.com/) " schema: type: integer responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SatisfactionRatingsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/satisfaction_ratings/{satisfaction_rating_id}: get: operationId: ShowSatisfactionRating tags: - Satisfaction Ratings summary: Show Satisfaction Rating description: | Returns a specific satisfaction rating. You can get the id from the [List Satisfaction Ratings](#list-satisfaction-ratings) endpoint. #### Allowed For * Admins parameters: - name: satisfaction_rating_id in: path description: The id of the satisfaction rating to retrieve required: true schema: type: integer responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SatisfactionRatingResponse" /api/v2/satisfaction_ratings/count: get: operationId: CountSatisfactionRatings tags: - Satisfaction Ratings summary: Count Satisfaction Ratings description: |- Returns an approximate count of satisfaction ratings in the account. If the count exceeds 100,000, the count will return a cached result. This cached result will update every 24 hours. The `count[refreshed_at]` property is a timestamp that indicates when the count was last updated. **Note**: When the count exceeds 100,000, `count[refreshed_at]` may occasionally be null. This indicates that the count is being updated in the background, and `count[value]` is limited to 100,000 until the update is complete. #### Allowed For * Admins responses: "200": description: Count of satisfaction ratings content: application/json: schema: $ref: "#/components/schemas/SatisfactionRatingsCountResponse" /api/v2/satisfaction_reasons: get: operationId: ListSatisfactionRatingReasons tags: - Satisfaction Reasons summary: List Reasons for Satisfaction Rating description: | List all reasons for an account #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SatisfactionReasonsResponse" /api/v2/satisfaction_reasons/{satisfaction_reason_id}: get: operationId: ShowSatisfactionRatings tags: - Satisfaction Reasons summary: Show Reason for Satisfaction Rating description: | #### Allowed For * Admins parameters: - name: satisfaction_reason_id in: path description: The id of the satisfaction rating reason required: true schema: type: integer responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SatisfactionReasonResponse" /api/v2/search: get: operationId: ListSearchResults tags: - Search summary: List Search Results description: | Returns the search results. See [Query basics](#query-basics) for the syntax of the `query` parameter. Use the ampersand character (&) to append the `sort_by` or `sort_order` parameters to the URL. For examples, see [Searching with Zendesk API](/documentation/ticketing/using-the-zendesk-api/searching-with-the-zendesk-api). #### Allowed For * Agents #### Pagination * Offset pagination only Offset pagination may result in duplicate results when paging. You can also use the [Export Search Results](/api-reference/ticketing/ticket-management/search/#export-search-results) endpoint, which uses cursor-based pagination and doesn't return duplicate results. See [Using cursor pagination](/api-reference/introduction/pagination/#using-cursor-pagination) for more information. #### Errors JSON Format Errors are represented as JSON objects which have the following keys: | Name | Type | Comment | --------------------- | ---------------------| -------------------- | error | string | The type of error. Examples: "unavailable", "invalid" | description | string | ##### Example Error ```js { "error": "unavailable", "description": "Sorry, we could not complete your search query. Please try again in a moment." } ``` parameters: - name: query in: query description: The search query. See [Query basics](#query-basics) above. For details on the query syntax, see the [Zendesk Support search reference](https://support.zendesk.com/hc/en-us/articles/203663226) required: true schema: type: string - name: sort_by in: query description: One of `updated_at`, `created_at`, `priority`, `status`, or `ticket_type`. Defaults to sorting by relevance schema: type: string enum: - updated_at - created_at - priority - status - ticket_type - name: sort_order in: query description: One of `asc` or `desc`. Defaults to `desc` schema: type: string enum: - asc - desc - name: page in: query description: Page number for offset pagination schema: type: integer minimum: 1 default: 1 - name: per_page in: query description: Number of items per page schema: type: integer minimum: 1 maximum: 100 default: 100 responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SearchResponse" x-speakeasy-pagination: type: offsetLimit inputs: - name: page in: parameters type: page - name: per_page in: parameters type: limit outputs: results: $.results /api/v2/search/count: get: operationId: CountSearchResults tags: - Search summary: Show Results Count description: | Returns the number of items matching the query rather than the items. The search string works the same as a regular search. #### Allowed For - Agents parameters: - name: query in: query description: The search query required: true schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SearchCountResponse" /api/v2/search/export: get: operationId: ExportSearchResults tags: - Search summary: Export Search Results description: | Exports a set of results. See [Query syntax](#query-syntax) for the syntax of the `query` parameter. Use this endpoint for search queries that will return more than 1000 results. The result set is ordered only by the `created_at` attribute. The search only returns results of a single object type. The following object types are supported: ticket, organization, user, or group. You must specify the type in the `filter[type]` parameter. Searches with type in the query string will result in an error. #### Allowed For - Agents #### Pagination - Cursor pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 1000 records per page. The number of results shown in a page is determined by the `page[size]` parameter. **Note**: You may experience a speed reduction or a timeout if you request 1000 results per page and you have many archived tickets in the results. Try reducing the number of results per page. We recommend 100 results per page. The cursor specified by the `after_cursor` property in a response expires after one hour. For more information on cursor-based pagination, see the following articles: - [Comparing cursor pagination and offset pagination](/documentation/developer-tools/pagination/comparing-cursor-pagination-and-offset-pagination) - [Paginating through lists using cursor pagination](/documentation/developer-tools/pagination/paginating-through-lists-using-cursor-pagination) #### Limits This API endpoint is rate-limited to 100 requests per minute per account. The limit also counts towards the global API rate limit. #### Response Format | Name | Type | Comment | --------------------- | ---------------------| -------------------- | links[next] | string | URL to the next page of results | meta[has_more] | string | Boolean indicating if there are more results | meta[after_cursor] | string | Cursor object returned from the Search Service | results | array | May consist of tickets, users, groups, or organizations, as specified by the `filter_type` parameter The response is similar to the response of `GET /api/v2/search.json?`, with a few changes: * `links` - Has the following nested properties: `prev` and `next`. These replace the `next_page` and `prev_page` links. The `prev` property is always null because backward pagination is not supported. The `next` property may include an auto-generated link to the next page of results. * `meta` - Has the following nested properties: `has_more` and `after_cursor`. The `has_more` property indicates whether the next page has more results. The `after_cursor` property is the cursor used to paginate to the next page. It expires after one hour. There's no `count` property. parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - name: query in: query description: The search query. See [Query basics](#query-basics) above. For details on the query syntax, see the [Zendesk Support search reference](https://support.zendesk.com/hc/en-us/articles/203663226) required: true schema: type: string - name: filter[type] in: query description: The object type returned by the export query. Can be `ticket`, `organization`, `user`, or `group`. schema: type: string enum: - ticket - organization - user - group responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SearchExportResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/sessions: get: operationId: ListSessions tags: - Sessions summary: List Sessions description: | If authenticated as an admin, returns all the account's sessions. If authenticated as an agent or end user, returns only the sessions of the user making the request. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). #### Allowed For * Admins, Agents, End users parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SessionsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/sharing_agreements: get: operationId: ListSharingAgreements tags: - Sharing Agreements summary: List Sharing Agreements description: | #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SharingAgreementsResponse" post: operationId: CreateSharingAgreement tags: - Sharing Agreements summary: Create Sharing Agreement description: | #### Allowed For * Admins responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/SharingAgreementResponse" /api/v2/sharing_agreements/{sharing_agreement_id}: parameters: - $ref: "#/components/parameters/SharingAgreementId" get: operationId: ShowSharingAgreement tags: - Sharing Agreements summary: Show a Sharing Agreement description: | Returns a sharing agreement for your account. #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SharingAgreementResponse" put: operationId: UpdateSharingAgreement tags: - Sharing Agreements summary: Update a Sharing Agreement description: | Returns an updated sharing agreement. Only `status` is allowed to be updated. #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SharingAgreementResponse" delete: operationId: DeleteSharingAgreement tags: - Sharing Agreements summary: Delete a Sharing Agreement description: | Deletes a sharing agreement. #### Allowed For * Admins responses: "204": description: No Content response /api/v2/skips: post: operationId: RecordNewSkip tags: - Ticket Skips summary: Record a New Skip for the Current User description: | Record a new ticket skip for the current user. #### Allowed For * Agents responses: "201": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketSkipCreation" /api/v2/slas/policies: get: operationId: ListSLAPolicies tags: - SLA Policies summary: List SLA Policies description: | #### Availability * Accounts on the Support Professional or Suite Growth plan or above #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SLAPoliciesResponse" post: operationId: CreateSLAPolicy tags: - SLA Policies summary: Create SLA Policy description: | #### Availability * Accounts on the Support Professional or Suite Growth plan or above #### Allowed For * Admins responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/SLAPolicyResponse" /api/v2/slas/policies/{sla_policy_id}: parameters: - $ref: "#/components/parameters/SLAPolicyId" get: operationId: ShowSLAPolicy tags: - SLA Policies summary: Show SLA Policy description: | #### Availability * Accounts on the Support Professional or Suite Growth plan or above #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SLAPolicyResponse" put: operationId: UpdateSLAPolicy tags: - SLA Policies summary: Update SLA Policy description: | Updates the specified policy. #### Availability * Accounts on the Support Professional or Suite Growth plan or above #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SLAPolicyResponse" delete: operationId: DeleteSLAPolicy tags: - SLA Policies summary: Delete SLA Policy description: | #### Availability * Accounts on the Support Professional or Suite Growth plan or above #### Allowed For * Admins responses: "204": description: No Content response /api/v2/slas/policies/definitions: get: operationId: RetrieveSLAPolicyFilterDefinitionItems tags: - SLA Policies summary: Retrieve Supported Filter Definition Items description: | #### Availability * Accounts on the Support Professional or Suite Growth plan or above #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SLAPolicyFilterDefinitionResponse" /api/v2/slas/policies/reorder: put: operationId: ReorderSLAPolicies tags: - SLA Policies summary: Reorder SLA Policies description: | #### Availability * Accounts on the Support Professional or Suite Growth plan or above #### Allowed For * Admins parameters: - name: sla_policy_ids in: query description: The IDs of the SLA Policies to reorder schema: type: array items: type: integer responses: "200": description: Success response content: application/json: schema: type: string description: Empty response /api/v2/suspended_tickets: parameters: - $ref: "#/components/parameters/SuspendedTicketsSortBy" - $ref: "#/components/parameters/SuspendedTicketsSortOrder" get: operationId: ListSuspendedTickets tags: - Suspended Tickets summary: List Suspended Tickets description: | #### Allowed For * Admins and [agents in custom roles with permission](https://support.zendesk.com/hc/en-us/articles/4408882153882#topic_cxn_hig_bd) to manage suspended tickets on Enterprise plans * Unrestricted agents on all other plans #### Sorting You can sort the tickets with the `sort_by` and `sort_order` query string parameters. #### Pagination * Cursor pagination See [Pagination](/api-reference/introduction/pagination/). parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SuspendedTicketsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/suspended_tickets/{id}: get: operationId: ShowSuspendedTickets tags: - Suspended Tickets summary: Show Suspended Ticket description: | #### Allowed For * Admins and [agents in custom roles with permission](https://support.zendesk.com/hc/en-us/articles/4408882153882#topic_cxn_hig_bd) to manage suspended tickets on Enterprise plans * Unrestricted agents on all other plans parameters: - $ref: "#/components/parameters/SuspendedTicketId" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SuspendedTicketsResponse" delete: operationId: DeleteSuspendedTicket tags: - Suspended Tickets summary: Delete Suspended Ticket description: | #### Allowed For * Unrestricted agents parameters: - $ref: "#/components/parameters/SuspendedTicketId" responses: "204": description: No Content response /api/v2/suspended_tickets/{id}/recover: put: operationId: RecoverSuspendedTicket tags: - Suspended Tickets summary: Recover Suspended Ticket description: | **Note**: During recovery, the API sets the requester to the authenticated agent who called the API, not the original requester. This prevents the ticket from being re-suspended after recovery. To preserve the original requester, use the [Recover Multiple Suspended Tickets](#recover-multiple-suspended-tickets) endpoint with the single ticket. This endpoint does not queue an asynchronous job that can be tracked from [Job Statuses](/api-reference/ticketing/ticket-management/job_statuses/). Instead, it processes the request with a synchronous response. - If all recoveries are successful, it returns a 200 with a `tickets` array in the response. - If all recoveries fail, it returns a 422 with a `suspended_tickets` array in the response. - If there is a mixture of successes and failures in a single call, it returns a 422 with a `suspended_tickets` array of the failures in the response. #### Allowed For * Admins and [agents in custom roles with permission](https://support.zendesk.com/hc/en-us/articles/4408882153882#topic_cxn_hig_bd) to manage suspended tickets on Enterprise plans * Unrestricted agents on all other plans parameters: - $ref: "#/components/parameters/SuspendedTicketId" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/RecoverSuspendedTicketResponse" "422": description: Recovery failed response content: application/json: schema: $ref: "#/components/schemas/RecoverSuspendedTicketUnprocessableContentResponse" /api/v2/suspended_tickets/attachments: post: operationId: SuspendedTicketsAttachments tags: - Suspended Tickets summary: Suspended Ticket Attachments description: | Makes copies of any attachments on a suspended ticket and returns them as [attachment tokens](/api-reference/ticketing/tickets/ticket-attachments/). If the ticket is manually recovered, you can include the attachment tokens on the new ticket. #### Allowed For * Admins and [agents in custom roles with permission](https://support.zendesk.com/hc/en-us/articles/4408882153882#topic_cxn_hig_bd) to manage suspended tickets on Enterprise plans * Unrestricted agents on all other plans responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SuspendedTicketsAttachmentsResponse" /api/v2/suspended_tickets/destroy_many: parameters: - $ref: "#/components/parameters/SuspendedTicketsDeleteIds" delete: operationId: DeleteSuspendedTickets tags: - Suspended Tickets summary: Delete Multiple Suspended Tickets description: | Accepts up to 100 ids (the auto-generated id, not the ticket id.) #### Allowed For * Admins and [agents in custom roles with permission](https://support.zendesk.com/hc/en-us/articles/4408882153882#topic_cxn_hig_bd) to manage suspended tickets on Enterprise plans * Unrestricted agents on all other plans responses: "204": description: No Content response /api/v2/suspended_tickets/export: post: operationId: ExportSuspendedTickets tags: - Suspended Tickets summary: Export Suspended Tickets description: | Exports a list of suspended tickets for the Zendesk Support instance. To export the list, the endpoint enqueues a job to create a CSV file with the data. When done, Zendesk sends the requester an email containing a link to the CSV file. In the CSV, tickets are sorted by the update timestamp in ascending order. #### Allowed For * Admins and [agents in custom roles with permission](https://support.zendesk.com/hc/en-us/articles/4408882153882#topic_cxn_hig_bd) to manage suspended tickets on Enterprise plans * Unrestricted agents on all other plans #### Rate limits Limited to one request per minute and up to one million records in return. The rate-limiting mechanism behaves identically to the one described in [Usage limits](/api-reference/ticketing/account-configuration/usage_limits/#monitoring-your-request-activity). We recommend using the `Retry-After` header value as described in [Catching errors caused by rate limiting](/documentation/ticketing/using-the-zendesk-api/best-practices-for-avoiding-rate-limiting#catch). responses: "200": description: Ok content: application/json: schema: $ref: "#/components/schemas/SuspendedTicketsExportResponse" /api/v2/suspended_tickets/recover_many: parameters: - $ref: "#/components/parameters/SuspendedTicketsRecoverIds" put: operationId: RecoverSuspendedTickets tags: - Suspended Tickets summary: Recover Multiple Suspended Tickets description: | Accepts up to 100 ids (the auto-generated id, not the ticket id.) Note that suspended tickets that fail to be recovered are still included in the response. #### Allowed For * Admins and [agents in custom roles with permission](https://support.zendesk.com/hc/en-us/articles/4408882153882#topic_cxn_hig_bd) to manage suspended tickets on Enterprise plans * Unrestricted agents on all other plans responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/RecoverSuspendedTicketsResponse" /api/v2/tags: get: operationId: ListTags tags: - Tags summary: List Tags description: | Lists up to the 20,000 most popular tags in the last 60 days, in decreasing popularity. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TagsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/tags/count: get: operationId: CountTags tags: - Tags summary: Count Tags description: | Returns an approximate count of tags. 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, the `refreshed_at` property in the `count` object may occasionally be null. This indicates that the count is being updated in the background and the `value` property in the `count` object is limited to 100,000 until the update is complete. #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TagCountResponse" /api/v2/target_failures: get: operationId: ListTargetFailures tags: - Target Failures summary: List Target Failures description: | Returns the 25 most recent target failures, per target. #### Stability * Development #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TargetFailuresResponse" /api/v2/target_failures/{target_failure_id}: parameters: - $ref: "#/components/parameters/TargetFailureId" get: operationId: ShowTargetFailure tags: - Target Failures summary: Show Target Failure description: | #### Stability * Development #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TargetFailureResponse" /api/v2/targets: get: operationId: ListTargets tags: - Targets summary: List Targets description: | #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TargetsResponse" post: operationId: CreateTarget tags: - Targets summary: Create Target description: | #### Allowed For * Admins responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/TargetResponse" /api/v2/targets/{target_id}: parameters: - $ref: "#/components/parameters/TargetId" get: operationId: ShowTarget tags: - Targets summary: Show Target description: | #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TargetResponse" put: operationId: UpdateTarget tags: - Targets summary: Update Target description: | #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TargetResponse" delete: operationId: DeleteTarget tags: - Targets summary: Delete Target description: | #### Allowed For * Admins responses: "204": description: No Content response /api/v2/ticket_audits: get: operationId: ListTicketAudits tags: - Ticket Audits summary: List All Ticket Audits description: | Returns ticket audits. Archived tickets are not included in the response. Use the [List Audits for a Ticket](#list-audits-for-a-ticket) endpoint to retrieve audit records for an archived ticket. To learn more about archived tickets, see [About archived tickets](https://support.zendesk.com/hc/en-us/articles/203657756). This endpoint should not be used for capturing change data. When continually chasing the tail of a cursor, some records will be skipped. For this use case, use the [Incremental Ticket Event Export API](/api-reference/ticketing/ticket-management/incremental_exports/#incremental-ticket-event-export). #### Allowed For * Admins parameters: - name: page[before] in: query description: "A [pagination cursor](/documentation/api-basics/pagination/paginating-through-lists-using-cursor-pagination) that tells the endpoint which page to start on. It should be a `meta.before_cursor` value from a previous request. Note: `page[before]` and `page[after]` can't be used together in the same request. " schema: type: string - name: page[after] in: query description: "A [pagination cursor](/documentation/api-basics/pagination/paginating-through-lists-using-cursor-pagination) that tells the endpoint which page to start on. It should be a `meta.after_cursor` value from a previous request. Note: `page[before]` and `page[after]` can't be used together in the same request. " schema: type: string - name: page[size] in: query description: Specifies how many records to be returned in the response. You can specify up to 100 records per page. schema: type: integer responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketAuditsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/ticket_fields: get: operationId: ListTicketFields tags: - Ticket Fields summary: List Ticket Fields description: | Returns a list of all system and custom ticket fields in your account. For end users, only the ticket fields with visible_in_portal set to true are returned. Cursor pagination returns a maximum of 100 records per page and fields are returned in the order specified by their id. If the results are not paginated, every field is returned in the response and fields are returned in the order specified by the position. You can adjust the position of ticket fields by: - Using the [Update Ticket Field](/api-reference/ticketing/tickets/ticket_fields/#update-ticket-field) endpoint - Using the [Reorder Ticket Fields](/api-reference/ticketing/tickets/ticket_fields/#reorder-ticket-fields) endpoint - Ticket Fields page in the Admin Center (**Admin Center** > **Manage** > **Ticket** > **Fields** > **Actions** > **Edit order**) These adjustments determine the order in which fields are displayed in various locations. For accounts without access to multiple ticket forms, the order will also be used to display field values within tickets. However, for accounts with access to multiple ticket forms, the field order on the ticket page is defined within each form. Consider caching this resource to use with the [Tickets](/api-reference/ticketing/tickets/tickets/#json-format) API. #### Pagination - Cursor pagination (recommended) - No pagination See [Pagination](/api-reference/introduction/pagination/). #### Sideloads The following sideloads are supported: | Name | Will sideload | ---------------- | ------------- | users | The user or users that created the ticket field #### Allowed For * Anyone parameters: - name: locale in: query description: | Forces the `title_in_portal` property to return a dynamic content variant for the specified locale. Only accepts [active locale ids](/api-reference/ticketing/account-configuration/locales/#list-locales). Example: `locale="de"`. schema: type: string - name: creator in: query description: | Displays the `creator_user_id` and `creator_app_name` properties. If the ticket field is created by an app, `creator_app_name` is the name of the app and `creator_user_id` is `-1`. If the ticket field is not created by an app, `creator_app_name` is null schema: type: boolean - name: page[size] in: query description: Number of records per page (required for cursor pagination) required: false schema: type: integer minimum: 1 maximum: 100 default: 100 - name: page[after] in: query description: Cursor for pagination (opaque string) required: false schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketFieldsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateTicketField tags: - Ticket Fields summary: Create Ticket Field description: | Creates any of the following custom field types: | Custom field type | Description | |-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| | text | Default custom field type when `type` is not specified | | textarea | For multi-line text | | checkbox | To capture a boolean value. Allowed values are true or false. Optionally, you can specify a tag to be added to the ticket when the value is true. | | date | Example: 2021-04-16 | | integer | String composed of numbers. May contain an optional decimal point | | decimal | For numbers containing decimals | | regexp | Matches the Regex pattern found in the custom field settings | | partialcreditcard | A credit card number. Only the last 4 digits are retained | | multiselect | Enables users to choose multiple options from a dropdown menu. It contains one or more tag values belonging to the field's options. | | tagger | Single-select dropdown menu. It contains one or more tag values belonging to the field's options. Example: ( {"id": 21938362, "value": ["hd_3000", "hd_5555"]}) | | lookup | A field to create a relationship (see [lookup relationships](/api-reference/ticketing/lookup_relationships/lookup_relationships/)) to another object such as a user, ticket, or organization | **Note**: Tags can't be re-used across custom ticket fields. For example, if you configure a tag for a checkbox field, you can't use that tag value for a dropdown (tagger) field option. The use of tags isn't validated and can prevent editing in the future. See [About custom field types](https://support.zendesk.com/hc/en-us/articles/203661866) in the Zendesk Help Center. #### Allowed For * Admins #### Field limits We recommend the following best practices for ticket fields limits. Creating more than these amounts can affect performance. * 400 ticket fields per account if your account doesn't have ticket forms * 400 ticket fields per ticket form if your account has ticket forms responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/TicketFieldResponse" /api/v2/ticket_fields/{ticket_field_id}: parameters: - $ref: "#/components/parameters/TicketFieldId" - $ref: "#/components/parameters/Creator" get: operationId: ShowTicketfield tags: - Ticket Fields summary: Show Ticket Field description: | #### Allowed for * Agents #### Sideloads The following sideloads are supported: | Name | Will sideload | ---------------- | ------------- | users | The user or users that created the ticket field responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketFieldResponse" put: operationId: UpdateTicketField tags: - Ticket Fields summary: Update Ticket Field description: | #### Updating drop-down field options You can also use the update endpoint to add, update, or remove options in a drop-down custom field. Updating field options for multi-select fields works exactly the same as drop-down field options. **Important**: Unless you want to remove some options, you must specify all existing options in any update request. Omitting an option removes it from the drop-down field, which removes its values from any tickets or macros. Use the `custom_field_options` attribute to update the options. The attribute consists of an array of option objects, with each object consisting of a `name` and `value` property. The properties correspond to the "Title" and "Tag" text boxes in the admin interface. Example request body: ```json {"ticket_field": { "custom_field_options": [ {"name": "Apple Pie", "value": "apple"}, {"name": "Pecan Pie", "value": "pecan"} ] } } ``` #### Example Request ```bash curl https://{subdomain}.zendesk.com/api/v2/ticket_fields/{id}.json \ -d '{"ticket_field": {"custom_field_options": [{"name": "Apple Pie", "value": "apple"}, {"name": "Pecan Pie", "value": "pecan"}]}}' \ -H "Content-Type: application/json" -X PUT \ -v -u {email_address}/token:{api_token} ``` #### Example Response ```http Status: 200 OK { "ticket_field": { "id":21938362, "type":"tagger", "title":"Pies", ... "custom_field_options": [ { "id":21029772, "name":"Apple Pie", "raw_name":"Apple Pie", "value":"apple", "default":false }, ... ] } } ``` #### Allowed for * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketFieldResponse" delete: operationId: DeleteTicketField tags: - Ticket Fields summary: Delete Ticket Field description: | #### Allowed for * Admins responses: "204": description: No Content response /api/v2/ticket_fields/{ticket_field_id}/options: parameters: - $ref: "#/components/parameters/TicketFieldId" get: operationId: ListTicketFieldOptions tags: - Ticket Fields summary: List Ticket Field Options description: | Returns a list of custom ticket field options for the given drop-down ticket field. #### Allowed For * Agents #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CustomFieldOptionsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateOrUpdateTicketFieldOption tags: - Ticket Fields summary: Create or Update Ticket Field Option description: | Creates or updates an option for the given drop-down ticket field. To update an option, include the id of the option in the `custom_field_option` object. Example: `{"custom_field_option": {"id": 10002, "name": "Pineapples", ... }` If an option exists for the given ID, the option will be updated. Otherwise, a new option will be created. #### Response Returns one of the following status codes: - 200 with `Location: /api/v2/ticket_fields/{ticket_field_id}/options.json` if the ticket field option already exists in the database - 201 with `Location: /api/v2/ticket_fields/{ticket_field_id}/options.json` if the ticket field option is new #### Allowed For * Admins #### Rate Limit You can make 100 requests every 1 minute using this endpoint. The rate limiting mechanism behaves as described in [Monitoring your request activity](/api-reference/ticketing/account-configuration/usage_limits/#monitoring-your-request-activity) in the API introduction. #### Field Option Limits * 2000 options per ticket field responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CustomFieldOptionResponse" "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/CustomFieldOptionResponse" /api/v2/ticket_fields/{ticket_field_id}/options/{ticket_field_option_id}: parameters: - $ref: "#/components/parameters/TicketFieldId" - $ref: "#/components/parameters/TicketFieldOptionId" get: operationId: ShowTicketFieldOption tags: - Ticket Fields summary: Show Ticket Field Option description: | #### Allowed for * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CustomFieldOptionResponse" delete: operationId: DeleteTicketFieldOption tags: - Ticket Fields summary: Delete Ticket Field Option description: | #### Allowed for * Admins responses: "204": description: No Content response /api/v2/ticket_fields/count: get: operationId: CountTicketFields tags: - Ticket Fields summary: Count Ticket Fields description: |- Returns an approximate count of system and custom ticket fields in the account. If the count exceeds 100,000, the count will return a cached result. This cached result will update every 24 hours. The `count[refreshed_at]` property is a timestamp that indicates when the count was last updated. **Note**: When the count exceeds 100,000, `count[refreshed_at]` may occasionally be null. This indicates that the count is being updated in the background, and `count[value]` is limited to 100,000 until the update is complete. #### Allowed For * Agents responses: "200": description: Count of ticket fields content: application/json: schema: $ref: "#/components/schemas/TicketFieldCountResponse" /api/v2/ticket_fields/reorder: put: operationId: ReorderTicketFields tags: - Ticket Fields summary: Reorder Ticket Fields description: | #### Allowed For * Admins #### Request Parameters You can pass in the following parameter in the payload: | Name | Type | Comment | ------------------- | ------ | -------- | ticket_field_ids | array | An array of ticket field ids. Example: "[2, 23, 46, 50]". Not all ticket_field_ids are necessary in the payload; only those provided will be assigned to the first positions. Missing IDs will be assigned incremental positions automatically. responses: "200": description: Success response content: application/json: schema: type: string description: Empty response /api/v2/ticket_form_statuses: get: operationId: ListTicketFormStatuses tags: - Ticket Form Statuses summary: List Ticket Form Statuses description: | Fetches all of the ticket form statuses for the account. #### Allowed For * Admins * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketFormStatusesResponse" /api/v2/ticket_form_statuses/show_many: get: operationId: ShowManyTicketFormStatuses tags: - Ticket Form Statuses summary: Show Many Ticket Form Statuses description: | Fetches all of the ticket form statuses specified by a comma separated list of ids. #### Allowed For * Admins * Agents parameters: - name: ids in: query description: Ticket form status ids to retrieve records for required: true schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketFormStatusesResponse" /api/v2/ticket_forms: get: operationId: ListTicketForms tags: - Ticket Forms summary: List Ticket Forms description: | Returns a list of all ticket forms for your account if accessed as an admin or agent. End users only see ticket forms that have `end_user_visible` set to true. #### Allowed For * Anyone parameters: - name: active in: query description: true returns active ticket forms; false returns inactive ticket forms. If not present, returns both schema: type: boolean - name: end_user_visible in: query description: true returns ticket forms where `end_user_visible`; false returns ticket forms that are not end-user visible. If not present, returns both schema: type: boolean - name: fallback_to_default in: query description: true returns the default ticket form when the criteria defined by the parameters results in a set without active and end-user visible ticket forms schema: type: boolean - name: associated_to_brand in: query description: true returns the ticket forms of the brand specified by the url's subdomain schema: type: boolean responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketFormsResponse" post: operationId: CreateTicketForm tags: - Ticket Forms summary: Create Ticket Form description: | #### Allowed For * Admins responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/TicketFormResponse" /api/v2/ticket_forms/{ticket_form_id}: parameters: - $ref: "#/components/parameters/TicketFormId" get: operationId: ShowTicketForm tags: - Ticket Forms summary: Show Ticket Form description: | #### Allowed For * Admins, Agents, and End Users responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketFormResponse" put: operationId: UpdateTicketForm tags: - Ticket Forms summary: Update Ticket Form description: | #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketFormResponse" delete: operationId: DeleteTicketForm tags: - Ticket Forms summary: Delete Ticket Form description: | #### Allowed For * Admins responses: "204": description: No Content response /api/v2/ticket_forms/{ticket_form_id}/clone: parameters: - $ref: "#/components/parameters/TicketFormId" post: operationId: CloneTicketForm tags: - Ticket Forms summary: Clone an Already Existing Ticket Form description: | #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketFormResponse" /api/v2/ticket_forms/{ticket_form_id}/ticket_form_statuses: parameters: - $ref: "#/components/parameters/TicketFormId" get: operationId: TicketFormTicketFormStatuses tags: - Ticket Forms - Ticket Form Statuses summary: List Ticket Form Statuses of a Ticket Form description: | Fetches all of the associated ticket form statuses of a ticket form. #### Allowed For * Admins * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketFormStatusesResponse" post: operationId: CreateTicketFormStatuses tags: - Ticket Forms - Ticket Form Statuses summary: Create Ticket Form Statuses description: | Creates one or many ticket form status associations #### Allowed For * Admins requestBody: content: application/json: schema: $ref: "#/components/schemas/TicketFormStatusesParams" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketFormStatusesResponse" put: operationId: UpdateTicketFormStatuses tags: - Ticket Forms - Ticket Form Statuses summary: Bulk Update Ticket Form Statuses of a Ticket Form description: | Updates or deletes ticket form status associations. This is a bulk operation that can both add and remove ticket form status associations for a form in one call. #### Allowed For * Admins requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateTicketFormStatusesParams" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketFormStatusesResponse" delete: operationId: DeleteTicketFormStatuses tags: - Ticket Form Statuses summary: Delete Ticket Form Statuses description: | Deletes all of of the ticket form statuses by id. #### Allowed For * Admins * Agents responses: "204": description: Success response /api/v2/ticket_forms/{ticket_form_id}/ticket_form_statuses/{ticket_form_status_id}: parameters: - $ref: "#/components/parameters/TicketFormId" - $ref: "#/components/parameters/TicketFormStatusId" put: operationId: UpdateTicketFormStatusById tags: - Ticket Forms - Ticket Form Statuses summary: Update Ticket Form Status By Id description: | Updates or deletes ticket form status association by id. #### Allowed For * Admins requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateTicketFormStatusesParams" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketFormStatusesResponse" delete: operationId: DeleteTicketFormStatusById tags: - Ticket Form Statuses summary: Delete Ticket Form Status By Id description: | Deletes a ticket form status by id. #### Allowed For * Admins responses: "204": description: Success response /api/v2/ticket_forms/reorder: put: operationId: ReorderTicketForms tags: - Ticket Forms summary: Reorder Ticket Forms description: | #### Allowed For * Admins #### Request Parameters You can pass in the following parameter in the payload: | Name | Type | Comment | ------------------- | ------ | -------- | ticket_form_ids | array | An array of ticket form ids. Example: "[2, 23, 46, 50]" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketFormsResponse" /api/v2/ticket_forms/show_many: get: operationId: ShowManyTicketForms tags: - Ticket Forms summary: Show Many Ticket Forms description: | Takes an `ids` query parameter that accepts a comma-separated list of up to 100 ticket form ids. This endpoint is used primarily by the [mobile SDK](/documentation/classic-web-widget-sdks/) and the [Web Widget](/api-reference/widget/introduction/). #### Allowed For * Anyone parameters: - name: ids in: query description: IDs of the ticket forms to be shown required: true schema: type: string - name: active in: query description: true returns active ticket forms; false returns inactive ticket forms. If not present, returns both schema: type: boolean - name: end_user_visible in: query description: true returns ticket forms where `end_user_visible`; false returns ticket forms that are not end-user visible. If not present, returns both schema: type: boolean - name: fallback_to_default in: query description: true returns the default ticket form when the criteria defined by the parameters results in a set without active and end-user visible ticket forms schema: type: boolean - name: associated_to_brand in: query description: true returns the ticket forms of the brand specified by the url's subdomain schema: type: boolean responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketFormsResponse" /api/v2/ticket_metrics: get: operationId: ListTicketMetrics tags: - Ticket Metrics summary: List Ticket Metrics description: | Returns a list of tickets with their metrics. Tickets are ordered chronologically by created date, from newest to oldest. The last ticket listed may not be the absolute oldest ticket in your account due to ticket archiving. Archived tickets are not included in the response. See [About archived tickets](https://support.zendesk.com/hc/en-us/articles/203657756) in Zendesk help. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketMetricsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/ticket_metrics/{ticket_metric_id}: get: operationId: ShowTicketMetrics tags: - Ticket Metrics summary: Show Ticket Metrics description: | Returns a specific metric, or the metrics of a specific ticket. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - name: ticket_metric_id in: path description: The id of the ticket metric to retrieve required: true schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketMetricsByTicketMetricIdResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/tickets: get: operationId: ListTickets tags: - Tickets summary: List Tickets parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - name: sort in: query description: Sort tickets by field (for cursor pagination use "field" for ascending or "-field" for descending) required: false schema: type: string enum: - updated_at - id - status - -updated_at - -id - -status default: id - name: external_id in: query description: Lists tickets by external id. External ids don't have to be unique for each ticket. As a result, the request may return multiple tickets with the same external id. schema: type: string responses: "200": description: List tickets content: application/json: schema: $ref: "#/components/schemas/TicketsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateTicket tags: - Tickets summary: Create Ticket requestBody: content: application/json: schema: $ref: "#/components/schemas/TicketCreateRequest" responses: "201": description: Create ticket headers: Location: description: The URL of the created ticket schema: type: string format: url content: application/json: schema: $ref: "#/components/schemas/TicketResponse" /api/v2/tickets/{ticket_id}: get: operationId: ShowTicket tags: - Tickets summary: Show Ticket description: |- Returns a number of ticket properties though not the ticket comments. To get the comments, use [List Comments](/api-reference/ticketing/tickets/ticket_comments/#list-comments) #### Allowed For * Agents parameters: - $ref: "#/components/parameters/TicketId" responses: "200": description: Ticket content: application/json: schema: $ref: "#/components/schemas/TicketResponse" put: operationId: UpdateTicket tags: - Tickets summary: Update Ticket parameters: - $ref: "#/components/parameters/TicketId" requestBody: content: application/json: schema: $ref: "#/components/schemas/TicketUpdateRequest" responses: "200": description: Successful request content: application/json: schema: $ref: "#/components/schemas/TicketUpdateResponse" delete: operationId: DeleteTicket tags: - Tickets summary: Delete Ticket description: |- #### Allowed For * Admins * Agents with permission to delete tickets Agent delete permissions are set in Support. See [Deleting tickets](https://support.zendesk.com/hc/en-us/articles/203690936) in the Support Help Center. #### Ticket deletion rate limit You can delete 400 tickets every 1 minute using this endpoint. The rate limiting mechanism behaves as described in [Rate limits](/api-reference/introduction/rate-limits/) in the API introduction. Zendesk recommends that you obey the Retry-After header values. To delete many tickets, you may use [Bulk Delete Tickets](/api-reference/ticketing/tickets/tickets/#bulk-delete-tickets). parameters: - $ref: "#/components/parameters/TicketId" responses: "204": description: No content /api/v2/tickets/{ticket_id}/audits: parameters: - $ref: "#/components/parameters/TicketId" get: operationId: ListAuditsForTicket tags: - Ticket Audits summary: List Audits for a Ticket description: | Lists the audits for a specified ticket. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. **Note**: Audits for [Archived Tickets](https://support.zendesk.com/hc/en-us/articles/4408887617050) do not support pagination for this endpoint. #### Allowed for * Agents parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: OK response content: application/json: schema: $ref: "#/components/schemas/TicketAuditsResponseNoneCursor" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/tickets/{ticket_id}/audits/{ticket_audit_id}: parameters: - $ref: "#/components/parameters/TicketId" - $ref: "#/components/parameters/TicketAuditId" get: operationId: ShowTicketAudit tags: - Ticket Audits summary: Show Audit description: | #### Allowed for * Agents responses: "200": description: OK response content: application/json: schema: $ref: "#/components/schemas/TicketAuditResponse" /api/v2/tickets/{ticket_id}/audits/{ticket_audit_id}/make_private: parameters: - $ref: "#/components/parameters/TicketId" - $ref: "#/components/parameters/TicketAuditId" put: operationId: MakeTicketCommentPrivateFromAudits tags: - Ticket Audits summary: Change a Comment From Public To Private description: | #### Allowed for * Agents responses: "200": description: description content: application/json: schema: type: string description: Empty response /api/v2/tickets/{ticket_id}/audits/count: parameters: - $ref: "#/components/parameters/TicketId" get: operationId: CountAuditsForTicket tags: - Ticket Audits summary: Count Audits for a Ticket description: | Returns an approximate count of audits for a specified ticket. If the count exceeds 100,000, the count will return a cached result. This cached result will update every 24 hours. The `count[refreshed_at]` property is a timestamp that indicates when the count was last updated. **Note**: If the total number of audits for a ticket exceeds 100,000, this endpoint returns a count of 100,000 with a `count[refreshed_at]` value of null. This value is cached for 24 hours, during which any requests returns the same count and timestamp. After 24 hours, the endpoint temporarily shows the same count again before providing an updated total. #### Allowed for * Agents responses: "200": description: Count of audits on a ticket content: application/json: schema: $ref: "#/components/schemas/TicketAuditsCountResponse" /api/v2/tickets/{ticket_id}/collaborators: get: operationId: ListTicketCollaborators tags: - Tickets summary: List Collaborators for a Ticket description: |- #### Allowed For * Agents parameters: - $ref: "#/components/parameters/TicketId" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/ListTicketCollaboratorsResponse" /api/v2/tickets/{ticket_id}/comments: parameters: - $ref: "#/components/parameters/TicketId" get: operationId: ListTicketComments tags: - Ticket Comments summary: List Comments description: | Returns the comments added to the ticket. Each comment may include a `content_url` for an attachment or a `recording_url` for a voice comment that points to a file that may be hosted externally. For security reasons, take care not to inadvertently send Zendesk authentication credentials to third parties when attempting to access these files. See [Working with url properties](/documentation/ticketing/managing-tickets/working-with-url-properties). #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Sorting By default, comments are sorted by creation date in ascending order. When using cursor pagination, use the following parameter to change the sort order: | Name | Type | Required | Comments | ------ | ------ | -------- | -------- | `sort` | string | no | Possible values are "created_at" (ascending order) or "-created_at" (descending order) When using offset pagination, use the following parameters to change the sort order: | Name | Type | Required | Comments | ------------ | ------ | -------- | -------- | `sort_order` | string | no | One of `asc`, `desc`. Defaults to `asc` #### Allowed For * Agents parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - name: sort in: query description: Sort order - "created_at" (ascending) or "-created_at" (descending) required: false schema: type: string enum: - created_at - -created_at default: created_at - name: include_inline_images in: query description: Default is false. When true, inline images are also listed as attachments in the response schema: type: boolean - name: include in: query description: 'Accepts "users". Use this parameter to list email CCs by side-loading users. Example: `?include=users`. **Note**: If the comment source is email, a deleted user will be represented as the CCd email address. If the comment source is anything else, a deleted user will be represented as the user name.' schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketCommentsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/tickets/{ticket_id}/comments/{comment_id}/attachments/{attachment_id}/redact: parameters: - $ref: "#/components/parameters/TicketId" - $ref: "#/components/parameters/CommentId" - $ref: "#/components/parameters/AttachmentId" put: operationId: RedactCommentAttachment tags: - Attachments summary: Redact Comment Attachment description: | Redaction allows you to permanently remove attachments from an existing comment on a ticket. Once removed from a comment, the attachment is replaced with an empty "redacted.txt" file. The redaction is permanent. It is not possible to undo redaction or see what was removed. Once a ticket is closed, redacting its attachments is no longer possible. Also, if you want to redact an inline attachment, you can use the `include_inline_images` parameter in the [List Comments](/api-reference/ticketing/tickets/ticket_comments/#list-comments) operation to obtain the inline attachment ID, and use it in the request URL. #### Allowed For * Admins * Agents when [deleting tickets is enabled for agents on professional accounts](https://support.zendesk.com/hc/en-us/articles/360002128107) * Agents assigned to a custom role with permissions to redact ticket content (Enterprise only) responses: "200": description: OK response content: application/json: schema: $ref: "#/components/schemas/AttachmentResponse" /api/v2/tickets/{ticket_id}/comments/{ticket_comment_id}/make_private: parameters: - $ref: "#/components/parameters/TicketId" - $ref: "#/components/parameters/TicketCommentId" put: operationId: MakeTicketCommentPrivate tags: - Ticket Comments summary: Make Comment Private description: | #### Allowed For * Agents responses: "200": description: description content: application/json: schema: type: string description: Empty response /api/v2/tickets/{ticket_id}/comments/{ticket_comment_id}/redact: parameters: - $ref: "#/components/parameters/TicketId" - $ref: "#/components/parameters/TicketCommentId" put: operationId: RedactStringInComment tags: - Ticket Comments summary: Redact String in Comment description: "Permanently removes words or strings from a ticket comment. Specify\ \ the string to redact in an object with a `text` property. Example: `'{\"\ text\": \"987-65-4320\"}'`. The characters of the word or string are replaced\ \ by the \u2587 symbol.\n\nIf the comment was made by email, the endpoint\ \ also attempts to redact the string from the original email retained by Zendesk\ \ for audit purposes.\n\n**Note**: If you use the rich text editor, support\ \ for redacting formatted text (bold, italics, hyperlinks) is limited.\n\n\ Redaction is permanent. You can't undo the redaction or see *what* was removed.\ \ Once a ticket is closed, you can no longer redact strings from its comments.\n\ \nTo use this endpoint, the \"Agents can delete tickets\" option must be enabled\ \ in the Zendesk Support admin interface at **Admin** > **Settings** > **Agents**.\n\ \n#### Allowed For\n\n* Agents\n" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketCommentResponse" /api/v2/tickets/{ticket_id}/comments/count: get: operationId: CountTicketComments tags: - Ticket Comments summary: Count Ticket Comments description: |- Returns an approximate count of the comments added to the ticket. If the count exceeds 100,000, the count will return a cached result. This cached result will update every 24 hours. The `count[refreshed_at]` property is a timestamp that indicates when the count was last updated. **Note**: When the count exceeds 100,000, `count[refreshed_at]` may occasionally be null. This indicates that the count is being updated in the background, and `count[value]` is limited to 100,000 until the update is complete. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/TicketId" responses: "200": description: Count of ticket comments content: application/json: schema: $ref: "#/components/schemas/TicketCommentsCountResponse" /api/v2/tickets/{ticket_id}/conversation_log: get: operationId: ListConversationLogForTicket tags: - Conversation Log summary: List Conversation log for Ticket description: | Lists the conversation log events for a specified ticket. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed for * Agents parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - $ref: "#/components/parameters/TicketId" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/ConversationLogResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/tickets/{ticket_id}/email_ccs: get: operationId: ListTicketEmailCCs tags: - Tickets summary: List Email CCs for a Ticket description: |- Returns any users cc'd on the ticket. #### Availability The [CCs and Followers](https://support.zendesk.com/hc/en-us/articles/203690846) feature must be enabled in Zendesk Support. If the feature is not enabled, the default CC functionality is used. In that case, use [List Collaborators](/api-reference/ticketing/tickets/tickets/#list-collaborators-for-a-ticket) to list the users cc'ed on the ticket. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/TicketId" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/ListTicketEmailCCsResponse" /api/v2/tickets/{ticket_id}/followers: get: operationId: ListTicketFollowers tags: - Tickets summary: List Followers for a Ticket description: |- Returns any users who follow the ticket. #### Availability The [CCs and Followers](https://support.zendesk.com/hc/en-us/articles/203690846) feature must be enabled in Zendesk Support. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/TicketId" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/ListTicketFollowersResponse" /api/v2/tickets/{ticket_id}/incidents: get: operationId: ListTicketIncidents tags: - Tickets summary: List Ticket Incidents description: |- #### Allowed For * Agents #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - $ref: "#/components/parameters/TicketId" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/ListTicketIncidentsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/tickets/{ticket_id}/macros/{macro_id}/apply: parameters: - $ref: "#/components/parameters/MacroId" - name: ticket_id in: path description: The ID of the ticket required: true schema: type: integer get: operationId: ShowTicketAfterChanges tags: - Macros summary: Show Ticket After Changes description: | Returns the full ticket object as it would be after applying the macro to the ticket. It doesn't actually change the ticket. To get only the ticket fields that would be changed by the macro, see [Show Changes to Ticket](#show-changes-to-ticket). #### Allowed For * Agents responses: "200": description: Success Response content: application/json: schema: $ref: "#/components/schemas/MacroApplyTicketResponse" /api/v2/tickets/{ticket_id}/mark_as_spam: put: operationId: MarkTicketAsSpamAndSuspendRequester tags: - Tickets summary: Mark Ticket as Spam and Suspend Requester description: |- #### Allowed For * Agents parameters: - $ref: "#/components/parameters/TicketId" responses: "200": description: Successful response content: application/json: schema: type: string /api/v2/tickets/{ticket_id}/merge: post: operationId: MergeTicketsIntoTargetTicket tags: - Tickets summary: Merge Tickets into Target Ticket description: |- Merges one or more tickets into the ticket with the specified id. See [Merging tickets](https://support.zendesk.com/hc/en-us/articles/203690916) in the Support Help Center for ticket merging rules. Any attachment to the source ticket is copied to the target ticket. This endpoint returns a `job_status` [JSON object](/api-reference/ticketing/ticket-management/job_statuses/#json-format) and queues a background job to do the work. Use the [Show Job Status](/api-reference/ticketing/ticket-management/job_statuses/#show-job-status) endpoint to check for the job's completion. Only a certain number of jobs can be queued or running at the same time. See [Job limit](/api-reference/introduction/rate-limits/#job-limit) for more information. #### Allowed For * Agents Agents in the Enterprise account must have merge permissions. See [Creating custom roles and assigning agents (Enterprise)](https://support.zendesk.com/hc/en-us/articles/203662026) in the Support Help Center. #### Available parameters The request takes a data object with the following properties: | Name | Type | Required | Comments | | ------------------------ | ------- | -------- | ------------------------------------------------------- | | ids | array | yes | Ids of tickets to merge into the target ticket | | target_comment | string | no | Private comment to add to the target ticket. This comment is optional but strongly recommended | | source_comment | string | no | Private comment to add to the source ticket. This comment is optional but strongly recommended | | target_comment_is_public | boolean | no | Whether comments in the target ticket are public or private | | source_comment_is_public | boolean | no | Whether comments in the source tickets are public or private | `target_comment` and `source_comment` can be used to provide a reason for the merge for recordkeeping purposes. If the source ticket has attachments, they are included in `target_comment`. Comments are private and can't be modified in the following cases: * Any of the sources or target tickets are private * Any of the sources or target tickets were created through X (formerly Twitter), Facebook or the Channel framework In any other case, comments default to private but can be modified with the comment privacy parameters. parameters: - $ref: "#/components/parameters/TicketId" requestBody: content: application/json: schema: $ref: "#/components/schemas/TicketMergeInput" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" /api/v2/tickets/{ticket_id}/related: get: operationId: TicketRelatedInformation tags: - Tickets summary: Ticket Related Information description: |- The request returns a data object with the following properties: | Name | Type | Comment | ------------------- | ------- | ------- | topic_id | string | Related topic in the Web portal (deprecated feature) | jira_issue_ids | array | Array of associated jira issues | followup_source_ids | array | Sources to follow up | from_archive | boolean | Is true if the current ticket is archived | incidents | integer | A count of related incident occurrences #### Allowed For * Agents parameters: - $ref: "#/components/parameters/TicketId" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/TicketRelatedInformation" /api/v2/tickets/{ticket_id}/satisfaction_rating: parameters: - name: ticket_id in: path description: The id of the ticket required: true schema: type: integer post: operationId: CreateTicketSatisfactionRating tags: - Satisfaction Ratings summary: Create a Satisfaction Rating description: | Creates a CSAT rating for a solved ticket, or for a ticket that was previously solved and then reopened. Only the end user listed as the ticket requester can create a satisfaction rating for the ticket. #### Allowed For * End user who requested the ticket The end user must be a verified user. responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SatisfactionRatingResponse" /api/v2/tickets/{ticket_id}/tags: parameters: - $ref: "#/components/parameters/TicketId" get: operationId: listTicketTags tags: - Tags summary: List Ticket Tags description: | Lists all tags associated with a specific ticket. #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TagsResponse" "404": $ref: "#/components/responses/NotFound" post: operationId: setTicketTags tags: - Tags summary: Set Ticket Tags description: | Replaces all existing tags on a ticket with the provided tags. #### Allowed For * Agents requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/TagsRequest" responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/TagsResponse" "404": $ref: "#/components/responses/NotFound" put: operationId: addTicketTags tags: - Tags summary: Add Tags description: | You can also add tags to multiple tickets with the [Update Many Tickets](/api-reference/ticketing/tickets/tickets/#update-many-tickets) endpoint. #### Safe Update If the same ticket is updated by multiple API requests at the same time, some tags could be lost because of ticket update collisions. Include `updated_stamp` and `safe_update` properties in the request body to make a safe update. For `updated_stamp`, retrieve and specify the ticket's latest `updated_at` timestamp. The tag update only occurs if the `updated_stamp` timestamp matches the ticket's actual `updated_at` timestamp at the time of the request. If the timestamps don't match (in other words, if the ticket was updated since you retrieved the ticket's last `updated_at` timestamp), the request returns a 409 Conflict error. #### Example ```js { "tags": ["customer"], "updated_stamp":"2019-09-12T21:45:16Z", "safe_update":"true" } ``` For details, see [Protecting against ticket update collisions](/api-reference/ticketing/tickets/tickets/#protecting-against-ticket-update-collisions). #### Allowed For * Agents requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SafeTagsRequest" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TagsResponse" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" delete: operationId: removeTicketTags tags: - Tags summary: Remove Ticket Tags description: "Removes specified tags from a ticket. You can also delete tags\ \ from multiple tickets \nwith the Update Many Tickets endpoint.\n\nThis endpoint\ \ supports safe updates. See the PUT endpoint documentation for details.\n\ \n#### Allowed For\n* Agents\n" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SafeTagsRequest" responses: "204": description: No Content - Tags successfully removed "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" /api/v2/tickets/count: get: operationId: CountTickets tags: - Tickets summary: Count Tickets description: |- Returns an approximate count of tickets in the account. If the count exceeds 100,000, it is updated every 24 hours. `ccd` lists tickets that the specified user is cc'd on. The `count[refreshed_at]` property is a timestamp that indicates when the count was last updated. **Note**: When the count exceeds 100,000, `count[refreshed_at]` may occasionally be null. This indicates that the count is being updated in the background, and `count[value]` is limited to 100,000 until the update is complete. #### Allowed For * Agents responses: "200": description: Count of tickets content: application/json: schema: type: object properties: count: type: object properties: refreshed_at: type: string format: date-time value: type: integer /api/v2/tickets/create_many: post: operationId: TicketsCreateMany tags: - Tickets summary: Create Many Tickets description: |- Accepts an array of up to 100 ticket objects. **Note**: Every ticket created with this endpoint may be affected by your business rules, which can include sending email notifications to your end users. If you are importing historical tickets or creating more than 1000 tickets, consider using the [Ticket Bulk Import](/api-reference/ticketing/tickets/ticket_import/#ticket-bulk-import) endpoint. This endpoint returns a `job_status` [JSON object](/api-reference/ticketing/ticket-management/job_statuses/#json-format) and queues a background job to do the work. Use the [Show Job Status](/api-reference/ticketing/ticket-management/job_statuses/#show-job-status) endpoint to check for the job's completion. Only a certain number of jobs can be queued or running at the same time. See [Job limit](/api-reference/introduction/rate-limits/#job-limit) for more information. #### Allowed For * Agents requestBody: content: application/json: schema: $ref: "#/components/schemas/TicketsCreateRequest" responses: "200": description: Create many tickets content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" /api/v2/tickets/destroy_many: delete: operationId: BulkDeleteTickets tags: - Tickets summary: Bulk Delete Tickets description: |- Accepts a comma-separated list of up to 100 ticket ids. #### Allowed For * Admins * Agents with permission to delete tickets Agent delete permissions are set in Support. See [Deleting tickets](https://support.zendesk.com/hc/en-us/articles/203690936) in the Support Help Center. This endpoint returns a `job_status` [JSON object](/api-reference/ticketing/ticket-management/job_statuses/#json-format) and queues a background job to do the work. Use the [Show Job Status](/api-reference/ticketing/ticket-management/job_statuses/#show-job-status) endpoint to check for the job's completion. Only a certain number of jobs can be queued or running at the same time. See [Job limit](/api-reference/introduction/rate-limits/#job-limit) for more information. parameters: - $ref: "#/components/parameters/TicketIds" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" /api/v2/tickets/mark_many_as_spam: put: operationId: MarkManyTicketsAsSpam tags: - Tickets summary: Bulk Mark Tickets as Spam description: |- Accepts a comma-separated list of up to 100 ticket ids. This endpoint returns a `job_status` [JSON object](/api-reference/ticketing/ticket-management/job_statuses/#json-format) and queues a background job to do the work. Use the [Show Job Status](/api-reference/ticketing/ticket-management/job_statuses/#show-job-status) endpoint to check for the job's completion. Only a certain number of jobs can be queued or running at the same time. See [Job limit](/api-reference/introduction/rate-limits/#job-limit) for more information. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/TicketIds" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" /api/v2/tickets/show_many: get: operationId: TicketsShowMany tags: - Tickets summary: Show Multiple Tickets description: |- Accepts a comma-separated list of ticket ids to return. This endpoint will return up to 100 tickets records. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/TicketIds" responses: "200": description: List tickets content: application/json: schema: $ref: "#/components/schemas/TicketsResponse" /api/v2/tickets/update_many: put: operationId: TicketsUpdateMany tags: - Tickets summary: Update Many Tickets description: Accepts an array of up to 100 ticket objects, or a comma-separated list of up to 100 ticket ids. parameters: - name: ids in: query description: Comma-separated list of ticket ids schema: type: string requestBody: required: false content: application/json: schema: $ref: "#/components/schemas/TicketsUpdateManyRequestBody" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" /api/v2/trigger_categories: get: operationId: ListTriggerCategories tags: - Trigger Categories summary: List Ticket Trigger Categories description: | Returns all the ticket trigger categories in the account. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - name: page in: query description: Pagination parameters style: deepObject explode: true schema: type: object properties: after: type: string before: type: string size: type: integer - name: sort in: query description: Sort parameters schema: type: string enum: - position - -position - name - -name - created_at - -created_at - updated_at - -updated_at - name: include in: query description: Allowed sideloads schema: type: string enum: - rule_counts responses: "200": description: A paged array of ticket trigger categories content: application/json: schema: allOf: - $ref: "#/components/schemas/TriggerCategoriesResponse" - $ref: "#/components/schemas/Pagination" "400": description: Error content: application/json: schema: $ref: "#/components/schemas/Errors" "403": description: Error content: application/json: schema: $ref: "#/components/schemas/Errors" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateTriggerCategory tags: - Trigger Categories summary: Create Ticket Trigger Category description: Creates a ticket trigger category. requestBody: required: true content: application/json: schema: type: object properties: trigger_category: allOf: - $ref: "#/components/schemas/TriggerCategoryRequest" - $ref: "#/components/schemas/TriggerCategoryRequestRequired" responses: "200": description: The created ticket trigger category content: application/json: schema: $ref: "#/components/schemas/TriggerCategoryResponse" "400": description: Error content: application/json: schema: $ref: "#/components/schemas/Errors" "403": description: Error content: application/json: schema: $ref: "#/components/schemas/Errors" /api/v2/trigger_categories/{trigger_category_id}: get: operationId: ShowTriggerCategoryById tags: - Trigger Categories summary: Show Ticket Trigger Category description: Returns the ticket trigger category with the specified ID. parameters: - name: trigger_category_id in: path description: The id of the ticket trigger category to retrieve required: true schema: type: string responses: "200": description: The requested ticket trigger category content: application/json: schema: $ref: "#/components/schemas/TriggerCategoryResponse" "404": description: Error content: application/json: schema: $ref: "#/components/schemas/Errors" patch: operationId: UpdateTriggerCategory tags: - Trigger Categories summary: Update Ticket Trigger Category description: Updates the ticket trigger category with the specified ID. parameters: - name: trigger_category_id in: path description: The id of the ticket trigger category to update required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: trigger_category: $ref: "#/components/schemas/TriggerCategoryRequest" responses: "200": description: The updated trigger category content: application/json: schema: $ref: "#/components/schemas/TriggerCategoryResponse" "400": description: Error content: application/json: schema: $ref: "#/components/schemas/Errors" "404": description: Error content: application/json: schema: $ref: "#/components/schemas/Errors" delete: operationId: DeleteTriggerCategory tags: - Trigger Categories summary: Delete Ticket Trigger Category description: Deletes the ticket trigger category with the specified ID. parameters: - name: trigger_category_id in: path description: The id of the ticket trigger category to delete required: true schema: type: string responses: "204": description: No content "400": description: Error content: application/json: schema: $ref: "#/components/schemas/Errors" "404": description: Error content: application/json: schema: $ref: "#/components/schemas/Errors" /api/v2/trigger_categories/jobs: post: operationId: BatchOperateTriggerCategories tags: - Trigger Categories summary: Create Batch Job for Ticket Trigger Categories description: Creates a job that performs a batch operation for the given ticket trigger categories. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/BatchJobRequest" responses: "200": description: The response to the batch job content: application/json: schema: $ref: "#/components/schemas/BatchJobResponse" "400": description: Error content: application/json: schema: $ref: "#/components/schemas/BatchJobResponse" /api/v2/triggers: get: operationId: ListTriggers tags: - Triggers summary: List Ticket Triggers description: | Lists all ticket triggers for the current account. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents #### Sideloads The following sideloads are supported. The usage sideloads are only supported on the Support Professional or Suite Growth plan or above. | Name | Will sideload | ---------------- | ------------- | app_installation | The app installation that requires each trigger, if present | permissions | The permissions for each trigger | usage_1h | The number of times each trigger has been used in the past hour | usage_24h | The number of times each trigger has been used in the past day | usage_7d | The number of times each trigger has been used in the past week | usage_30d | The number of times each trigger has been used in the past thirty days parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - $ref: "#/components/parameters/TriggerActive" - $ref: "#/components/parameters/TriggerSort" - $ref: "#/components/parameters/TriggerSortBy" - $ref: "#/components/parameters/TriggerSortOrder" - $ref: "#/components/parameters/TriggerCategoryId" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TriggersResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateTrigger tags: - Triggers summary: Create Trigger description: | #### Allowed For * Agents requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/TriggerWithCategoryRequest" responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/TriggerResponse" /api/v2/triggers/{trigger_id}: parameters: - $ref: "#/components/parameters/TriggerId" get: operationId: GetTrigger tags: - Triggers summary: Show Ticket Trigger description: | #### Allowed For * Agents The Via Type value is a number instead of a text string. See [Via types reference](/documentation/ticketing/reference-guides/via-types/) for the keys. responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TriggerResponse" put: operationId: UpdateTrigger tags: - Triggers summary: Update Ticket Trigger description: | #### Allowed For * Agents #### Note Updating a condition or action updates both the conditions and actions arrays, clearing all existing values of both arrays. Include all your conditions and actions when updating any condition or action. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/TriggerWithCategoryRequest" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TriggerResponse" delete: operationId: DeleteTrigger tags: - Triggers summary: Delete Ticket Trigger description: | #### Allowed For * Agents responses: "204": description: No Content response /api/v2/triggers/{trigger_id}/revisions: parameters: - $ref: "#/components/parameters/TriggerId" get: operationId: ListTriggerRevisions tags: - Triggers summary: List Ticket Trigger Revisions description: | List the revisions associated with a ticket trigger. Ticket trigger revision history is only available on Enterprise plans. #### Allowed For * Agents #### Sideloads The following sideloads are supported: | Name | Will sideload | ----- | ------------- | users | The user that authored each revision #### Pagination This endpoint uses cursor-based pagination. The records are ordered in descending order by the `created_at` timestamp, then by `id` on duplicate `created_at` values. The `cursor` parameter is a non-human-readable argument you can use to move forward or backward in time. Each JSON response will contain the following attributes to help you get more results: - `after_url` requests more recent results - `before_url` requests older results - `after_cursor` is the cursor to build the request yourself - `before_cursor` is the cursor to build the request yourself The properties are null if no more records are available. You can request a maximum of 1000 records using the `limit` parameter. If no `limit` parameter is supplied, it will default to 1,000. responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TriggerRevisionsResponse" /api/v2/triggers/{trigger_id}/revisions/{trigger_revision_id}: parameters: - $ref: "#/components/parameters/TriggerId" - $ref: "#/components/parameters/TriggerRevisionId" get: operationId: TriggerRevision tags: - Triggers summary: Show Ticket Trigger Revision description: | Fetches a revision associated with a ticket trigger. Ticket trigger revision history is only available on Enterprise plans. #### Allowed For * Agents #### Sideloads The following sideloads are supported: | Name | Will sideload | ----- | ------------- | users | The user that authored each revision responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TriggerRevisionResponse" /api/v2/triggers/active: parameters: - $ref: "#/components/parameters/TriggerSort" - $ref: "#/components/parameters/TriggerSortBy" - $ref: "#/components/parameters/TriggerSortOrder" - $ref: "#/components/parameters/TriggerCategoryId" get: operationId: ListActiveTriggers tags: - Triggers summary: List Active Ticket Triggers description: | Lists all active ticket triggers. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents #### Sideloads The following sideloads are supported: | Name | Will sideload | ---------------- | ------------- | app_installation | The app installation that requires each ticket trigger, if present | permissions | The permissions for each trigger | usage_1h | The number of times each ticket trigger has been used in the past hour | usage_24h | The number of times each ticket trigger has been used in the past day | usage_7d | The number of times each ticket trigger has been used in the past week | usage_30d | The number of times each ticket trigger has been used in the past thirty days responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TriggersResponse" /api/v2/triggers/definitions: get: operationId: ListTriggerActionConditionDefinitions tags: - Triggers summary: List Ticket Trigger Action and Condition Definitions description: | Returns the definitions of the actions a ticket trigger can perform and the definitions of the conditions under which a ticket trigger can execute. The definition of the action includes a title ("Status"), a type ("list"), and possible values. The definition of the condition includes the same fields as well as the possible operators. For a list of supported actions, see the [Actions reference](/documentation/ticketing/reference-guides/actions-reference) For a list of supported conditions, see the [Conditions reference](/documentation/ticketing/reference-guides/conditions-reference) #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TriggerDefinitionResponse" /api/v2/triggers/destroy_many: parameters: - $ref: "#/components/parameters/TriggerIds" delete: operationId: DeleteManyTriggers tags: - Triggers summary: Bulk Delete Ticket Triggers description: | Deletes the ticket triggers corresponding to the provided comma-separated list of IDs. #### Allowed For * Agents #### Request Parameters The DELETE request takes one parameter, an `ids` object that lists the ticket triggers to delete. | Name | Description | ---- | ----------- | ids | The IDs of the triggers to delete #### Example request ```js { "ids": "25,23,27,22" } ``` responses: "204": description: No content response /api/v2/triggers/reorder: put: operationId: ReorderTriggers tags: - Triggers summary: Reorder Ticket Triggers description: | Alters the firing order of ticket triggers in the account. See [Reordering and sorting triggers](https://support.zendesk.com/hc/en-us/articles/115015696088) in the Zendesk Help Center. The firing order is set in a `trigger_ids` array in the request body. You must include every ticket trigger id in your account to reorder the ticket triggers. If not, the endpoint will return 404 Forbidden. Reordering ticket triggers via the API is not permitted if you have more than one ticket trigger category. If there is more than one ticket trigger category, the endpoint will return a `LimitOneCategory` error. #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TriggerResponse" /api/v2/triggers/search: parameters: - $ref: "#/components/parameters/TriggerSearchQuery" - $ref: "#/components/parameters/TriggerSearchFilter" - $ref: "#/components/parameters/TriggerActive" - $ref: "#/components/parameters/TriggerSort" - $ref: "#/components/parameters/TriggerSortBy" - $ref: "#/components/parameters/TriggerSortOrder" - $ref: "#/components/parameters/TriggerInclude" get: operationId: SearchTriggers tags: - Triggers summary: Search Ticket Triggers description: | #### Pagination * Offset pagination only See [Using Offset Pagination](/api-reference/ticketing/introduction/#using-offset-pagination). #### Allowed For * Agents #### Sideloads The following sideloads are supported. For more information, see [Side-loading](/documentation/ticketing/using-the-zendesk-api/side_loading/). | Name | Will sideload | ---------------- | ------------- | app_installation | The app installation that requires each ticket trigger, if present | permissions | The permissions for each ticket trigger | usage_1h | The number of times each ticket trigger has been used in the past hour | usage_24h | The number of times each ticket trigger has been used in the past day | usage_7d | The number of times each ticket trigger has been used in the past week | usage_30d | The number of times each ticket trigger has been used in the past thirty days #### Filter Use the `filter` query parameter to filter a ticket trigger search by one or more attributes. For example, the following `filter` argument filters ticket triggers by the `description` attribute: ```json { "json": { "description": "Close a ticket" } } ``` responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TriggersResponse" /api/v2/triggers/update_many: put: operationId: UpdateManyTriggers tags: - Triggers summary: Update Many Ticket Triggers description: | Updates the position or the active status of multiple ticket triggers. Any additional properties are ignored. #### Allowed For * Agents #### Request Parameters The PUT request expects a `triggers` object that lists the ticket triggers to update. Each ticket trigger may have the following properties: | Name | Mandatory | Description | -------- | --------- | ----------- | id | yes | The ID of the ticket trigger to update | position | no | The new position of the ticket trigger | active | no | The active status of the ticket trigger (true or false) | category_id | no | The ID of the new category the ticket trigger is to be moved to #### Example Request ```js { "triggers": [ {"id": 25, "position": 3}, {"id": 23, "position": 5}, {"id": 27, "position": 9}, {"id": 22, "position": 7} ] } ``` requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/TriggerBulkUpdateRequest" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TriggersResponse" /api/v2/uploads: post: operationId: UploadFiles tags: - Attachments summary: Upload Files description: | Uploads a file that can be attached to a ticket comment. It doesn't attach the file to the comment. For details and examples, see [Attaching ticket comments with the API](/documentation/ticketing/using-the-zendesk-api/adding-ticket-attachments-with-the-api). The endpoint has a required `filename` query parameter. The parameter specifies what the file will be named when attached to the ticket comment (to give the agent more context about the file). The parameter does not specify the file on the local system to be uploaded. While the two names can be different, their file extensions must be the same. If they don't match, the agent's browser or file reader could give an error when attempting to open the attachment. The `Content-Type` header must contain a recognized MIME type that correctly describes the type of the uploaded file. Failing to send a recognized, correct type may cause undesired behavior. For example, in-browser audio playback may be interrupted by the browser's security mechanisms for MP3s uploaded with an incorrect type. Adding multiple files to the same upload is handled by splitting requests and passing the API token received from the first request to each subsequent request. The token is valid for 60 minutes. **Note**: Even if [private attachments](https://support.zendesk.com/hc/en-us/articles/204265396) are enabled in the Zendesk Support instance, uploaded files are visible to any authenticated user at the `content_URL` specified in the [JSON response](#json-format) until the upload token is consumed. Once a file is associated with a ticket or post, visibility is restricted to users with access to the ticket or post with the attachment. #### Allowed For * End users responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/AttachmentUploadResponse" /api/v2/uploads/{token}: delete: operationId: DeleteUpload tags: - Attachments summary: Delete Upload description: | #### Allowed for * End Users parameters: - name: token in: path description: The token of the uploaded attachment required: true schema: type: string responses: "204": description: No Content response /api/v2/user_fields: get: operationId: ListUserFields tags: - User Fields summary: List User Fields description: | Returns a list of custom user fields in your account. Fields are returned in the order that you specify in your user fields configuration in Zendesk Support. Clients should cache this resource for the duration of their API usage and map the key for each User Field to the values returned under the `user_fields` attribute on the [User](/api-reference/ticketing/users/users/) resource. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/UserFieldsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateUserField tags: - User Fields summary: Create User Field description: | Creates any of the following custom field types: * text (default when no "type" is specified) * textarea * checkbox * date * integer * decimal * regexp * dropdown * lookup * multiselect See [About custom field types](https://support.zendesk.com/hc/en-us/articles/203661866) in Zendesk help. #### Allowed For * Admins responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/UserFieldResponse" /api/v2/user_fields/{user_field_id}: parameters: - $ref: "#/components/parameters/UserFieldId" get: operationId: ShowUserField tags: - User Fields summary: Show User Field description: | #### Allowed for * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/UserFieldResponse" put: operationId: UpdateUserField tags: - User Fields summary: Update User Field description: | #### Updating a Dropdown (Tagger) or Multiselect Field Dropdown and multiselect fields return an array of `custom_field_options` which specify the name, value, and order of the list of dropdown or multiselect options. Understand the following behavior when updating a dropdown or multiselect field: - All options must be passed on update. Options that are not passed will be removed. As a result, these values will be removed from any organizations. - To create a new option, pass a null `id` along with `name` and `value`. - To update an existing option, pass its `id` along with `name` and `value`. - To re-order an option, reposition it in the `custom_field_options` array relative to the other options. - To remove an option, omit it from the list of options upon update. #### Example Request ```bash curl https://{subdomain}.zendesk.com/api/v2/user_fields/{user_field_id}.json \ -H "Content-Type: application/json" -X PUT \ -d '{"user_field": {"custom_field_options": [{"id": 124, "name": "Option 2", "value": "option_2"}, {"id": 123, "name": "Option 1", "value": "option_1"}, {"id": 125, "name": "Option 2", "value": "option_3"}]}}' \ -v -u {email_address}/token:{api_token} ``` #### Allowed for * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/UserFieldResponse" delete: operationId: DeleteUserField tags: - User Fields summary: Delete User Field description: | #### Allowed for * Admins responses: "204": description: No Content response /api/v2/user_fields/{user_field_id}/options: parameters: - $ref: "#/components/parameters/UserFieldId" get: operationId: ListUserFieldOptions tags: - User Fields summary: List User Field Options description: | Returns a list of custom user field options for the given dropdown user field. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CustomFieldOptionsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateOrUpdateUserFieldOption tags: - User Fields summary: Create or Update a User Field Option description: | Creates a new option or updates an existing option for the given drop-down user field. To update an option, include the id of the option in the `custom_field_option` object. Example: `{"custom_field_option": {"id": 10002, "name": "Pineapples", ... }`. If an option exists for the given ID, the option will be updated. Otherwise, a new option will be created. #### Response Returns one of the following status codes: - 200 with `Location: /api/v2/user_fields/{user_field_id}/options.json` if the user field option already exists in the database - 201 with `Location: /api/v2/user_fields/{user_field_id}/options.json` if the user field option is new #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CustomFieldOptionResponse" "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/CustomFieldOptionResponse" /api/v2/user_fields/{user_field_id}/options/{user_field_option_id}: parameters: - $ref: "#/components/parameters/UserFieldId" - $ref: "#/components/parameters/UserFieldOptionId" get: operationId: ShowUserFieldOption tags: - User Fields summary: Show a User Field Option description: | #### Allowed for * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CustomFieldOptionResponse" delete: operationId: DeleteUserFieldOption tags: - User Fields summary: Delete User Field Option description: | #### Allowed for * Admins responses: "204": description: No Content response /api/v2/user_fields/reorder: put: operationId: ReorderUserField tags: - User Fields summary: Reorder User Field description: | #### Allowed For * Admins responses: "200": description: Success response content: application/json: schema: type: string description: Empty response /api/v2/users: get: operationId: ListUsers tags: - Users summary: List Users description: | #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Admins, Agents and Light Agents parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - $ref: "#/components/parameters/UserRoleFilter" - $ref: "#/components/parameters/UserRolesFilter" - $ref: "#/components/parameters/UserPermissionSetFilter" - $ref: "#/components/parameters/UserExternalIdFilter" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/UsersResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateUser tags: - Users summary: Create User requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UserRequest" responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/UserResponse" /api/v2/users/{user_id}: parameters: - $ref: "#/components/parameters/UserId" get: operationId: ShowUser tags: - Users summary: Show User description: | #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/UserResponse" put: operationId: UpdateUser tags: - Users summary: Update User requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UserRequest" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/UserResponse" delete: operationId: DeleteUser tags: - Users summary: Delete User description: | Deletes the user and associated records from the account. **Warning**: * Deleted users are not recoverable. * Both agents and administrators can soft delete users in the agent interface in Zendesk Support. Agents with permission can delete end users, while administrators can delete all users except the account owner. To comply with GDPR, a further step is needed. See [Permanently Delete User](/api-reference/ticketing/users/users/#permanently-delete-user). #### Allowed For * Admins and [agents in custom roles with permission](https://support.zendesk.com/hc/en-us/articles/4408882153882#topic_cxn_hig_bd) to manage end users or team members responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/UserResponse" /api/v2/users/{user_id}/compliance_deletion_statuses: parameters: - $ref: "#/components/parameters/UserId" get: operationId: ShowUserComplianceDeletionStatuses tags: - Users summary: Show Compliance Deletion Statuses description: | Returns the GDPR status for each user per area of compliance. A Zendesk area of compliance is typically a product like "support/explore" but can be more fine-grained for areas within the product lines. If the user is not in the account, the request returns a 404 status. ```http Status: 404 { "error":"RecordNotFound", "description":"Not found" } ``` #### Allowed For * Agents, with restrictions #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - name: application in: query description: Area of compliance schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ComplianceDeletionStatusesResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/users/{user_id}/group_memberships/{group_membership_id}/make_default: parameters: - $ref: "#/components/parameters/UserId" - $ref: "#/components/parameters/GroupMembershipId" put: operationId: GroupMembershipSetDefault tags: - Group Memberships summary: Set Membership as Default description: | #### Allowed For: * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/GroupMembershipsResponse" /api/v2/users/{user_id}/identities: parameters: - $ref: "#/components/parameters/UserId" - name: type[] in: query description: Filters results by one or more identity types using the format `?type[]={type}&type[]={type}` explode: true schema: type: string enum: - email - facebook - phone_number - sdk - twitter - messaging - microsoft get: operationId: ListUserIdentities tags: - User Identities summary: List Identities description: | Returns a list of identities for the given user. Use the first endpoint if authenticating as an agent. Use the second if authenticating as an end user. End users can only list email and phone number identities. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page for cursor pagination. #### Allowed For * Agents * Verified end users parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/UserIdentitiesResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateUserIdentity tags: - User Identities summary: Create Identity description: | Adds an identity to a user's profile. An agent can add an identity to any user profile. Supported identity types: | Type | Example | | ---------------- | ------- | | email | `{ "type" : "email", "value" : "someone@example.com" }` | | twitter | `{ "type" : "twitter", "value" : "screen_name" }` | | facebook | `{ "type" : "facebook", "value" : "855769377321" }` | | google | `{ "type" : "google", "value" : "example@gmail.com" }` | | agent_forwarding | `{ "type" : "agent_forwarding", "value" : "+1 555-123-4567" }` | | phone_number | `{ "type" : "phone_number", "value" : "+1 555-123-4567" }` | To create an identity without sending out a verification email, include a `"skip_verify_email": true` property. The `"skip_verify_email": true` property does not apply when updating your own agent profile. A welcome or verification email will be sent regardless of this setting. #### Allowed For * Agents responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/UserIdentityResponse" /api/v2/users/{user_id}/identities/{user_identity_id}: parameters: - $ref: "#/components/parameters/UserId" - $ref: "#/components/parameters/UserIdentityId" get: operationId: ShowUserIdentity tags: - User Identities summary: Show Identity description: | Shows the identity with the given id for a given user. Use the first endpoint if authenticating as an agent. Use the second if authenticating as an end user. End users can only view email or phone number identity. #### Allowed For * Agents * Verified end users responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/UserIdentityResponse" put: operationId: UpdateUserIdentity tags: - User Identities summary: Update Identity description: | This endpoint allows you to: * Set the specified identity as verified (by setting `verified` to "true" or `verification_method` to "low") * Unverify a verified identity (by setting `verified` to "false" or `verification_method` to "none") * Update the `value` property of the specified identity You can't change an identity's `primary` attribute with this endpoint. You must use the [Make Identity Primary](#make-identity-primary) endpoint instead. #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/UserIdentityResponse" delete: operationId: DeleteUserIdentity tags: - User Identities summary: Delete Identity description: | Deletes the identity for a given user. In certain cases, a phone number associated with an identity is still visible on the user profile after the identity has been deleted via API. You can remove the phone number from the user profile by updating the `phone` attribute of the user to an empty string. See [Update User via API](/api-reference/ticketing/users/users/#update-user) for details and examples. Deleting identities with type `messaging` could break messaging functionality. For example, an agent may stop being able to send messages via the messaging channel. #### Allowed For * Agents responses: "204": description: No Content response /api/v2/users/{user_id}/identities/{user_identity_id}/make_primary: parameters: - $ref: "#/components/parameters/UserId" - $ref: "#/components/parameters/UserIdentityId" put: operationId: MakeUserIdentityPrimary tags: - User Identities summary: Make Identity Primary description: | Sets the specified identity as primary. To change other attributes, use the [Update Identity](#update-identity) endpoint. This is a collection-level operation and the correct behavior for an API client is to subsequently reload the entire collection. The first endpoint is the preferred option if authenticating as an agent. If authenticating as an end user, you can only use the second endpoint. In addition, an end user can only make an email identity primary if the email is verified. #### Allowed For * Agents * Verified end users responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/UserIdentitiesResponse" /api/v2/users/{user_id}/identities/{user_identity_id}/request_verification: parameters: - $ref: "#/components/parameters/UserId" - $ref: "#/components/parameters/UserIdentityId" put: operationId: RequestUserVerfication tags: - User Identities summary: Request User Verification description: | Sends the user a verification email with a link to verify ownership of the email address. #### Allowed For * Agents responses: "200": description: Success description content: application/json: schema: type: string description: Empty response /api/v2/users/{user_id}/identities/{user_identity_id}/verify: parameters: - $ref: "#/components/parameters/UserId" - $ref: "#/components/parameters/UserIdentityId" put: operationId: VerifyUserIdentity tags: - User Identities summary: Verify Identity description: | Sets the specified identity as verified. For security reasons, you can't use this endpoint to update the email identity of the account owner. To verify the person's identity, send a verification email. See [Verifying the account owner's email address](https://support.zendesk.com/hc/en-us/articles/4408828975130) in Zendesk help. If [automatic mapping of users to organizations using the email domain](https://support.zendesk.com/hc/en-us/articles/4408882246298-Creating-organizations#topic_nxl_vdt_bc) is enabled and the user is not already a member of an organization, they will be automatically added to the organization associated with the email domain once the email identity is verified. #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/UserIdentityResponse" /api/v2/users/{user_id}/merge: parameters: - $ref: "#/components/parameters/UserId" put: operationId: MergeEndUsers tags: - Users summary: Merge End Users description: | Merges the end user specified in the path parameter into the existing end user specified in the request body. Any two end users can be merged with the exception of end users created by sharing agreements. To be eligible for merging, the user in the path parameter must be a requester on 10,000 or fewer tickets. Otherwise, the merge will be blocked. Agents, admins, and users with more than 10,000 requested tickets cannot be merged. For more information about how user data is merged, see [Merging a user's duplicate account](https://support.zendesk.com/hc/en-us/articles/4408887695898) in Zendesk help. #### Allowed For * Admins or agents with permission to edit end users requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UserRequest" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/UserResponse" /api/v2/users/{user_id}/organization_memberships/{organization_membership_id}/make_default: parameters: - $ref: "#/components/parameters/UserId" - $ref: "#/components/parameters/OrganizationMembershipId" put: operationId: SetOrganizationMembershipAsDefault tags: - Organization Memberships summary: Set Membership as Default description: | Sets the default organization membership of a given user. #### Allowed for * Admins * Agents when setting the default organization membership for an end user responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/OrganizationMembershipsResponse" /api/v2/users/{user_id}/organizations/{organization_id}: parameters: - $ref: "#/components/parameters/OrganizationId" - $ref: "#/components/parameters/UserId" delete: operationId: UnassignOrganization tags: - Organization Memberships summary: Unassign Organization description: | Immediately removes a user from an organization and schedules a job to unassign all working tickets currently assigned to the user and organization combination. The `organization_id` of the unassigned tickets is set to null. #### Allowed For * Agents responses: "204": description: No Content response /api/v2/users/{user_id}/organizations/{organization_id}/make_default: parameters: - $ref: "#/components/parameters/UserId" - $ref: "#/components/parameters/OrganizationId" put: operationId: SetOrganizationAsDefault tags: - Organization Memberships summary: Set Organization as Default description: | Sets the default organization membership of a given user. #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/OrganizationMembershipResponse" /api/v2/users/{user_id}/password: parameters: - $ref: "#/components/parameters/UserId" post: operationId: SetUserPassword tags: - User Passwords summary: Set a User's Password description: | An admin can set a user's password only if the setting is enabled in Zendesk Support under **Settings** > **Security** > **Global**. The setting is off by default. Only the account owner can access and change this setting. #### Allowed For * Admins responses: "200": description: Success description content: application/json: schema: type: string description: Empty response put: operationId: ChangeOwnPassword tags: - User Passwords summary: Change Your Password description: | You can only change your own password. Nobody can change the password of another user because it requires knowing the user's existing password. However, an admin can set a new password for another user without knowing the existing password. See [Set a User's Password](#set-a-users-password) above. #### Allowed For * Agents * End Users responses: "200": description: Success description content: application/json: schema: type: string description: Empty response /api/v2/users/{user_id}/password/requirements: parameters: - $ref: "#/components/parameters/UserId" get: operationId: GetUserPasswordRequirements tags: - User Passwords summary: List password requirements description: | #### Allowed For * Agents * End Users responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/UserPasswordRequirementsResponse" /api/v2/users/{user_id}/related: parameters: - $ref: "#/components/parameters/UserId" get: operationId: ShowUserRelated tags: - Users summary: Show User Related Information responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/UserRelatedResponse" /api/v2/users/{user_id}/sessions: parameters: - $ref: "#/components/parameters/UserId" delete: operationId: BulkDeleteSessionsByUserId tags: - Sessions summary: Bulk Delete Sessions description: | Deletes all the sessions for a user. #### Allowed For * Admins, Agents, End users responses: "204": description: No Content /api/v2/users/{user_id}/sessions/{session_id}: parameters: - $ref: "#/components/parameters/SessionId" - $ref: "#/components/parameters/UserId" get: operationId: ShowSession tags: - Sessions summary: Show Session description: | #### Allowed For * Admins, Agents, End users responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SessionResponse" delete: operationId: DeleteSession tags: - Sessions summary: Delete Session description: | #### Allowed For * Admins, Agents, End users responses: "204": description: No Content /api/v2/users/{user_id}/skips: parameters: - $ref: "#/components/parameters/SkipTicketUserId" - $ref: "#/components/parameters/TicketSortOrder" get: operationId: ListTicketSkips tags: - Ticket Skips summary: List Ticket Skips description: | Archived tickets are not included in the response. See [About archived tickets](https://support.zendesk.com/hc/en-us/articles/203657756) in the Support Help Center. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents with "View only" or higher reports permissions in Support. These permissions are distinct from Explore permissions. * Agents retrieving their own skips parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketSkipsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/users/autocomplete: get: operationId: AutocompleteUsers tags: - Users summary: Autocomplete Users description: | Returns an array of users whose name starts with the value specified in the `name` parameter. It only returns users with no foreign identities. #### Allowed For * Agents parameters: - name: name in: query description: "The name to search for the user. " required: true schema: type: string - $ref: "#/components/parameters/LookupRelationshipAutocompleteFieldIdFragment" - $ref: "#/components/parameters/LookupRelationshipAutocompleteSourceFragment" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/UsersResponse" /api/v2/users/count: get: operationId: CountUsers tags: - Users summary: Count Users description: | Returns an approximate count of users. If the count exceeds 100,000, it is updated every 24 hours. The response includes a `refreshed_at` property in a `count` object that contains a timestamp indicating when the count was last updated. **Note**: When the count exceeds 100,000, the `refreshed_at` property may occasionally be null. This indicates that the count is being updated in the background. The `count` object's `value` property is limited to 100,000 until the update is complete. #### Allowed For * Admins, Agents and Light Agents parameters: - $ref: "#/components/parameters/UserRoleFilter" - $ref: "#/components/parameters/UserRolesFilter" - $ref: "#/components/parameters/UserPermissionSetFilter" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CountResponse" /api/v2/users/create_many: post: operationId: CreateManyUsers tags: - Users summary: Create Many Users description: | Accepts an array of up to 100 user objects. **Note**: To protect the data in your Zendesk account, bulk user imports are not enabled by default in Zendesk accounts. The account owner must contact [Zendesk Customer Support](https://support.zendesk.com/hc/en-us/articles/4408843597850) to enable the imports. A 403 Forbidden error is returned if data imports are not enabled. #### Allowed For * Admins and [agents in custom roles with permission](https://support.zendesk.com/hc/en-us/articles/4408882153882#topic_cxn_hig_bd) to manage end users or team members #### Specifying an organization You can assign a user to an existing organization by setting an `organization_id` property in the user object. #### Response This endpoint returns a `job_status` [JSON object](/api-reference/ticketing/ticket-management/job_statuses/#json-format) and queues a background job to do the work. Use the [Show Job Status](/api-reference/ticketing/ticket-management/job_statuses/#show-job-status) endpoint to check for the job's completion. Only a certain number of jobs can be queued or running at the same time. See [Job limit](/api-reference/introduction/rate-limits/#job-limit) for more information. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UsersRequest" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" /api/v2/users/create_or_update: post: operationId: CreateOrUpdateUser tags: - Users summary: Create Or Update User description: | Creates a user if the user does not already exist, or updates an existing user identified by e-mail address or external ID. If you don't specify a role parameter, the new user is assigned the role of end user. If you need to create users without sending out a verification email, include a `"skip_verify_email": true` property in the body. #### External ID Case Sensitivity When providing an external id to identify an existing user to update, the search for the user record is not case sensitive. However, if an existing user is found, the system will update the user's external id to match the case of the external id used to find the user. #### Response Status Code - If the user exists in Zendesk, a successful request returns a 200 status code with "Location: /api/v2/users/{user_id}.json". - If the user does not exist in Zendesk, a successful request returns a 201 status code with "Location: /api/v2/users/{new_user_id}.json". #### Allowed For * Admins and [agents in custom roles with permission](https://support.zendesk.com/hc/en-us/articles/4408882153882#topic_cxn_hig_bd) to manage end users or team members requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UserRequest" responses: "200": description: Successful response, when user exits content: application/json: schema: $ref: "#/components/schemas/UserResponse" "201": description: Created response, when user is new content: application/json: schema: $ref: "#/components/schemas/UserResponse" /api/v2/users/create_or_update_many: post: operationId: CreateOrUpdateManyUsers tags: - Users summary: Create Or Update Many Users description: "Accepts an array of up to 100 user objects. For each user, the\ \ user is created if it does not\nalready exist, or the existing user is updated.\n\ \n**Note**: To protect the data in your Zendesk account, bulk user imports\ \ are not enabled by default in Zendesk accounts. The account owner must contact\ \ [Zendesk Customer Support](https://support.zendesk.com/hc/en-us/articles/4408843597850)\ \ to enable the imports. A 403 Forbidden\nerror is returned if data imports\ \ are not enabled. \n\nEach individual user object can identify an existing\ \ user by `email` or by `external_id`.\n\nThis endpoint returns a `job_status`\ \ [JSON object](/api-reference/ticketing/ticket-management/job_statuses/#json-format)\ \ and queues a background job to do the work. Use the [Show Job Status](/api-reference/ticketing/ticket-management/job_statuses/#show-job-status)\ \ endpoint to check for the job's completion. Only a certain number of jobs\ \ can be queued or running at the same time. See [Job limit](/api-reference/introduction/rate-limits/#job-limit)\ \ for more information.\n\n#### Allowed For\n\n* Admins and [agents in custom\ \ roles with permission](https://support.zendesk.com/hc/en-us/articles/4408882153882#topic_cxn_hig_bd)\ \ to manage end users or team members\n" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UsersRequest" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" /api/v2/users/destroy_many: delete: operationId: DestroyManyUsers tags: - Users summary: Bulk Delete Users description: | Accepts a comma-separated list of up to 100 user ids. The request takes an `ids` or an `external_ids` query parameter. #### Allowed for - Admins #### Response This endpoint returns a `job_status` [JSON object](/api-reference/ticketing/ticket-management/job_statuses/#json-format) and queues a background job to do the work. Use the [Show Job Status](/api-reference/ticketing/ticket-management/job_statuses/#show-job-status) endpoint to check for the job's completion. Only a certain number of jobs can be queued or running at the same time. See [Job limit](/api-reference/introduction/rate-limits/#job-limit) for more information. parameters: - name: ids in: query description: Id of the users to delete. Comma separated schema: type: string - name: external_ids in: query description: External Id of the users to delete. Comma separated schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" /api/v2/users/logout_many: post: operationId: LogoutManyUsers tags: - Users summary: Logout many users description: | Accepts a comma-separated list of up to 100 user ids. #### Allowed For: * Admins parameters: - name: ids in: query description: "Accepts a comma-separated list of up to 100 user ids. " schema: type: string responses: "202": description: Accepted response content: application/json: schema: type: string description: Empty response /api/v2/users/me: get: operationId: ShowCurrentUser tags: - Users summary: Show Self description: "The endpoint returns [user information](/api-reference/ticketing/users/users/)\ \ and an `authenticity_token`. \n\n#### Allowed For\n\n* Anonymous users\n\ \n#### Authenticity Token\n\nZendesk API calls made by end users from a Zendesk\ \ help center must include `authenticity_token` in the `X-CSRF-Token` HTTP\ \ header. This helps prevent [cross-site request forgery (CSRF)](https://en.wikipedia.org/wiki/Cross-site_request_forgery)\ \ attacks.\n\nFor an example using an authenticity token, see the AJAX request\ \ in the [Upgrading from Templating API v1](https://developer.zendesk.com/documentation/help_center/help-center-templates/v1#jquery)\ \ documentation.\n" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/CurrentUserResponse" /api/v2/users/me/logout: delete: operationId: DeleteAuthenticatedSession tags: - Sessions summary: Delete the Authenticated Session description: | Deletes the current session. In practice, this only works when using session auth for requests, such as client-side requests made from a Zendesk app. When using OAuth or basic authentication, you don't have a current session so this endpoint has no effect. #### Allowed For * Admins, Agents, End users responses: "204": description: No Content /api/v2/users/me/session: get: operationId: ShowCurrentlyAuthenticatedSession tags: - Sessions summary: Show the Currently Authenticated Session description: | #### Allowed For * Admins, Agents, End users responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/SessionResponse" /api/v2/users/me/session/renew: get: operationId: RenewCurrentSession tags: - Sessions summary: Renew the current session description: | #### Allowed For * Admins, Agents, End users responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/RenewSessionResponse" /api/v2/users/request_create: post: operationId: RequestUserCreate tags: - Users summary: Request User Create description: | Sends the owner a reminder email to update their subscription so more agents can be created. #### Allowed For * Agents requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UserRequest" responses: "200": description: description content: application/json: schema: type: string description: Empty response /api/v2/users/search: get: operationId: SearchUsers tags: - Users summary: Search Users description: | Returns an array of users who meet the search criteria. Returns up to 100 records per page to a maximum of 10,000 records per query. See [Using offset pagination](/api-reference/introduction/pagination/#using-offset-pagination). #### Pagination * Offset pagination only See [Using Offset Pagination](/api-reference/ticketing/introduction/#using-offset-pagination). #### Allowed For * Agents parameters: - name: query in: query description: | The `query` parameter supports the Zendesk search syntax for more advanced user searches. It can specify a partial or full value of any user property, including name, email address, notes, or phone. Example: `query="jdoe"`. See the [Search API](/api-reference/ticketing/ticket-management/search/). schema: type: string - name: external_id in: query description: "The `external_id` parameter does not support the search syntax. It only accepts ids. " schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/UsersResponse" /api/v2/users/show_many: get: operationId: ShowManyUsers tags: - Users summary: Show Many Users description: | Accepts a comma-separated list of up to 100 user ids or external ids. #### Allowed For: * Agents parameters: - name: ids in: query description: "Accepts a comma-separated list of up to 100 user ids. " schema: type: string - name: external_ids in: query description: "Accepts a comma-separated list of up to 100 external ids. " schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/UsersResponse" /api/v2/users/update_many: put: operationId: UpdateManyUsers tags: - Users summary: Update Many Users parameters: - name: ids in: query description: Id of the users to update. Comma separated schema: type: string - name: external_ids in: query description: External Id of the users to update. Comma separated schema: type: string requestBody: required: true content: application/json: schema: oneOf: - $ref: "#/components/schemas/UserRequest" - $ref: "#/components/schemas/UsersRequest" additionalProperties: true responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/JobStatusResponse" /api/v2/views: get: operationId: ListViews tags: - Views summary: List Views description: | Lists shared and personal views available to the current user. #### Sideloads The following sideloads are supported: | Name | Will sideload | ---------------- | ------------- | app_installation | The app installation that requires each view, if present | permissions | The permissions for each view #### Pagination - Cursor pagination (recommended, but only sorts by `created_at`) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - name: access in: query description: Only views with given access. May be "personal", "shared", or "account" schema: type: string - name: active in: query description: Only active views if true, inactive views if false schema: type: boolean - name: group_id in: query description: Only views belonging to given group schema: type: integer - name: sort_by in: query description: Possible values are "alphabetical", "created_at", or "updated_at". Defaults to "position" schema: type: string - name: sort_order in: query description: One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ViewsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: operationId: CreateView tags: - Views summary: Create View description: | #### Allowed For * Agents #### JSON Format The JSON format consists of one property, a `view` object that lists the values to set when the view is created. **Note**: The request must include at least one condition in the `all` array that checks one of the following fields: `status`, `type`, `group_id`, `assignee_id`, or `requester_id`. | Name | Description | ----------- | ----------- | title | Required. The title of the view | all | Required. An array of one or more conditions. A ticket must meet all of them to be included in the view. See [Conditions reference](/documentation/ticketing/reference-guides/conditions-reference) | any | An array of one or more conditions. A ticket must meet any of them to be included in the view. See [Conditions reference](/documentation/ticketing/reference-guides/conditions-reference) | description | The description of the view | active | Allowed values are true or false. Determines if the view is displayed or not | output | An object that specifies the columns to display. Example: `"output": {"columns": ["status", "description", "priority"]}`. See [View columns](#view-columns) | restriction | An object that describes who can access the view. To give all agents access to the view, omit this property The `restriction` object has the following properties. | Name | Comment | ---- | ------- | type | Allowed values are "Group" or "User" | id | The numeric ID of a single group or user | ids | The numeric IDs of a single or more groups. Recommended for "Group" `type` If `type` is "Group", the `ids` property is the preferred method of specifying the group id or ids. #### Example Request Body ```js { "view": { "title": "Kelly's tickets", "raw_title": "{{dc.tickets_assigned_to_kelly}}", "description": "Tickets that are assigned to Kelly", "active": true, "position": 3, "restriction": { "type": "User", "id": "213977756" }, "all": [ { "field": "status", "operator": "less_than", "value": "solved" }, { "field": "group_id", "operator": "is", "value": "24000932" }, { "field": "custom_fields_360011872073", "operator": "is", "value": "Canada" }, ... ], "output": { "columns": ["status", "requester", "assignee"], "group_by": "assignee", "group_order": "desc", "sort_by": "status", "sort_order": "desc" } } } ``` #### View columns The `output` request parameter lets you specify what columns to include in the view in the agent interface. Example: `"output": {"columns": ["status", "description", "priority"]}`. The following table lists possible columns for views in the agent UI and the corresponding values in the `columns` array. For custom fields, specify the id of the custom field in the `columns` array. You can specify a total of 10 columns to a view. | View column title in UI | Value | |---------------------------- | -------------------- | | Assigned | `assigned` | | Assignee | `assignee` | | Due Date | `due_date` | | Group | `group` | | ID | `nice_id` | | Updated | `updated` | | Assignee updated | `updated_assignee` | | Requester updated | `updated_requester` | | Updater | `updated_by_type` | | Organization | `organization` | | Priority | `priority` | | Requested | `created` | | Requester | `requester` | | Requester language | `locale_id` | | Satisfaction | `satisfaction_score` | | Solved | `solved` | | Status category | `status` | | Subject | `description` | | Submitter | `submitter` | | Ticket form | `ticket_form` | | Type | `type` | | Brand | `brand` | | Ticket status | `custom_status_id` | #### View sorting You can group and sort items in the view by adding items to the `output` parameter: | Attribute | Description |-----------------------------| ----------- | `group_by`, `sort_by` | Sort or group the tickets by a column in the [View columns](#view-columns) table. The `description`, `submitter` and `custom_status_id` columns are not supported | `group_order`, `sort_order` | Either "asc" or "desc" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ViewResponse" /api/v2/views/{view_id}: parameters: - $ref: "#/components/parameters/ViewId" get: operationId: ShowView tags: - Views summary: Show View description: | #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ViewResponse" put: operationId: UpdateView tags: - Views summary: Update View description: | #### Allowed For * Agents #### JSON Format The PUT request takes one property, a `view` object that lists the values to update. All properties are optional. **Note**: Updating a condition updates the containing array, clearing the other conditions. Include all your conditions when updating any condition. | Name | Description | ----------- | ----------- | title | The title of the view | all | An array of one or more conditions. A ticket must meet all the conditions to be included in the view. The PUT request replaces all existing conditions. See [Conditions reference](/documentation/ticketing/reference-guides/conditions-reference) | any | An array of one or more conditions. A ticket must meet any of them to be included in the view. At least one `all` condition must be defined with the `any` conditions. The PUT request replaces all existing `any` conditions. See [Conditions reference](/documentation/ticketing/reference-guides/conditions-reference) | active | Allowed values are true or false. Determines if the view is displayed or not | output | An object that specifies the columns to display. Example: `"output": {"columns": ["status", "description," "priority"]}`. See [View columns](#view-columns) | restriction | An object that describes who can access the view. To give all agents access to the view, omit this property The `restriction` object has the following properties. | Name | Comment | ---- | ------- | type | Allowed values are "Group" or "User" | id | The numeric ID of a single group or user | ids | The numeric IDs of a single or more groups. Recommended for "Group" `type` If `type` is "Group", the `ids` property is the preferred method of specifying the group id or ids. You can also update how items are sorted and grouped. See [View sorting](#view-sorting) in Create View. #### Example Request Body ```js { "view": { "title": "Code red tickets", "restriction": { "type": "Group", "ids": [10052, 10057, 10062, 10002] }, "all": [ { "field": "priority", "operator": "is", "value": "urgent" } ], "output": { "columns": ["status", "requester", "assignee", "updated"] } } } ``` responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ViewResponse" delete: operationId: DeleteView tags: - Views summary: Delete View description: | #### Allowed For * Agents responses: "204": description: No Content response /api/v2/views/{view_id}/count: parameters: - $ref: "#/components/parameters/ViewId" get: operationId: GetViewCount tags: - Views summary: Count Tickets in View description: | Returns the ticket count for a single view. This endpoint is rate limited to 5 requests per minute, per view, per agent. #### View Counts The view count endpoints, Count Tickets in View (this endpoint) and [Count Tickets in Views](#count-tickets-in-views), let you estimate how many tickets remain in a view without having to retrieve the entire view. They're designed to help estimate view size. From a business perspective, accuracy becomes less relevant as view size increases. To ensure quality of service, these counts are cached more heavily as the number of tickets in a view grows. For a view with thousands of tickets, you can expect the count to be cached for 60-90 minutes. As a result, the count may not reflect the actual number of tickets in your view. View counts are represented as JSON objects with the following attributes: | Name | Type | Comment | --------------- | ------------| ------- | view_id | integer | The id of the view | url | string | The API url of the count | value | integer | The cached number of tickets in the view. Can also be null if the system is loading and caching new data. Not to be confused with 0 tickets | pretty | string | A pretty-printed text approximation of the view count | fresh | boolean | false if the cached data is stale and the system is still loading and caching new data | active | boolean | Only active views if true, inactive views if false, all views if null. #### Example ```js { "view_count": { "view_id": 25, "url": "https://company.zendesk.com/api/v2/views/25/count.json", "value": 719, "pretty": "~700", "fresh": true } } ``` responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ViewCountResponse" /api/v2/views/{view_id}/execute: parameters: - $ref: "#/components/parameters/ViewId" get: operationId: ExecuteView tags: - Views summary: Execute View description: | Returns the column titles and the rows of the specified view. The `columns` array lists the view's column titles and includes only views parameters. The `rows` array lists the values of each column for each ticket and includes parameters from both views and tickets. Though not displayed in the view, a partial ticket object is included with each row object. **Note**: To get the full ticket objects for a specified view, use [List Tickets from a View](#list-tickets-from-a-view). This endpoint is rate limited to 5 requests per minute, per view, per agent. This rate limit includes activity in Zendesk Support. An API script is more likely to encounter rate limit errors if the authenticating agent or admin is concurrently active in Zendesk Support. The view execution system is designed for periodic rather than high-frequency API usage. In particular, views called very frequently may be cached by Zendesk. This means that the API client will still receive a result, but that result may have been computed at any time within the last 10 minutes. Zendesk recommends using the Incremental Ticket Export endpoint to get the latest changes. You can call it more often, and it returns all the tickets that changed since the last poll. For details and rate limits, see [Incremental Exports](/api-reference/ticketing/ticket-management/incremental_exports/). View output sorting can be controlled by passing the `sort_by` and `sort_order` parameters in the format described in the table in [Preview Views](#preview-views). #### Allowed For * Agents #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - name: sort_by in: query description: The ticket field used for sorting. This will either be a title or a custom field id. schema: type: string - name: sort_order in: query description: The direction the tickets are sorted. May be one of 'asc' or 'desc' schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ViewResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/views/{view_id}/export: parameters: - $ref: "#/components/parameters/ViewId" get: operationId: ExportView tags: - Views summary: Export View description: | Returns the csv attachment of the specified view if possible. Enqueues a job to produce the csv if necessary. #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ViewExportResponse" /api/v2/views/{view_id}/tickets: parameters: - $ref: "#/components/parameters/ViewId" get: operationId: ListTicketsFromView tags: - Views summary: List Tickets From a View description: | #### Allowed For * Agents #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](/api-reference/introduction/pagination/). parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - name: sort_by in: query description: Sort or group the tickets by a column in the [View columns](#view-columns) table. The `subject` and `submitter` columns are not supported schema: type: string - name: sort_order in: query description: One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TicketsResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/views/active: get: operationId: ListActiveViews tags: - Views summary: List Active Views description: | Lists active shared and personal views available to the current user. #### Sideloads The following sideloads are supported: | Name | Will sideload | ---------------- | ------------- | app_installation | The app installation that requires each view, if present | permissions | The permissions for each view #### Pagination - Offset pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 100 records per page. #### Allowed For * Agents parameters: - name: access in: query description: Only views with given access. May be "personal", "shared", or "account" schema: type: string - name: group_id in: query description: Only views belonging to given group schema: type: integer - name: sort_by in: query description: Possible values are "alphabetical", "created_at", or "updated_at". Defaults to "position" schema: type: string - name: sort_order in: query description: One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ViewsResponse" /api/v2/views/compact: get: operationId: ListCompactViews tags: - Views summary: List Views - Compact description: | A compacted list of shared and personal views available to the current user. This endpoint never returns more than 32 records and does not respect the "per_page" option. #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ViewsResponse" /api/v2/views/count: get: operationId: CountViews tags: - Views summary: Count Views description: |- Returns an approximate count of shared and personal views available to the current user. If the count exceeds 100,000, the count will return a cached result. This cached result will update every 24 hours. The `count[refreshed_at]` property is a timestamp that indicates when the count was last updated. **Note**: When the count exceeds 100,000, `count[refreshed_at]` may occasionally be null. This indicates that the count is being updated in the background, and `count[value]` is limited to 100,000 until the update is complete. #### Allowed For * Agents responses: "200": description: Count of views content: application/json: schema: $ref: "#/components/schemas/ViewsCountResponse" /api/v2/views/count_many: get: operationId: GetViewCounts tags: - Views summary: Count Tickets in Views description: | Returns the ticket count of each view in a list of views. Accepts up to 20 view ids per request. For the ticket count of a single view, see [Count Tickets in View](#count-tickets-in-view). Only returns values for personal and shared views accessible to the user performing the request. This endpoint is rate limited to 6 requests every 5 minutes. #### Allowed For * Agents parameters: - name: ids in: query description: List of view's ids separated by commas. required: true schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ViewCountsResponse" /api/v2/views/destroy_many: delete: operationId: BulkDeleteViews tags: - Views summary: Bulk Delete Views description: | Deletes the views corresponding to the provided list of IDs. #### Allowed For * Agents parameters: - name: ids in: query description: The IDs of the views to delete required: true schema: type: string responses: "204": description: No Content response /api/v2/views/preview: post: operationId: PreviewViews tags: - Views summary: Preview Views description: | You can preview views by constructing the conditions in the proper format and nesting them under the `view` property. See [Conditions reference](/documentation/ticketing/reference-guides/conditions-reference/). The output can also be controlled by passing in any of the following parameters and nesting them under the `output` property. | Name | Type | Comment | --------------- | ------- | ------- | columns | Array | The ticket fields to display. System fields are looked up by name, custom fields by title or id. See the [View columns](#view-columns) table | group_by | String | When present, the field by which the tickets are grouped | group_order | String | The direction the tickets are grouped. May be one of "asc" or "desc" | sort_order | String | The direction the tickets are sorted. May be one of "asc" or "desc" | sort_by | String | The ticket field used for sorting. This will either be a title or a custom field id. This endpoint is rate limited to 5 requests per minute, per view, per agent. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](/api-reference/introduction/pagination/). #### Allowed For * Agents parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ViewResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/views/preview/count: post: operationId: PreviewCount tags: - Views summary: Preview Ticket Count description: | Returns the ticket count for a single preview. #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ViewCountResponse" /api/v2/views/search: get: operationId: SearchViews tags: - Views summary: Search Views description: | #### Pagination * Offset pagination only See [Using Offset Pagination](/api-reference/ticketing/introduction/#using-offset-pagination). #### Allowed For * Agents #### Sideloads The following sideloads are supported. For more information, see [Side-loading](/documentation/ticketing/using-the-zendesk-api/side_loading/). | Name | Will sideload | ---------------- | ------------- | app_installation | The app installation that requires each view, if present | permissions | The permissions for each view parameters: - name: query in: query description: Query string used to find all views with matching title required: true schema: type: string - name: access in: query description: Filter views by access. May be "personal", "shared", or "account" schema: type: string - name: active in: query description: Filter by active views if true or inactive views if false schema: type: boolean - name: group_id in: query description: Filter views by group schema: type: integer - name: sort_by in: query description: Possible values are "alphabetical", "created_at", "updated_at", and "position". If unspecified, the views are sorted by relevance schema: type: string - name: sort_order in: query description: One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others schema: type: string - name: include in: query description: A sideload to include in the response. See [Sideloads](#sideloads-3) schema: type: string responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ViewsResponse" /api/v2/views/show_many: get: operationId: ListViewsById tags: - Views summary: List Views By ID description: | #### Allowed For * Agents #### Sideloads The following sideloads are supported: | Name | Will sideload | ---------------- | ------------- | app_installation | The app installation that requires each view, if present | permissions | The permissions for each view parameters: - name: ids in: query description: List of view's ids separated by commas. required: true schema: type: string - name: active in: query description: Only active views if true, inactive views if false schema: type: boolean responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ViewsResponse" /api/v2/views/update_many: put: operationId: UpdateManyViews tags: - Views summary: Update Many Views description: | #### Allowed For * Agents #### Request Parameters The PUT request expects a `views` object that lists the views to update. Each view may have the following properties: | Name | Mandatory | Description | -------- | --------- | ----------- | id | yes | The ID of the view to update | position | no | The new position of the view | active | no | The active status of the view (true or false) #### Example Request Body ```js { "views": [ {"id": 25, "position": 3}, {"id": 23, "position": 5}, {"id": 27, "position": 9}, {"id": 22, "position": 7} ] } ``` responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/ViewsResponse" /api/v2/workspaces: get: operationId: ListWorkspaces tags: - Workspaces summary: List Workspaces description: | #### Allowed For * Admins, Agents responses: "200": description: Success Response content: application/json: schema: $ref: "#/components/schemas/WorkspaceResponse" post: operationId: CreateWorkspace tags: - Workspaces summary: Create Workspace description: | #### Allowed For * Admins requestBody: content: application/json: schema: type: object properties: workspace: $ref: "#/components/schemas/WorkspaceInput" responses: "201": description: Created workspace content: application/json: schema: type: object properties: workspace: $ref: "#/components/schemas/WorkspaceObject" /api/v2/workspaces/{workspace_id}: parameters: - $ref: "#/components/parameters/WorkspaceId" get: operationId: ShowWorkspace tags: - Workspaces summary: Show Workspace description: | #### Allowed For * Admins responses: "200": description: Successful response content: application/json: schema: type: object properties: workspace: $ref: "#/components/schemas/WorkspaceObject" put: operationId: UpdateWorkspace tags: - Workspaces summary: Update Workspace description: |- #### Allowed For * Admins requestBody: content: application/json: schema: type: object properties: workspace: $ref: "#/components/schemas/WorkspaceInput" responses: "200": description: OK content: application/json: schema: type: object properties: workspace: $ref: "#/components/schemas/WorkspaceObject" delete: operationId: DeleteWorkspace tags: - Workspaces summary: Delete Workspace description: | #### Allowed For * Admins responses: "204": description: No Content /api/v2/workspaces/destroy_many: delete: operationId: DestroyManyWorkspaces tags: - Workspaces summary: Bulk Delete Workspaces description: | #### Allowed For * Admins parameters: - name: ids in: query description: The ids of the workspaces to delete required: true schema: type: array items: type: integer responses: "200": description: Succesful response content: application/json: schema: type: string description: Empty response /api/v2/workspaces/reorder: put: operationId: ReorderWorkspaces tags: - Workspaces summary: Reorder Workspaces description: | #### Allowed For * Admins requestBody: content: application/json: schema: type: object properties: ids: type: array items: type: number responses: "200": description: Succesful response content: application/json: schema: type: string description: Empty response /oauth/tokens: post: operationId: CreateTokenForGrantType tags: - Grant Type Tokens summary: Create Token for Grant Type description: | Returns an OAuth access token in exchange for an [authorization code](https://support.zendesk.com/hc/en-us/articles/203663836#topic_pvr_ncl_1l) valid for 120 seconds. Using a Zendesk username and password to gain an OAuth access token (password grant type flow) has been deprecated and is highly discouraged. An access token can be revoked. Use the [OAuth Tokens API](/api-reference/ticketing/oauth/oauth_tokens) to list, show, or revoke tokens. The refresh token grant type allows for refreshing an access token that has either expired or is about to expire. See [Oauth Tokens for Grant Types](/api-reference/ticketing/oauth/grant_type_tokens/). #### Request parameters The POST request takes the following parameters, which must be formatted as JSON: | Name | Description | ------------- | -------------------------------------------------- | grant_type | "authorization_code" or "refresh_token" | code | Authorization grant flow only. The authorization code you received from Zendesk after the user granted access. See [Handle the user's authorization decision](https://support.zendesk.com/hc/en-us/articles/203663836#topic_tfc_cdl_1l) in Help Center | client_id | The **Unique Identifier** specified in an OAuth client in the Support admin interface (**Admin** > **Channels** > **API** > **OAuth Clients**). See [Registering your application with Zendesk](https://support.zendesk.com/hc/en-us/articles/203663836#topic_s21_lfs_qk) | client_secret | The **Secret** specified in an OAuth client in the Support admin interface (**Admin** > **Channels** > **API** > **OAuth Clients**). See [Registering your application with Zendesk](https://support.zendesk.com/hc/en-us/articles/203663836#topic_s21_lfs_qk) | redirect_uri | Authorization grant flow only. The redirect URL you specified when you sent the user to the Zendesk authorization page. For ID purposes only. See [Send the user to the Zendesk authorization page](https://support.zendesk.com/hc/en-us/articles/203663836#topic_qk3_d3s_qk) | scope | Valid scope for this token. A string of space-separated values. See [Scope](#scope) below | expires_in | Number of seconds the access token is valid. Must be more than 300 seconds (5 minutes) and less than 172,800 seconds (2 days), or less than `refresh_token_expires_in`, whichever is the smallest. Defaults to null | refresh_token_expires_in | Number of seconds the refresh token is valid. Must be more than 604,800 seconds (7 days) or `expires_in` (if given), and less than 7,776,000 seconds (90 days). Defaults to 2,592,000 seconds (30 days) | refresh_token | The refresh token **Example Node.js authorization code grant flow** ```javascript const tokenResponse = await axios.post( `https://${ZENDESK_SUBDOMAIN}.zendesk.com/oauth/tokens`, { grant_type: "authorization_code", code: req.query.code, client_id: ZENDESK_CLIENT_ID, redirect_uri: REDIRECT_URI_PKCE, scope: "read write", code_verifier: CODE_VERIFIER, expires_in: 86400, refresh_token_expires_in: 604800, }, { headers: { "Content-Type": "application/json" } } ); ``` **Example Node.js refresh token grant flow** ```javascript const tokenResponse = await axios.post( `https://${ZENDESK_SUBDOMAIN}.zendesk.com/oauth/tokens`, { grant_type: "refresh_token", refresh_token: refresh_token, client_id: ZENDESK_CLIENT_ID, client_secret: ZENDESK_CLIENT_SECRET, scopes: "tickets:write", expires_in: 86400, refresh_token_expires_in: 604800, }, { headers: { "Content-Type": "application/json" } } ); ``` #### Scope You must specify a scope to control the app's access to Zendesk resources. The "read" scope gives access to GET endpoints. It includes permission to sideload related resources. The "write" scope gives access to POST, PUT, and DELETE endpoints for creating, updating, and deleting resources. **Note**: Don't confuse the **scope** parameter (singular) with the **scopes** parameter (plural) for non-grant-type tokens described in [OAuth Tokens](/api-reference/ticketing/oauth/oauth_tokens). The "impersonate" scope allows a Zendesk admin to make requests on behalf of end users. See [Making API requests on behalf of end users](/documentation/ticketing/using-the-zendesk-api/making-api-requests-on-behalf-of-end-users/). For example, the following parameter gives read access to all resources: `"scope": "read"` The following parameter gives read and write access to all resources: `"scope": "read write"` You can fine-tune the scope of the following resources: - tickets - users - auditlogs (read only) - organizations - hc - apps - triggers - automations - targets - webhooks The syntax is as follows: `"scope": "resource:scope"` For example, the following parameter restricts the scope to only reading tickets: `"scope": "tickets:read"` To give read and write access to a resource, specify both scopes: `"scope": "users:read users:write"` To give write access only to one resource, such as organizations, and read access to everything else: `"scope": "organizations:write read"` **Note**: The endpoint returns an access token even if you specify an invalid scope such as `"scope": ["read", "write"]` (no parentheses). Any request you make with the token will return a "Forbidden" error. #### Tokens for Implicit Grant Type The implicit grant flow has been deprecated. It's considered insecure and its use is highly discouraged. responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/OAuthTokenForGrantTypesObject" /api/v2/webhooks: get: summary: List Webhooks description: List webhooks. operationId: listWebhooks tags: - Webhooks parameters: - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - name: filter[name_contains] in: query description: Filters the webhooks by a string in the name required: false schema: type: string - name: filter[status] in: query description: Filters the webhooks by webhook status required: false schema: type: string enum: - active - inactive - name: sort in: query description: Defines the sorting criteria. Only supports name and status required: false schema: type: string enum: - name - status responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/WebhookListResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor post: summary: Create or Clone Webhook description: | Creates or clones a webhook. The clone_webhook_id query parameter is only required when cloning a webhook. A request body is only required when creating a webhook. Note that admins cannot clone webhooks created by Zendesk apps. **Webhooks for trial accounts**: Zendesk trial accounts are limited to 10 webhooks. operationId: createOrCloneWebhook tags: - Webhooks parameters: - name: clone_webhook_id in: query description: id of the webhook to clone. Only required if cloning a webhook. required: false schema: type: string requestBody: description: Webhook data (required when creating, not when cloning) required: false content: application/json: schema: $ref: "#/components/schemas/WebhookCreateRequest" responses: "201": description: Webhook created successfully content: application/json: schema: $ref: "#/components/schemas/WebhookResponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "403": description: Forbidden - Trial account webhook limit exceeded or insufficient permissions content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v2/webhooks/test: post: summary: Test Webhook description: | Tests a new or existing webhook. When testing an existing webhook, the existing webhook data will be attached automatically as part of the outbound test request. The data includes the request format, http method, authentication method (only if same type and add_position are attached), and signing secret. The request payload data will overwrite existing webhook data in the outbound test request. operationId: testWebhook tags: - Webhooks parameters: - name: webhook_id in: query description: The webhook to be tested. Only required for testing an existing webhook. required: false schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/WebhookTestRequest" responses: "200": description: Test completed successfully content: application/json: schema: $ref: "#/components/schemas/WebhookTestResponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v2/webhooks/{webhook_id}: get: summary: Show Webhook description: Returns the specified webhook. operationId: showWebhook tags: - Webhooks parameters: - name: webhook_id in: path description: Webhook id required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/WebhookResponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" put: summary: Update Webhook description: | Updates the specified webhook. **Restrictions**: Admins cannot set `external_source` and `signing_secret` when updating a webhook. operationId: updateWebhook tags: - Webhooks parameters: - name: webhook_id in: path description: Webhook id required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/WebhookUpdateRequest" responses: "204": description: No Content - Successfully updated "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" patch: summary: Patch Webhook description: | Use the webhook_id to update a webhook. **Restrictions**: Admins cannot set `external_source` and `signing_secret` when patching a webhook. operationId: patchWebhook tags: - Webhooks parameters: - name: webhook_id in: path description: Webhook id required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/WebhookPatchRequest" responses: "204": description: No Content - Successfully patched "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" delete: summary: Delete Webhook description: Deletes the specified webhook. operationId: deleteWebhook tags: - Webhooks parameters: - name: webhook_id in: path description: Webhook id required: true schema: type: string responses: "204": description: No Content - Successfully deleted "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v2/webhooks/{webhook_id}/invocations: get: summary: List Webhook Invocations description: Returns up to 7 days of invocations for a webhook. operationId: listWebhookInvocations tags: - Webhook Invocations parameters: - name: webhook_id in: path description: Webhook id required: true schema: type: string - name: filter[from_ts] in: query description: Filters invocations by from timestamp. Use ISO 8601 UTC format required: false schema: type: string format: date-time - name: filter[status] in: query description: Filters invocations by invocation status required: false schema: type: string enum: - unknown - accepted - success - failed - timeout - circuit broken - throttled - client error - server error - name: filter[to_ts] in: query description: Filters invocations by timestamp. Use ISO 8601 UTC format required: false schema: type: string format: date-time - $ref: "#/components/parameters/PageBefore" - $ref: "#/components/parameters/PageAfter" - $ref: "#/components/parameters/PageSize" - name: sort in: query description: Defines a invocation attribute to sort invocations required: false schema: type: string enum: - latest_completed_at - -latest_completed_at responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/WebhookInvocationListResponse" x-speakeasy-pagination: type: cursor inputs: - name: page[after] in: parameters type: cursor outputs: nextCursor: $.meta.after_cursor /api/v2/webhooks/{webhook_id}/invocations/{invocation_id}/attempts: get: summary: List Webhook Invocation Attempts description: Returns the invocation attempts for the specified webhook. operationId: listWebhookInvocationAttempts tags: - Webhook Invocations parameters: - name: webhook_id in: path description: Webhook id required: true schema: type: string - name: invocation_id in: path description: Webhook invocation id required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/WebhookInvocationAttemptListResponse" /api/v2/webhooks/{webhook_id}/signing_secret: get: summary: Show Webhook Signing Secret description: "Returns the webhook's signing secret. Note that admins cannot reveal secrets of webhooks created by Zendesk apps. " operationId: showWebhookSigningSecret tags: - Webhooks parameters: - name: webhook_id in: path description: Webhook id required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/WebhookSigningSecretResponse" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" post: summary: Reset Webhook Signing Secret description: "Resets a signing secret for the specified webhook. Note that admins cannot reset secrets of webhooks created by Zendesk apps. " operationId: resetWebhookSigningSecret tags: - Webhooks parameters: - name: webhook_id in: path description: Webhook id required: true schema: type: string responses: "201": description: Signing secret reset successfully content: application/json: schema: $ref: "#/components/schemas/WebhookSigningSecretResponse" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v2/organizations/{organization_id}/tags: parameters: - $ref: "#/components/parameters/OrganizationId" get: operationId: listOrganizationTags tags: - Tags summary: List Organization Tags description: | Lists all tags associated with a specific organization. #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TagsResponse" "404": $ref: "#/components/responses/NotFound" post: operationId: setOrganizationTags tags: - Tags summary: Set Organization Tags description: | Replaces all existing tags on an organization with the provided tags. #### Allowed For * Agents requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/TagsRequest" responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/TagsResponse" "404": $ref: "#/components/responses/NotFound" put: operationId: addOrganizationTags tags: - Tags summary: Add Organization Tags description: | Adds tags to an organization. #### Allowed For * Agents requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/TagsRequest" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TagsResponse" "404": $ref: "#/components/responses/NotFound" delete: operationId: removeOrganizationTags tags: - Tags summary: Remove Organization Tags description: | Removes specified tags from an organization. #### Allowed For * Agents requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/TagsRequest" responses: "204": description: No Content - Tags successfully removed "404": $ref: "#/components/responses/NotFound" /api/v2/users/{user_id}/tags: parameters: - $ref: "#/components/parameters/UserId" get: operationId: listUserTags tags: - Tags summary: List User Tags description: | Lists all tags associated with a specific user. #### Allowed For * Agents responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TagsResponse" "404": $ref: "#/components/responses/NotFound" post: operationId: setUserTags tags: - Tags summary: Set User Tags description: | Replaces all existing tags on a user with the provided tags. #### Allowed For * Agents requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/TagsRequest" responses: "201": description: Created response content: application/json: schema: $ref: "#/components/schemas/TagsResponse" "404": $ref: "#/components/responses/NotFound" put: operationId: addUserTags tags: - Tags summary: Add User Tags description: | Adds tags to a user. #### Allowed For * Agents requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/TagsRequest" responses: "200": description: Success response content: application/json: schema: $ref: "#/components/schemas/TagsResponse" "404": $ref: "#/components/responses/NotFound" delete: operationId: removeUserTags tags: - Tags summary: Remove User Tags description: | Removes specified tags from a user. #### Allowed For * Agents requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/TagsRequest" responses: "204": description: No Content - Tags successfully removed "404": $ref: "#/components/responses/NotFound" components: schemas: AccountSettingsActiveFeaturesObject: type: object description: The active features for an account. See [Active Features](#active-features) properties: agent_forwarding: type: boolean allow_ccs: type: boolean allow_email_template_customization: type: boolean automatic_answers: type: boolean bcc_archiving: type: boolean benchmark_opt_out: type: boolean business_hours: type: boolean chat: type: boolean chat_about_my_ticket: type: boolean csat_reason_code: type: boolean custom_dkim_domain: type: boolean customer_context_as_default: type: boolean customer_satisfaction: type: boolean dynamic_contents: type: boolean explore: type: boolean explore_on_support_ent_plan: type: boolean explore_on_support_pro_plan: type: boolean facebook: type: boolean facebook_login: type: boolean fallback_composer: type: boolean forum_analytics: type: boolean good_data_and_explore: type: boolean google_login: type: boolean is_abusive: type: boolean light_agents: type: boolean markdown: type: boolean on_hold_status: type: boolean organization_access_enabled: type: boolean rich_content_in_emails: type: boolean sandbox: type: boolean satisfaction_prediction: type: boolean suspended_ticket_notification: type: boolean ticket_forms: type: boolean ticket_tagging: type: boolean topic_suggestion: type: boolean twitter: type: boolean twitter_login: type: boolean user_org_fields: type: boolean user_tagging: type: boolean voice: type: boolean AccountSettingsAgentObject: type: object description: Configuration for the agent workspace. See [Agents](#agents) properties: agent_home: type: boolean agent_workspace: type: boolean aw_self_serve_migration_enabled: type: boolean focus_mode: type: boolean idle_timeout_enabled: type: boolean unified_agent_statuses: type: boolean AccountSettingsApiObject: type: object description: API configuration options. See [API](#api) properties: accepted_api_agreement: type: boolean api_password_access: type: string api_token_access: type: string AccountSettingsAppsObject: type: object description: Apps configuration options. See [Apps](#apps) properties: create_private: type: boolean create_public: type: boolean use: type: boolean AccountSettingsBillingObject: type: object description: Billing configuration options. See [Billing](#billing) properties: backend: type: string AccountSettingsBrandingObject: type: object description: Branding settings. See [Branding](#branding) properties: favicon_url: type: string nullable: true header_color: type: string header_logo_url: type: string nullable: true page_background_color: type: string tab_background_color: type: string text_color: type: string AccountSettingsBrandsObject: type: object description: Brand settings. See [Brands](#brands) properties: default_brand_id: type: integer require_brand_on_new_tickets: type: boolean AccountSettingsCdnObject: type: object description: CDN settings properties: cdn_provider: type: string fallback_cdn_provider: type: string hosts: type: array items: type: object properties: name: type: string url: type: string AccountSettingsChatObject: type: object description: Zendesk Chat settings. See [Chat](#chat) properties: available: type: boolean enabled: type: boolean integrated: type: boolean maximum_request_count: type: integer welcome_message: type: string AccountSettingsCrossSellObject: type: object description: Cross Sell settings properties: show_chat_tooltip: type: boolean xsell_source: type: string nullable: true AccountSettingsEmailObject: type: object description: Email settings properties: accept_wildcard_emails: type: boolean custom_dkim_domain: type: boolean email_sender_authentication: type: boolean description: Whether incoming email is subjected to sender authentication checks (SPF, DKIM) email_sender_authentication_profile: type: string description: The sender authentication profile in use. enum: - default - enhanced email_status: type: boolean description: Whether email status and delivery information is shown in the Agent Workspace email_template_photos: type: boolean email_template_section: type: boolean gmail_actions: type: boolean modern_email_template: type: boolean no_mail_delimiter: type: boolean personalized_replies: type: boolean send_gmail_messages_via_gmail: type: boolean AccountSettingsGoogleAppsObject: type: object description: Google Apps configuration. See [G Suite](#g-suite) properties: has_google_apps: type: boolean has_google_apps_admin: type: boolean AccountSettingsGroupObject: type: object description: Group configuration properties: check_group_name_uniqueness: type: boolean AccountSettingsLimitsObject: type: object description: Account limits configuration. See [Limits](#limits) properties: attachment_size: type: integer AccountSettingsLocalizationObject: type: object description: Internationalization configuration settings. See [Localization](#localization) properties: locale_ids: type: array items: type: integer AccountSettingsLotusObject: type: object description: Support UI settings. See [Lotus](#lotus) properties: pod_id: type: integer prefer_lotus: type: boolean reporting: type: boolean AccountSettingsMetricsObject: type: object description: Account metrics settings. See [Metrics](#metrics) properties: account_size: type: string AccountSettingsObject: type: object properties: active_features: $ref: "#/components/schemas/AccountSettingsActiveFeaturesObject" agents: $ref: "#/components/schemas/AccountSettingsAgentObject" api: $ref: "#/components/schemas/AccountSettingsApiObject" apps: $ref: "#/components/schemas/AccountSettingsAppsObject" billing: $ref: "#/components/schemas/AccountSettingsBillingObject" branding: $ref: "#/components/schemas/AccountSettingsBrandingObject" brands: $ref: "#/components/schemas/AccountSettingsBrandsObject" cdn: $ref: "#/components/schemas/AccountSettingsCdnObject" chat: $ref: "#/components/schemas/AccountSettingsChatObject" cross_sell: $ref: "#/components/schemas/AccountSettingsCrossSellObject" email: $ref: "#/components/schemas/AccountSettingsEmailObject" google_apps: $ref: "#/components/schemas/AccountSettingsGoogleAppsObject" groups: $ref: "#/components/schemas/AccountSettingsGroupObject" limits: $ref: "#/components/schemas/AccountSettingsLimitsObject" localization: $ref: "#/components/schemas/AccountSettingsLocalizationObject" lotus: $ref: "#/components/schemas/AccountSettingsLotusObject" metrics: $ref: "#/components/schemas/AccountSettingsMetricsObject" onboarding: $ref: "#/components/schemas/AccountSettingsOnboardingObject" routing: $ref: "#/components/schemas/AccountSettingsRoutingObject" rule: $ref: "#/components/schemas/AccountSettingsRuleObject" side_conversations: $ref: "#/components/schemas/AccountSettingsSideConversationsObject" statistics: $ref: "#/components/schemas/AccountSettingsStatisticsObject" ticket_form: $ref: "#/components/schemas/AccountSettingsTicketFormObject" tickets: $ref: "#/components/schemas/AccountSettingsTicketObject" twitter: $ref: "#/components/schemas/AccountSettingsTwitterObject" user: $ref: "#/components/schemas/AccountSettingsUserObject" voice: $ref: "#/components/schemas/AccountSettingsVoiceObject" AccountSettingsOnboardingObject: type: object description: Onboarding settings properties: checklist_onboarding_version: type: integer onboarding_segments: type: string nullable: true product_sign_up: type: string nullable: true AccountSettingsResponse: type: object properties: settings: $ref: "#/components/schemas/AccountSettingsObject" AccountSettingsRoutingObject: type: object description: Configuration for routing. See [Routing](#routing) properties: autorouting_tag: type: string enabled: type: boolean max_email_capacity: type: integer max_messaging_capacity: type: integer reassignment_messaging_enabled: type: boolean reassignment_messaging_timeout: type: integer reassignment_talk_timeout: type: integer AccountSettingsRuleObject: type: object description: Rules settings for triggers, macros, views, and automations. See [Rules](#rules) properties: macro_most_used: type: boolean macro_order: type: string skill_based_filtered_views: type: array items: type: object additionalProperties: true using_skill_based_routing: type: boolean AccountSettingsSideConversationsObject: type: object description: Side conversations settings properties: email_channel: type: boolean msteams_channel: type: boolean show_in_context_panel: type: boolean slack_channel: type: boolean tickets_channel: type: boolean AccountSettingsStatisticsObject: type: object description: Account statistics settings. See [Statistics](#statistics) properties: forum: type: boolean rule_usage: type: boolean search: type: boolean AccountSettingsTicketFormObject: type: object description: Ticket form settings. See [Ticket Form](#ticket-form) properties: raw_ticket_forms_instructions: type: string ticket_forms_instructions: type: string AccountSettingsTicketObject: type: object description: Ticket settings. See [Tickets](#tickets) properties: accepted_new_collaboration_tos: type: boolean agent_collision: type: boolean agent_invitation_enabled: type: boolean agent_ticket_deletion: type: boolean allow_group_reset: type: boolean assign_default_organization: type: boolean assign_tickets_upon_solve: type: boolean auto_translation_enabled: type: boolean auto_updated_ccs_followers_rules: type: boolean chat_sla_enablement: type: boolean collaboration: type: boolean comments_public_by_default: type: boolean default_solved_ticket_reassignment_strategy: type: string email_attachments: type: boolean emoji_autocompletion: type: boolean follower_and_email_cc_collaborations: type: boolean has_color_text: type: boolean is_first_comment_private_enabled: type: boolean light_agent_email_ccs_allowed: type: boolean list_empty_views: type: boolean list_newest_comments_first: type: boolean markdown_ticket_comments: type: boolean maximum_personal_views_to_list: type: integer modern_ticket_reassignment: type: boolean private_attachments: type: boolean rich_text_comments: type: boolean show_modern_ticket_reassignment: type: boolean status_hold: type: boolean tagging: type: boolean using_skill_based_routing: type: boolean AccountSettingsTwitterObject: type: object description: X (formerly Twitter) settings. See [X](#x-formerly-twitter) properties: shorten_url: type: string AccountSettingsUserObject: type: object description: User settings. See [Users](#users) properties: agent_created_welcome_emails: type: boolean end_user_phone_number_validation: type: boolean have_gravatars_enabled: type: boolean language_selection: type: boolean multiple_organizations: type: boolean tagging: type: boolean time_zone_selection: type: boolean AccountSettingsVoiceObject: type: object description: Zendesk Talk settings. See [Voice](#voice) properties: agent_confirmation_when_forwarding: type: boolean agent_wrap_up_after_calls: type: boolean enabled: type: boolean logging: type: boolean maximum_queue_size: type: integer maximum_queue_wait_time: type: integer only_during_business_hours: type: boolean outbound_enabled: type: boolean recordings_public: type: boolean uk_mobile_forwarding: type: boolean ActionObject: type: object properties: field: type: string description: The name of a ticket field to modify value: type: string description: The new value of the field ActionsObject: type: object properties: actions: type: array items: $ref: "#/components/schemas/ActionObject" ActivitiesCountResponse: type: object properties: count: type: object properties: refreshed_at: type: string format: date-time value: type: integer ActivitiesResponse: type: object properties: activities: type: array items: $ref: "#/components/schemas/ActivityObject" readOnly: true actors: type: array items: type: object additionalProperties: true readOnly: true count: type: integer readOnly: true next_page: type: string nullable: true readOnly: true previous_page: type: string nullable: true readOnly: true users: type: array items: type: object additionalProperties: true readOnly: true ActivityObject: title: Ticket Activities type: object properties: actor: type: object description: The full user record of the user responsible for the ticket activity. See [Users](/api-reference/ticketing/users/users/) allOf: - $ref: "#/components/schemas/UserObject" readOnly: true actor_id: type: integer description: The id of the user responsible for the ticket activity. An `actor_id` of "-1" is a Zendesk system user, such as an automations action. readOnly: true created_at: type: string description: When the record was created readOnly: true id: type: integer description: Automatically assigned on creation readOnly: true object: type: object description: The content of the activity. Can be a ticket, comment, or change. additionalProperties: true readOnly: true target: type: object description: The target of the activity, a ticket. additionalProperties: true readOnly: true title: type: string description: Description of the activity readOnly: true updated_at: type: string description: When the record was last updated readOnly: true url: type: string description: The API url of the activity readOnly: true user: type: object description: The full user record of the agent making the request. See [Users](/api-reference/ticketing/users/users/) allOf: - $ref: "#/components/schemas/UserObject" readOnly: true user_id: type: integer description: The id of the agent making the request readOnly: true verb: type: string description: The type of activity. Can be "tickets.assignment", "tickets.comment", or "tickets.priority_increase" readOnly: true ActivityResponse: type: object properties: activity: $ref: "#/components/schemas/ActivityObject" ApprovalRequestCreateRequest: title: ApprovalRequestCreateRequest type: object properties: assignee_user: type: integer description: User id of the request approver message: type: string description: Details for the approval request subject: type: string description: Subject for the approval request ticket_id: type: integer description: Ticket id to attach the approval request to workflow_instance_id: type: string description: Workflow instance id for the approval request ApprovalRequestDecision: title: ApprovalRequestDecision type: object properties: decided_at: type: string format: date-time description: The time the decision was made readOnly: true decided_by_user: $ref: "#/components/schemas/ApprovalRequestUser" decision_notes: type: string description: Notes for the decision id: type: string description: Unique identifier for the decision status: type: string description: Status of the decision ApprovalRequestObject: title: ApprovalRequestObject type: object properties: approval_request: type: object properties: assignee_user: $ref: "#/components/schemas/ApprovalRequestUser" created_at: type: string format: date-time description: The time the approval request was created readOnly: true created_by_user: $ref: "#/components/schemas/ApprovalRequestUser" decided_at: type: string format: date-time description: The time at which the approver submitted a decision about the request. nullable: true decisions: type: array description: List of decisions for the approval request items: $ref: "#/components/schemas/ApprovalRequestDecision" id: type: string description: Unique identifier for the approval request message: type: string description: Details for the approval request status: type: string description: Current status of the approval request subject: type: string description: Subject for the approval request ticket_details: $ref: "#/components/schemas/ApprovalTicketDetails" withdrawn_reason: type: string description: Reason for withdrawing the approval request nullable: true ApprovalRequestUser: title: ApprovalRequestUser type: object properties: id: type: integer description: Unique identifier for the user name: type: string description: Name of the user photo: type: object description: Details for the approval request properties: content_url: type: string description: URL for the user's photo ApprovalRequestsSearchResponse: title: ApprovalRequestsSearchResponse type: object properties: after_cursor: type: string description: Cursor for the next page of results nullable: true after_url: type: string description: URL for the next page of results nullable: true approval_requests: type: array items: type: object properties: approval_workflow_instance_id: type: string description: Unique identifier for the approval workflow instance. See [Approval Workflow Instances](/api-reference/ticketing/approvals/approval_workflow_instances/#approval-workflow-instances) created_at: type: string format: date-time description: The time the approval request was created was created readOnly: true created_by_name: type: string description: Name of the user that created the approval request id: type: string description: Unique identifier for the approval request message: type: string description: Details for the approval request requester_name: type: string description: Name of the user that can make a decision on the approval request status: type: string description: Current status of the approval request subject: type: string description: Subject for the approval request before_cursor: type: string description: Cursor for the previous page of results nullable: true before_url: type: string description: URL for the previous page of results nullable: true ApprovalTicketDetails: title: ApprovalTicketDetails type: object properties: custom_fields: type: array description: Custom fields for the ticket. See [Setting custom field values](/documentation/ticketing/managing-tickets/creating-and-updating-tickets#setting-custom-field-values) items: type: object properties: id: type: integer description: The id of the custom field value: type: string description: The value of the custom field id: type: integer description: Unique identifier for the user priority: type: string description: Priority of the ticket requester: $ref: "#/components/schemas/ApprovalRequestUser" status: type: string description: Status of the ticket ApprovalWorkflowInstanceCreateRequest: title: ApprovalWorkflowInstanceCreateRequest type: object properties: name: type: string description: Name of the approval workflow instance ticket_id: type: integer description: Ticket id associated with the approval workflow instance ApprovalWorkflowInstanceObject: title: ApprovalWorkflowInstance type: object properties: custom_object_record: $ref: "#/components/schemas/CustomObjectRecord" AssigneeFieldAssignableAgentObject: title: AssigneeFieldAssignableAgents type: object properties: avatar_url: type: string description: URL of Agent's avatar nullable: true id: type: integer description: Agent Support ID name: type: string description: Name of the agent AssigneeFieldAssignableGroupAgentsResponse: type: object properties: agents: type: array items: $ref: "#/components/schemas/AssigneeFieldAssignableAgentObject" count: type: integer description: Number of agents listed in `agents` property. next_page: type: string nullable: true readOnly: true previous_page: type: string nullable: true readOnly: true AssigneeFieldAssignableGroupObject: title: AssigneeFieldAssignableGroups type: object properties: description: type: string description: Description of the group readOnly: true id: type: integer description: Group ID readOnly: true name: type: string description: Name of the group readOnly: true AssigneeFieldAssignableGroupsAndAgentsSearchResponse: type: object properties: agents: type: array items: $ref: "#/components/schemas/AssigneeFieldAssignableSearchAgentObject" count: type: integer description: Number of agents + groups listed from search result. groups: type: array items: $ref: "#/components/schemas/AssigneeFieldAssignableSearchGroupObject" AssigneeFieldAssignableGroupsResponse: type: object properties: count: type: integer description: Number of groups listed in `groups` property. groups: type: array items: $ref: "#/components/schemas/AssigneeFieldAssignableGroupObject" next_page: type: string nullable: true readOnly: true previous_page: type: string nullable: true readOnly: true AssigneeFieldAssignableSearchAgentObject: type: object properties: group: type: string description: Name of the agent's group group_id: type: integer description: Agent's Group ID id: type: integer description: Agent ID name: type: string description: Name of the agent photo_url: type: string description: URL of Avatar nullable: true AssigneeFieldAssignableSearchGroupObject: type: object properties: id: type: integer description: Group ID name: type: string description: Name of the group AttachmentBaseObject: type: object properties: content_type: type: string description: 'The content type of the image. Example value: "image/png"' readOnly: true content_url: type: string description: A full URL where the attachment image file can be downloaded. The file may be hosted externally so take care not to inadvertently send Zendesk authentication credentials. See [Working with url properties](/documentation/ticketing/managing-tickets/working-with-url-properties) readOnly: true deleted: type: boolean description: If true, the attachment has been deleted readOnly: true file_name: type: string description: The name of the image file readOnly: true height: type: integer description: The height of the image file in pixels. If height is unknown, returns null readOnly: true id: type: integer description: Automatically assigned when created readOnly: true inline: type: boolean description: | If true, the attachment is excluded from the attachment list and the attachment's URL can be referenced within the comment of a ticket. Default is false readOnly: true malware_access_override: type: boolean description: If true, you can download an attachment flagged as malware. If false, you can't download such an attachment. readOnly: true malware_scan_result: type: string description: 'The result of the malware scan. There is a delay between the time the attachment is uploaded and when the malware scan is completed. Usually the scan is done within a few seconds, but high load conditions can delay the scan results. Possible values: "malware_found", "malware_not_found", "failed_to_scan", "not_scanned"' readOnly: true mapped_content_url: type: string description: The URL the attachment image file has been mapped to readOnly: true size: type: integer description: The size of the image file in bytes readOnly: true url: type: string description: A URL to access the attachment details readOnly: true width: type: integer description: The width of the image file in pixels. If width is unknown, returns null readOnly: true AttachmentObject: type: object description: A file represented as an [Attachment](/api-reference/ticketing/tickets/ticket-attachments/) object allOf: - $ref: "#/components/schemas/AttachmentBaseObject" - $ref: "#/components/schemas/AttachmentThumbnails" AttachmentResponse: type: object properties: attachment: $ref: "#/components/schemas/AttachmentObject" AttachmentThumbnails: type: object properties: thumbnails: type: array description: An array of attachment objects. Note that photo thumbnails do not have thumbnails items: $ref: "#/components/schemas/AttachmentBaseObject" readOnly: true AttachmentUpdateInput: type: object properties: malware_access_override: type: boolean description: If true, allows access to attachments with detected malware. AttachmentUpdateRequest: type: object properties: attachment: $ref: "#/components/schemas/AttachmentUpdateInput" AttachmentUploadResponse: type: object properties: upload: type: object properties: attachment: $ref: "#/components/schemas/AttachmentObject" attachments: type: array items: $ref: "#/components/schemas/AttachmentObject" token: type: string description: Token for subsequent request readOnly: true AuditLogObject: type: object properties: action: type: string description: 'Type of change made. Possible values are "create", "destroy", "exported", "login", and "update" ' readOnly: true action_label: type: string description: Localized string of action field readOnly: true actor_id: type: integer description: id of the user or system that initiated the change readOnly: true actor_name: type: string description: Name of the user or system that initiated the change readOnly: true change_description: type: string description: The description of the change that occurred readOnly: true created_at: type: string format: date-time description: The time the audit got created readOnly: true id: type: integer description: The id automatically assigned upon creation readOnly: true ip_address: type: string description: The IP address of the user doing the audit readOnly: true source_id: type: integer description: The id of the item being audited readOnly: true source_label: type: string description: The name of the item being audited readOnly: true source_type: type: string description: | Item type being audited. Typically describes the system where the change was initiated. Possible values vary based on your account's Zendesk products and activity. Common values include "apitoken", "rule", "ticket", "user", and "zendesk/app_market/app". The "rule" value is used for [automations](https://support.zendesk.com/hc/en-us/articles/4408832701850), [macros](https://support.zendesk.com/hc/en-us/articles/4408844187034), [triggers](https://support.zendesk.com/hc/en-us/articles/4408822236058), [views](https://support.zendesk.com/hc/en-us/articles/4408888828570), and other automated business rules readOnly: true url: type: string description: The URL to access the audit log readOnly: true AuditLogResponse: type: object properties: audit_log: $ref: "#/components/schemas/AuditLogObject" AuditLogsResponse: type: object properties: audit_logs: type: array items: $ref: "#/components/schemas/AuditLogObject" AuditObject: type: object properties: author_id: type: integer readOnly: true description: ID of the user who created the audit created_at: type: string format: date-time readOnly: true description: When the audit was created events: type: array items: $ref: "#/components/schemas/AuditEvent" readOnly: true description: Array of events that occurred in this audit id: type: integer readOnly: true description: Automatically assigned audit ID metadata: type: object readOnly: true description: Additional metadata about the audit ticket_id: type: integer readOnly: true description: ID of the ticket this audit belongs to via: $ref: "#/components/schemas/ViaObject" AuditEvent: type: object discriminator: propertyName: type mapping: Create: "#/components/schemas/CreateEvent" Change: "#/components/schemas/ChangeEvent" Comment: "#/components/schemas/CommentEvent" CommentRedactionEvent: "#/components/schemas/CommentRedactionEvent" AttachmentRedactionEvent: "#/components/schemas/AttachmentRedactionEvent" VoiceComment: "#/components/schemas/VoiceCommentEvent" CommentPrivacyChange: "#/components/schemas/CommentPrivacyChangeEvent" SuspendedTicketRecovery: "#/components/schemas/SuspendedTicketRecoveryEvent" Notification: "#/components/schemas/NotificationEvent" NotificationWithCcs: "#/components/schemas/NotificationWithCcsEvent" SmsNotification: "#/components/schemas/SmsNotificationEvent" Cc: "#/components/schemas/CcEvent" FollowerNotificationEvent: "#/components/schemas/FollowerNotificationEvent" FollowersChange: "#/components/schemas/FollowerChangeEvent" EmailCcChange: "#/components/schemas/EmailCcChangeEvent" MacroReference: "#/components/schemas/MacroReferenceEvent" SatisfactionRating: "#/components/schemas/SatisfactionRatingEvent" TicketSharingEvent: "#/components/schemas/TicketSharingEvent" OrganizationActivity: "#/components/schemas/OrganizationSubscriptionNotificationEvent" Error: "#/components/schemas/ErrorEvent" Tweet: "#/components/schemas/TweetEvent" FacebookEvent: "#/components/schemas/FacebookEvent" FacebookComment: "#/components/schemas/FacebookCommentEvent" External: "#/components/schemas/ExternalEvent" LogMeInTranscript: "#/components/schemas/LogMeInTranscriptEvent" Push: "#/components/schemas/PushEvent" ChatStartedEvent: "#/components/schemas/ChatStartedEvent" ChatEndedEvent: "#/components/schemas/ChatEndedEvent" AssociateAttValsEvent: "#/components/schemas/SkillAssignedEvent" SurveyOffered: "#/components/schemas/SurveyOfferedEvent" SurveyResponseSubmitted: "#/components/schemas/SurveyResponseSubmittedEvent" OfferedToEvent: "#/components/schemas/OfferedToEvent" RoutingChannelEvent: "#/components/schemas/RoutingChannelEvent" WebhookEvent: "#/components/schemas/WebhookEvent" oneOf: - $ref: "#/components/schemas/CreateEvent" - $ref: "#/components/schemas/ChangeEvent" - $ref: "#/components/schemas/CommentEvent" - $ref: "#/components/schemas/CommentRedactionEvent" - $ref: "#/components/schemas/AttachmentRedactionEvent" - $ref: "#/components/schemas/VoiceCommentEvent" - $ref: "#/components/schemas/CommentPrivacyChangeEvent" - $ref: "#/components/schemas/SuspendedTicketRecoveryEvent" - $ref: "#/components/schemas/NotificationEvent" - $ref: "#/components/schemas/NotificationWithCcsEvent" - $ref: "#/components/schemas/SmsNotificationEvent" - $ref: "#/components/schemas/CcEvent" - $ref: "#/components/schemas/FollowerNotificationEvent" - $ref: "#/components/schemas/FollowerChangeEvent" - $ref: "#/components/schemas/EmailCcChangeEvent" - $ref: "#/components/schemas/MacroReferenceEvent" - $ref: "#/components/schemas/SatisfactionRatingEvent" - $ref: "#/components/schemas/TicketSharingEvent" - $ref: "#/components/schemas/OrganizationSubscriptionNotificationEvent" - $ref: "#/components/schemas/ErrorEvent" - $ref: "#/components/schemas/TweetEvent" - $ref: "#/components/schemas/FacebookEvent" - $ref: "#/components/schemas/FacebookCommentEvent" - $ref: "#/components/schemas/ExternalEvent" - $ref: "#/components/schemas/LogMeInTranscriptEvent" - $ref: "#/components/schemas/PushEvent" - $ref: "#/components/schemas/ChatStartedEvent" - $ref: "#/components/schemas/ChatEndedEvent" - $ref: "#/components/schemas/SkillAssignedEvent" - $ref: "#/components/schemas/SurveyOfferedEvent" - $ref: "#/components/schemas/SurveyResponseSubmittedEvent" - $ref: "#/components/schemas/OfferedToEvent" - $ref: "#/components/schemas/RoutingChannelEvent" - $ref: "#/components/schemas/WebhookEvent" BaseEvent: type: object required: - id - type properties: id: type: integer readOnly: true description: Automatically assigned when the event is created type: type: string readOnly: true description: The type of event via: $ref: "#/components/schemas/ViaObject" description: Via object if different from the audit's via object CreateEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - Create readOnly: true field_name: type: string readOnly: true description: The name of the field that was set value: oneOf: - type: string - type: array items: {} - type: object readOnly: true description: The value of the field that was set ChangeEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - Change readOnly: true field_name: type: string readOnly: true description: The name of the field that was changed value: oneOf: - type: string - type: array items: {} - type: object readOnly: true description: The value of the field that was changed previous_value: oneOf: - type: string - type: array items: {} - type: object readOnly: true description: The previous value of the field that was changed CommentEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - Comment readOnly: true body: type: string readOnly: true description: The comment body html_body: type: string readOnly: true description: The comment formatted as HTML public: type: boolean readOnly: true description: Whether the comment is public trusted: type: boolean readOnly: true description: Whether the comment is trusted author_id: type: integer readOnly: true description: The comment author ID attachments: type: array items: $ref: "#/components/schemas/AttachmentObject" readOnly: true CommentRedactionEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - CommentRedactionEvent readOnly: true comment_id: type: integer readOnly: true description: The comment with the redacted text AttachmentRedactionEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - AttachmentRedactionEvent readOnly: true attachment_id: type: integer readOnly: true description: The redacted attachment comment_id: type: integer readOnly: true description: The comment with the redacted attachment VoiceCommentEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - VoiceComment readOnly: true data: type: object readOnly: true description: Properties describing the voice comment formatted_from: type: string readOnly: true description: A formatted version of the phone number which dialed the call formatted_to: type: string readOnly: true description: A formatted version of the phone number which answered the call body: type: string readOnly: true description: Comment added to the ticket html_body: type: string readOnly: true description: The comment formatted to HTML public: type: boolean readOnly: true description: If true, the ticket requester can see the comment trusted: type: boolean readOnly: true description: If this comment is trusted or marked as being potentially fraudulent author_id: type: integer readOnly: true description: The comment author, typically the agent assigned to the ticket transcription_visible: type: boolean readOnly: true description: Whether the transcription is visible on the ticket attachments: type: array items: $ref: "#/components/schemas/AttachmentObject" readOnly: true CommentPrivacyChangeEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - CommentPrivacyChange readOnly: true comment_id: type: integer readOnly: true description: The id of the comment that changed privacy public: type: boolean readOnly: true description: Tells if the comment was made public or private SuspendedTicketRecoveryEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - SuspendedTicketRecovery readOnly: true cause: type: string readOnly: true description: The details of the suspension cause_name: type: string readOnly: true description: The key of the cause of suspension cause_id: type: integer readOnly: true description: The id of the cause of suspension recovery_details: type: string readOnly: true description: The details of the recovery, including the recovery type and the recovery author's name recovery_type: type: string enum: - manual - automatic readOnly: true description: The type of recovery recovered_at: type: string format: date-time readOnly: true description: The date of recovery recovered_by: type: integer readOnly: true description: The user who performed the recovery NotificationEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - Notification readOnly: true subject: type: string readOnly: true description: The subject of the message sent to the recipients body: type: string readOnly: true description: The message sent to the recipients recipients: type: array items: type: integer readOnly: true description: An array of recipient IDs NotificationWithCcsEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - NotificationWithCcs readOnly: true subject: type: string readOnly: true description: The subject of the message sent to the recipients body: type: string readOnly: true description: The message sent to the recipients recipients: type: array items: type: integer readOnly: true description: An array of recipient IDs SmsNotificationEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - SmsNotification readOnly: true body: type: string readOnly: true description: The message sent to the recipients recipients: type: array items: type: integer readOnly: true description: An array of recipient IDs CcEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - Cc readOnly: true body: type: string readOnly: true description: The message sent to the recipients recipients: type: array items: type: integer readOnly: true description: An array of recipient IDs FollowerNotificationEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - FollowerNotificationEvent readOnly: true subject: type: string readOnly: true description: The subject of the message sent to the recipients body: type: string readOnly: true description: The message sent to the recipients recipients: type: array items: type: integer readOnly: true description: An array of recipient IDs FollowerChangeEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - FollowersChange readOnly: true previous_followers: type: array items: type: integer readOnly: true description: The previous followers on the ticket current_followers: type: array items: type: integer readOnly: true description: The current followers on the ticket EmailCcChangeEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - EmailCcChange readOnly: true previous_email_ccs: type: array items: type: string readOnly: true description: The previous email CCs on the ticket current_email_ccs: type: array items: type: string readOnly: true description: The current email CCs on the ticket MacroReferenceEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - MacroReference readOnly: true macro_id: type: integer readOnly: true description: The id of the macro this event refers to macro_title: type: string readOnly: true description: The title of the macro this event refers to macro_deleted: type: boolean readOnly: true description: Whether or not the macro this event refers to is deleted SatisfactionRatingEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - SatisfactionRating readOnly: true score: type: string enum: - offered - unoffered - good - bad readOnly: true description: The rating state assignee_id: type: integer readOnly: true description: Who the ticket was assigned to upon rating time body: type: string readOnly: true description: The users comment posted during rating TicketSharingEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - TicketSharingEvent readOnly: true agreement_id: type: integer readOnly: true description: The sharing agreement id action: type: string enum: - shared - unshared readOnly: true description: The sharing action OrganizationSubscriptionNotificationEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - OrganizationActivity readOnly: true subject: type: string readOnly: true description: The subject of the message sent to the recipients body: type: string readOnly: true description: The message sent to the recipients recipients: type: array items: type: integer readOnly: true description: An array of recipient IDs ErrorEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - Error readOnly: true message: type: string readOnly: true description: The error message TweetEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - Tweet readOnly: true direct_message: type: boolean readOnly: true description: Whether this tweet was a direct message body: type: string readOnly: true description: The body of the tweet recipients: type: array items: type: integer readOnly: true description: An array of recipient IDs FacebookEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - FacebookEvent readOnly: true page: type: object readOnly: true description: The name and graph id of the Facebook Page associated with the event communication: type: integer readOnly: true description: The Zendesk Support id of the associated communication ticket_via: type: string enum: - post - message readOnly: true description: Post or message depending on the association body: type: string readOnly: true description: The value of the message posted to Facebook FacebookCommentEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - FacebookComment readOnly: true data: type: object readOnly: true description: Properties of the Facebook comment body: type: string readOnly: true description: The actual comment made by the author html_body: type: string readOnly: true description: The actual comment made by the author formatted as HTML public: type: boolean readOnly: true description: If this is a public comment or an internal-agents-only note trusted: type: boolean readOnly: true description: If this comment is trusted or marked as being potentially fraudulent author_id: type: integer readOnly: true description: The id of the author of this comment graph_object_id: type: string readOnly: true description: The graph object id of the associated Facebook Wall post or message ExternalEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - External readOnly: true resource: type: string readOnly: true description: External target id body: type: string readOnly: true description: Trigger message for this target event LogMeInTranscriptEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - LogMeInTranscript readOnly: true body: type: string readOnly: true description: An audit of the transcript PushEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - Push readOnly: true value: type: string readOnly: true description: Data being pushed out of our system value_reference: type: string readOnly: true description: A reference to the destination of the data ChatStartedEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - ChatStartedEvent readOnly: true value: type: array items: {} readOnly: true description: Properties of the messaging conversation history: type: array items: {} readOnly: true description: Data about chat events webpath: type: array items: {} readOnly: true description: The webpath for the messaging conversation attachments: type: array items: $ref: "#/components/schemas/AttachmentObject" readOnly: true ChatEndedEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - ChatEndedEvent readOnly: true value: type: array items: {} readOnly: true description: Properties of the messaging conversation attachments: type: array items: $ref: "#/components/schemas/AttachmentObject" readOnly: true SkillAssignedEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - AssociateAttValsEvent readOnly: true attribute_values: type: array items: $ref: "#/components/schemas/AttributeValueObject" readOnly: true description: Skills assigned to the ticket SurveyOfferedEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - SurveyOffered readOnly: true assigned_user_id: type: integer nullable: true readOnly: true description: The id of the user assigned to the ticket at the time the survey was offered assigned_group_id: type: integer nullable: true readOnly: true description: The id of the group assigned to the ticket at the time the survey was offered survey_id: type: string readOnly: true description: A ULID representing the survey that was offered survey_type: type: string readOnly: true description: The type of the survey that was offered SurveyResponseSubmittedEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - SurveyResponseSubmitted readOnly: true assigned_user_id: type: integer nullable: true readOnly: true description: The id of the user assigned to the ticket at the time the survey response was submitted assigned_group_id: type: integer nullable: true readOnly: true description: The id of the group assigned to the ticket at the time the survey response was submitted survey_response_id: type: string readOnly: true description: A ULID representing the survey response that was submitted survey_type: type: string readOnly: true description: The type of the survey that was offered OfferedToEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - OfferedToEvent readOnly: true assignee: type: integer readOnly: true description: The id of the agent the ticket was offered to skills: type: array items: $ref: "#/components/schemas/AttributeValueObject" readOnly: true description: Skills used to route the ticket to an agent RoutingChannelEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - RoutingChannelEvent readOnly: true previous: type: string readOnly: true description: The previous routing channel current: type: string readOnly: true description: The current routing channel WebhookEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object properties: type: type: string enum: - WebhookEvent readOnly: true via: type: object readOnly: true description: How the webhook event was triggered properties: channel: type: string readOnly: true source: type: object readOnly: true properties: from: type: object readOnly: true properties: deleted: type: boolean readOnly: true title: type: string readOnly: true id: type: integer readOnly: true rel: type: string readOnly: true AttributeValueObject: type: object properties: id: type: string format: uuid description: Attribute value ID name: type: string description: Attribute value name attribute_id: type: string format: uuid description: The ID of the attribute (skill type) AuthorObject: type: object properties: email: type: string description: The author email readOnly: true id: type: integer description: The author id readOnly: true name: type: string description: The author name readOnly: true AutomationObject: type: object properties: actions: type: array description: An object describing what the automation will do. See [Actions reference](/documentation/ticketing/reference-guides/actions-reference) items: $ref: "#/components/schemas/ActionObject" active: type: boolean description: Whether the automation is active conditions: $ref: "#/components/schemas/ConditionsObject" created_at: type: string format: date-time description: The time the automation was created readOnly: true default: type: boolean description: If true, the automation is a default automation readOnly: true id: type: integer description: Automatically assigned when created readOnly: true position: type: integer description: The position of the automation which specifies the order it will be executed raw_title: type: string description: The raw title of the automation readOnly: true title: type: string description: The title of the automation updated_at: type: string format: date-time description: The time of the last update of the automation readOnly: true AutomationResponse: type: object properties: automation: $ref: "#/components/schemas/AutomationObject" AutomationsResponse: type: object properties: automations: type: array items: $ref: "#/components/schemas/AutomationObject" count: type: integer readOnly: true next_page: type: string nullable: true readOnly: true previous_page: type: string nullable: true readOnly: true BatchErrorItem: type: object allOf: - $ref: "#/components/schemas/Error" - type: object properties: trigger_id: type: string BatchJobRequest: type: object properties: job: type: object properties: action: type: string enum: - patch items: type: object properties: trigger_categories: type: array items: $ref: "#/components/schemas/TriggerCategoryBatchRequest" triggers: type: array items: $ref: "#/components/schemas/TriggerBatchRequest" BatchJobResponse: type: object properties: errors: type: array items: $ref: "#/components/schemas/BatchErrorItem" results: type: object properties: trigger_categories: type: array items: $ref: "#/components/schemas/TriggerCategory" triggers: type: array items: $ref: "#/components/schemas/TriggerObject" status: type: string enum: - complete - failed BookmarkCreateRequest: type: object properties: bookmark: $ref: "#/components/schemas/BookmarkInput" BookmarkInput: type: object properties: ticket_id: type: integer description: The id of the ticket the bookmark is for. BookmarkObject: title: Bookmarks type: object properties: created_at: type: string format: date-time description: The time the bookmark was created readOnly: true id: type: integer description: Automatically assigned when the bookmark is created readOnly: true ticket: type: object allOf: - $ref: "#/components/schemas/TicketObject" readOnly: true url: type: string description: The API url of this bookmark readOnly: true BookmarkResponse: type: object properties: bookmark: $ref: "#/components/schemas/BookmarkObject" BookmarksResponse: title: Bookmarks type: object allOf: - $ref: "#/components/schemas/OffsetPaginationObject" - type: object properties: bookmarks: type: array items: $ref: "#/components/schemas/BookmarkObject" BrandAgentObject: type: object properties: brand_id: type: integer description: The id of a brand created_at: type: string format: date-time description: The time the brand membership was created readOnly: true id: type: string description: Automatically assigned upon creation readOnly: true updated_at: type: string format: date-time description: The time of the last update of the brand membership readOnly: true url: type: string description: The API url of this record readOnly: true user_id: type: integer description: The id of an agent required: - user_id - brand_id BrandAgentResponse: type: object properties: brand_agent: $ref: "#/components/schemas/BrandAgentObject" BrandAgentsResponse: type: object properties: brand_agents: type: array items: $ref: "#/components/schemas/BrandAgentObject" BrandCreateRequest: type: object properties: brand: $ref: "#/components/schemas/BrandObject" BrandObject: title: Brands type: object properties: active: type: boolean description: If the brand is set as active brand_url: type: string description: The url of the brand created_at: type: string format: date-time description: The time the brand was created readOnly: true default: type: boolean description: Is the brand the default brand for this account has_help_center: type: boolean description: If the brand has a Help Center help_center_state: type: string description: The state of the Help Center enum: - enabled - disabled - restricted readOnly: true host_mapping: type: string description: The hostmapping to this brand, if any. Only admins view this property. id: type: integer description: The ID automatically assigned when the brand is created readOnly: true is_deleted: type: boolean description: If the brand object is deleted or not logo: $ref: "#/components/schemas/AttachmentObject" name: type: string description: The name of the brand signature_template: type: string description: The signature template for a brand subdomain: type: string description: The subdomain of the brand ticket_form_ids: type: array description: The ids of ticket forms that are available for use by a brand items: type: integer readOnly: true updated_at: type: string format: date-time description: The time of the last update of the brand readOnly: true url: type: string description: The API url of this brand readOnly: true required: - name - subdomain BrandResponse: type: object properties: brand: $ref: "#/components/schemas/BrandObject" BrandUpdateRequest: type: object properties: brand: $ref: "#/components/schemas/BrandObject" BrandsResponse: title: Brands type: object allOf: - $ref: "#/components/schemas/OffsetPaginationObject" - type: object properties: brands: type: array description: Array of brands items: $ref: "#/components/schemas/BrandObject" BulkSkillBasedRoutingAttributeValueJob: type: object properties: action: type: string description: 'The action to perform on the attribute values. One of the following: "upsert", "update", "delete"' readOnly: true attributes: type: object description: The attribute values to update. See [Attribute Values](#attribute-values) properties: attribute_values: type: array items: $ref: "#/components/schemas/SkillBasedRoutingAttributeValueObject" items: type: array description: The list of agent ids items: type: integer readOnly: true required: - action - items - attributes BulkSkillBasedRoutingAttributeValuesRequest: title: Bulk Skill Based Routing Attribute Values Job type: object properties: job: $ref: "#/components/schemas/BulkSkillBasedRoutingAttributeValueJob" BulkUpdateDefaultCustomStatusRequest: type: object properties: ids: type: string description: The comma-separated list of custom ticket status ids to be set as default for their status categories BulkUpdateDefaultCustomStatusResponse: type: object ChannelFrameworkPushResultsResponse: type: object properties: results: type: array description: An array of [result objects](#result-object) items: $ref: "#/components/schemas/ChannelFrameworkResultObject" ChannelFrameworkResultObject: type: object properties: external_resource_id: type: string description: The external ID of the resource, as passed in readOnly: true status: $ref: "#/components/schemas/ChannelFrameworkResultStatusObject" ChannelFrameworkResultStatusObject: type: object description: The status of the import for the indicated resource properties: code: type: string description: A code indicating the status of the import of the resource, as described in [status codes](#status-codes) readOnly: true description: type: string description: In the case of an exception, a description of the exception. Otherwise, not present. readOnly: true CollaboratorObject: type: object properties: email: type: string format: email name: type: string ComplianceDeletionStatusObject: type: object properties: account_subdomain: type: string action: type: string application: type: string created_at: type: string executer_id: type: integer nullable: true user_id: type: integer required: - action - application - account_subdomain - executer_id - user_id - created_at ComplianceDeletionStatusesResponse: type: object properties: compliance_deletion_statuses: type: array items: $ref: "#/components/schemas/ComplianceDeletionStatusObject" ConditionObject: type: object properties: field: type: string description: The name of a ticket field operator: type: string description: A comparison operator value: type: string description: The value of a ticket field ConditionsObject: type: object description: An object that describes the conditions under which the automation will execute. See [Conditions reference](/documentation/ticketing/reference-guides/conditions-reference) properties: all: type: array description: Logical AND. Tickets must fulfill all of the conditions to be considered matching items: $ref: "#/components/schemas/ConditionObject" any: type: array description: Logical OR. Tickets may satisfy any of the conditions to be considered matching items: $ref: "#/components/schemas/ConditionObject" ConversationLogObject: type: object properties: attachments: type: array description: A collection of attachments (image or file) associated with the event readOnly: true items: $ref: "#/components/schemas/AttachmentObject" author: type: object description: Object that describes the user who created the event properties: type: type: string description: Either user, agent, or bot enum: - user - agent - bot readOnly: true zen:sunco:user_id: type: string description: A Zendesk resource name prefix describing a messaging user readOnly: true zen:support:user_id: type: integer description: A Zendesk resource name prefix describing a Support user readOnly: true additionalProperties: true content: type: object description: Object that describes the content of the message. The inner fields depends on the record type additionalProperties: true readOnly: true created_at: type: string format: date-time description: The timestamp of when this record was created readOnly: true id: type: string description: Unique record identifier readOnly: true metadata: type: object description: Various additional data that further describes this record additionalProperties: true readOnly: true reference: type: string description: "A Zendesk resource name value that uniquely identifies this record. Example: `zen:ticket_event:`" readOnly: true type: type: string description: "The type of record, representing one of the conversational ticket events. Examples: `Comment` or `Messaging::ConversationMessage`" readOnly: true additionalProperties: true required: - id - type - reference - created_at - author - content - metadata - attachments ConversationLogResponse: type: object properties: events: type: array items: $ref: "#/components/schemas/ConversationLogObject" links: type: object properties: next: type: string prev: type: string meta: type: object properties: after_cursor: type: string before_cursor: type: string has_more: type: boolean CountOrganizationObject: type: object properties: refreshed_at: type: string readOnly: true value: type: integer readOnly: true CountOrganizationResponse: type: object properties: count: $ref: "#/components/schemas/CountOrganizationObject" CountResponse: type: object properties: count: type: object properties: refreshed_at: type: string format: datetime value: type: integer CreateOrganizationRequest: type: object properties: organization: $ref: "#/components/schemas/OrganizationObject" required: - organization CreateResourceResult: type: object properties: id: type: integer description: the id of the new resource index: type: integer description: the index number of the resul required: - id - index CurrentUserResponse: type: object properties: user: allOf: - $ref: "#/components/schemas/UserObject" - type: object properties: authenticity_token: type: string description: CSRF token required by some Zendesk APIs. readOnly: true CursorBasedExportIncrementalTicketsResponse: type: object description: "See [Tickets](/api-reference/ticketing/tickets/tickets/) for a detailed example. " properties: after_cursor: type: string nullable: true after_url: type: string nullable: true before_cursor: type: string nullable: true before_url: type: string nullable: true end_of_stream: type: boolean tickets: type: array items: $ref: "#/components/schemas/TicketObject" CursorBasedExportIncrementalUsersResponse: type: object properties: after_cursor: type: string nullable: true after_url: type: string nullable: true before_cursor: type: string nullable: true before_url: type: string nullable: true end_of_stream: type: boolean users: type: array items: $ref: "#/components/schemas/UserObject" CustomFieldObject: type: object properties: active: type: boolean description: If true, this field is available for use created_at: type: string format: date-time description: The time of the last update of the ticket field readOnly: true custom_field_options: type: array description: Required and presented for a custom field of type "dropdown". Each option is represented by an object with a `name` and `value` property items: $ref: "#/components/schemas/CustomFieldOptionObject" description: type: string description: User-defined description of this field's purpose id: type: integer description: Automatically assigned upon creation readOnly: true key: type: string description: A unique key that identifies this custom field. This is used for updating the field and referencing in placeholders. The key must consist of only letters, numbers, and underscores. It can't be only numbers position: type: integer description: Ordering of the field relative to other fields raw_description: type: string description: The dynamic content placeholder, if present, or the `description` value, if not. See [Dynamic Content Items](/api-reference/ticketing/ticket-management/dynamic_content/) raw_title: type: string description: The dynamic content placeholder, if present, or the `title` value, if not. See [Dynamic Content Items](/api-reference/ticketing/ticket-management/dynamic_content/) regexp_for_validation: type: string description: Regular expression field only. The validation pattern for a field value to be deemed valid nullable: true relationship_filter: type: object description: A filter definition that allows your autocomplete to filter down results relationship_target_type: type: string description: A representation of what type of object the field references. Options are "zen:user", "zen:organization", "zen:ticket", and "zen:custom_object:{key}" where key is a custom object key. For example "zen:custom_object:apartment". system: type: boolean description: If true, only active and position values of this field can be changed readOnly: true tag: type: string description: Optional for custom field of type "checkbox"; not presented otherwise. title: type: string description: The title of the custom field type: type: string description: 'The custom field type: "checkbox", "date", "decimal", "dropdown", "integer", ["lookup"](/api-reference/ticketing/lookup_relationships/lookup_relationships/), "multiselect", "regexp", "text", or "textarea"' updated_at: type: string format: date-time description: The time of the last update of the ticket field readOnly: true url: type: string description: The URL for this resource readOnly: true required: - key - type - title CustomFieldOptionObject: type: object properties: id: type: integer description: Automatically assigned upon creation readOnly: true name: type: string description: Name of the dropdown option position: type: integer description: Position of the dropdown option raw_name: type: string description: Raw name of the dropdown option readOnly: true url: type: string description: URL of the dropdown option readOnly: true value: type: string description: Value of the dropdown option required: - name - value CustomFieldOptionResponse: type: object properties: custom_field_option: $ref: "#/components/schemas/CustomFieldOptionObject" CustomFieldOptionsResponse: type: object properties: count: type: integer description: Total count of records retrieved readOnly: true custom_field_options: type: array items: $ref: "#/components/schemas/CustomFieldOptionObject" next_page: type: string description: URL of the next page nullable: true readOnly: true previous_page: type: string description: URL of the previous page nullable: true readOnly: true CustomObject: type: object properties: allows_photos: type: boolean description: If true, photos can be uploaded to the records of the object. If false, new photos cannot be uploaded but existing photos can still be viewed and removed created_at: type: string format: date-time description: The time the object type was created readOnly: true created_by_user_id: type: string description: Id of a user who created the object readOnly: true description: type: string description: User-defined description of the object include_in_list_view: type: boolean description: A flag setting the visibility of the object in the agent's list view. If true, all agents and admins have viewing access to the object in the Custom objects record page in the Agent Workspace. If false, only admins have viewing access key: type: string description: A user-defined unique identifier. Writable on create only readOnly: true raw_description: type: string description: The dynamic content placeholder, if present, or the "raw_description" value, if not. See [Dynamic Content Items](/api-reference/ticketing/ticket-management/dynamic_content/) raw_title: type: string description: The dynamic content placeholder, if present, or the "title" value, if not. See [Dynamic Content Items](/api-reference/ticketing/ticket-management/dynamic_content/) raw_title_pluralized: type: string description: The dynamic content placeholder, if present, or the "raw_title_pluralized" value, if not. See [Dynamic Content Items](/api-reference/ticketing/ticket-management/dynamic_content/) title: type: string description: User-defined display name for the object title_pluralized: type: string description: User-defined pluralized version of the object's title updated_at: type: string format: date-time description: The time of the last update of the object readOnly: true updated_by_user_id: type: string description: Id of the last user who updated the object readOnly: true url: type: string description: Direct link to the specific custom object readOnly: true required: - key - title - title_pluralized - include_in_list_view CustomObjectCreateInput: type: object properties: key: type: string description: Unique identifier. Writable on create only title: type: string description: Display name for the object title_pluralized: type: string description: Pluralized version of the object's title CustomObjectField: type: object allOf: - $ref: "#/components/schemas/CustomFieldObject" properties: properties: $ref: "#/components/schemas/CustomObjectFieldPropertiesObject" CustomObjectFieldPropertiesObject: type: object description: A set of properties which describe the standard::name field's autonumbering and uniqueness behavior. Autonumbering and uniqueness can't be used together properties: autoincrement_enabled: type: boolean description: Turns autonumbering on or off autoincrement_next_sequence: type: integer description: The next number in the autonumbering sequence. It can't be negative or less than the current autonumbering value autoincrement_padding: type: integer description: Sets the number of digits for autogenerated numbers. Valid values are 0-9 autoincrement_prefix: type: string description: A prefix to autogenerated numbers that can't exceed 30 characters is_unique: type: boolean description: Turns uniqueness on or off CustomObjectFieldResponse: type: object properties: custom_object_field: $ref: "#/components/schemas/CustomObjectField" CustomObjectFieldsCreateRequest: type: object properties: custom_object_field: $ref: "#/components/schemas/CustomObjectField" CustomObjectFieldsResponse: type: object properties: custom_object_fields: type: array items: $ref: "#/components/schemas/CustomObjectField" CustomObjectLimitsResponse: type: object properties: count: type: integer description: The current numnber of the requested resource readOnly: true limit: type: integer description: The maximum allowed number for the requested resource readOnly: true CustomObjectRecord: type: object properties: created_at: type: string format: date-time description: The time the object was created readOnly: true created_by_user_id: type: string description: Id of a user who created the object readOnly: true custom_object_fields: type: object additionalProperties: true custom_object_key: type: string description: A user-defined unique identifier readOnly: true external_id: type: string description: An id you can use to link custom object records to external data nullable: true id: type: string description: Automatically assigned upon creation readOnly: true name: type: string description: User-defined display name for the object. If autonumbering is selected for the custom object's name field, the name isn't allowed because it's automatically generated. If uniqueness is enabled, the name must be unique. readOnly: true photo: type: object description: The record photo represented as an [Attachment](/api-reference/ticketing/tickets/ticket-attachments/). The `allows_photos` property must be set to `true` for the object additionalProperties: true nullable: true updated_at: type: string format: date-time description: The time of the last update of the object readOnly: true updated_by_user_id: type: string description: Id of the last user who updated the object readOnly: true url: type: string description: Direct link to the specific custom object readOnly: true required: - name CustomObjectRecordFilteredSearchCondition: type: object properties: field_key: type: object properties: operator: type: string value: oneOf: - type: string - type: integer - type: array items: oneOf: - type: string - type: integer nullable: true additionalProperties: true CustomObjectRecordResponse: type: object properties: custom_object_record: $ref: "#/components/schemas/CustomObjectRecord" CustomObjectRecordsBulkCreateRequest: type: object properties: job: type: object properties: action: type: string items: type: array description: An array of record objects for job actions that create, update, or set. An array of strings for job actions that delete. items: $ref: "#/components/schemas/CustomObjectRecord" CustomObjectRecordsCreateRequest: type: object properties: custom_object_record: $ref: "#/components/schemas/CustomObjectRecord" CustomObjectRecordsFilteredSearchRequestBasic: type: object properties: filter: $ref: "#/components/schemas/CustomObjectRecordFilteredSearchCondition" CustomObjectRecordsFilteredSearchRequestComplex: type: object properties: filter: type: object properties: $and: type: array items: $ref: "#/components/schemas/CustomObjectRecordFilteredSearchCondition" $or: type: array items: $ref: "#/components/schemas/CustomObjectRecordFilteredSearchCondition" CustomObjectRecordsJobsResponse: type: object properties: job_status: type: object properties: id: type: string message: type: string nullable: true progress: type: integer nullable: true results: type: array items: $ref: "#/components/schemas/CustomObjectRecord" nullable: true status: type: string total: type: integer url: type: string CustomObjectRecordsResponse: type: object properties: count: type: integer description: The number of results returned for the current request readOnly: true custom_object_records: type: array items: $ref: "#/components/schemas/CustomObjectRecord" links: type: object properties: next: type: string nullable: true prev: type: string nullable: true required: - prev - next meta: type: object properties: after_cursor: type: string nullable: true before_cursor: type: string nullable: true has_more: type: boolean required: - has_more - after_cursor - before_cursor CustomObjectRecordsUpsertRequest: type: object properties: custom_object_record: $ref: "#/components/schemas/CustomObjectRecord" CustomObjectResponse: type: object properties: custom_object: $ref: "#/components/schemas/CustomObject" CustomObjectsCreateRequest: type: object properties: custom_object: $ref: "#/components/schemas/CustomObjectCreateInput" CustomObjectsResponse: type: object properties: custom_objects: type: array items: $ref: "#/components/schemas/CustomObject" CustomRoleConfigurationObject: type: object description: Configuration settings for the role. See [Configuration](#configuration) properties: assign_tickets_to_any_group: type: boolean description: Whether or not the agent can assign tickets to any group readOnly: true chat_access: type: boolean description: Whether or not the agent has access to Chat readOnly: true end_user_list_access: type: string description: 'Whether or not the agent can view lists of user profiles. Allowed values: "full", "none"' end_user_profile_access: type: string description: 'What the agent can do with end-user profiles. Allowed values: "edit", "edit-within-org", "full", "readonly"' explore_access: type: string description: 'Allowed values: "edit", "full", "none", "readonly"' forum_access: type: string description: 'The kind of access the agent has to Guide. Allowed values: "edit-topics", "full", "readonly"' forum_access_restricted_content: type: boolean group_access: type: boolean description: Whether or not the agent can add or modify groups readOnly: true light_agent: type: boolean readOnly: true macro_access: type: string description: 'What the agent can do with macros. Allowed values: "full", "manage-group", "manage-personal", "readonly"' manage_business_rules: type: boolean description: Whether or not the agent can manage business rules manage_contextual_workspaces: type: boolean description: Whether or not the agent can view, add, and edit contextual workspaces manage_dynamic_content: type: boolean description: Whether or not the agent can access dynamic content manage_extensions_and_channels: type: boolean description: Whether or not the agent can manage channels and extensions manage_facebook: type: boolean description: Whether or not the agent can manage Facebook pages manage_organization_fields: type: boolean description: Whether or not the agent can create and manage organization fields manage_ticket_fields: type: boolean description: Whether or not the agent can create and manage ticket fields manage_ticket_forms: type: boolean description: Whether or not the agent can create and manage ticket forms manage_user_fields: type: boolean description: Whether or not the agent can create and manage user fields moderate_forums: type: boolean readOnly: true organization_editing: type: boolean description: Whether or not the agent can add or modify organizations organization_notes_editing: type: boolean description: Whether or not the agent can add or modify organization notes readOnly: true report_access: type: string description: 'What the agent can do with reports. Allowed values: "full", "none", "readonly"' side_conversation_create: type: boolean description: Whether or not the agent can contribute to side conversations ticket_access: type: string description: 'What kind of tickets the agent can access. Allowed values: "all", "assigned-only", "within-groups", "within-groups-and-public-groups", "within-organization"' ticket_comment_access: type: string description: 'What type of comments the agent can make. Allowed values: "public", "none"' ticket_deletion: type: boolean description: Whether or not the agent can delete tickets ticket_editing: type: boolean description: Whether or not the agent can edit ticket properties ticket_merge: type: boolean description: Whether or not the agent can merge tickets ticket_tag_editing: type: boolean description: Whether or not the agent can edit ticket tags twitter_search_access: type: boolean user_view_access: type: string description: 'What the agent can do with customer lists. Allowed values: "full", "manage-group", "manage-personal", "none", "readonly"' view_access: type: string description: 'What the agent can do with views. Allowed values: "full", "manage-group", "manage-personal", "playonly", "readonly"' view_deleted_tickets: type: boolean description: Whether or not the agent can view deleted tickets voice_access: type: boolean description: Whether or not the agent can answer and place calls to end users voice_dashboard_access: type: boolean description: Whether or not the agent can view details about calls on the Talk dashboard CustomRoleObject: title: Custom Agent Roles type: object properties: configuration: $ref: "#/components/schemas/CustomRoleConfigurationObject" created_at: type: string format: date-time description: The time the record was created readOnly: true description: type: string description: A description of the role id: type: integer description: Automatically assigned on creation readOnly: true name: type: string description: Name of the custom role role_type: type: integer description: The user's role. 0 stands for a custom agent, 1 for a light agent, 2 for a chat agent, 3 for a contributor, 4 for an admin and 5 for a billing admin. See [Understanding standard agent roles in Zendesk Support](https://support.zendesk.com/hc/en-us/articles/4409155971354-Understanding-standard-agent-roles-in-Zendesk-Support) in Zendesk help readOnly: true team_member_count: type: integer description: The number of team members assigned to this role readOnly: true updated_at: type: string format: date-time description: The time the record was last updated readOnly: true required: - name - role_type CustomRoleResponse: type: object properties: custom_role: $ref: "#/components/schemas/CustomRoleObject" CustomRolesResponse: type: object properties: custom_roles: type: array items: $ref: "#/components/schemas/CustomRoleObject" CustomStatusCreateInput: type: object allOf: - $ref: "#/components/schemas/CustomStatusUpdateInput" - type: object properties: status_category: type: string description: The status category the custom ticket status belongs to enum: - new - open - pending - hold - solved CustomStatusCreateRequest: type: object properties: custom_status: $ref: "#/components/schemas/CustomStatusCreateInput" CustomStatusObject: type: object properties: active: type: boolean description: If true, the custom status is set to active, If false, the custom status is set to inactive agent_label: type: string description: The label displayed to agents. Maximum length is 48 characters created_at: type: string format: date-time description: The date and time the custom ticket status was created readOnly: true default: type: boolean description: If true, the custom status is set to default. If false, the custom status is set to non-default description: type: string description: The description of when the user should select this custom ticket status end_user_description: type: string description: The description displayed to end users end_user_label: type: string description: The label displayed to end users. Maximum length is 48 characters id: type: integer description: Automatically assigned when the custom ticket status is created readOnly: true raw_agent_label: type: string description: The dynamic content placeholder. If the dynamic content placeholder is not available, this is the "agent_label" value. See [Dynamic Content Items](/api-reference/ticketing/ticket-management/dynamic_content/) readOnly: true raw_description: type: string description: The dynamic content placeholder. If the dynamic content placeholder is not available, this is the "description" value. [Dynamic Content Items](/api-reference/ticketing/ticket-management/dynamic_content/) readOnly: true raw_end_user_description: type: string description: The dynamic content placeholder. If the dynamic content placeholder is not available, this is the "end_user_description" value. See [Dynamic Content Items](/api-reference/ticketing/ticket-management/dynamic_content/) readOnly: true raw_end_user_label: type: string description: The dynamic content placeholder. If the dynamic content placeholder is not available, this is the "end_user_label" value. See [Dynamic Content Items](/api-reference/ticketing/ticket-management/dynamic_content/) readOnly: true status_category: type: string description: The status category the custom ticket status belongs to enum: - new - open - pending - hold - solved updated_at: type: string format: date-time description: The date and time the custom ticket status was last updated readOnly: true required: - status_category - agent_label CustomStatusResponse: type: object properties: custom_status: $ref: "#/components/schemas/CustomStatusObject" CustomStatusUpdateInput: type: object properties: active: type: boolean description: True if the custom status is set as active; inactive if false agent_label: type: string description: The dynamic content placeholder, if present, or the "agent_label" value, if not. See [Dynamic Content Items](/api-reference/ticketing/ticket-management/dynamic_content/) description: type: string description: The dynamic content placeholder, if present, or the "description" value, if not. See [Dynamic Content Items](/api-reference/ticketing/ticket-management/dynamic_content/) end_user_description: type: string description: The dynamic content placeholder, if present, or the "end_user_description" value, if not. See [Dynamic Content Items](/api-reference/ticketing/ticket-management/dynamic_content/) end_user_label: type: string description: The dynamic content placeholder, if present, or the "end_user_label" value, if not. See [Dynamic Content Items](/api-reference/ticketing/ticket-management/dynamic_content/) CustomStatusUpdateRequest: type: object properties: custom_status: $ref: "#/components/schemas/CustomStatusUpdateInput" CustomStatusesResponse: type: object properties: custom_statuses: type: array items: $ref: "#/components/schemas/CustomStatusObject" DefinitionsResponse: type: object properties: definitions: type: object properties: conditions_all: type: array items: type: object properties: group: type: string nullable: type: boolean operators: type: array items: type: object properties: terminal: type: boolean title: type: string value: type: string repeatable: type: boolean subject: type: string title: type: string type: type: string values: type: array items: type: object properties: enabled: type: boolean title: type: string value: type: string conditions_any: type: array items: type: object properties: group: type: string nullable: type: boolean operators: type: array items: type: object properties: terminal: type: boolean title: type: string value: type: string repeatable: type: boolean subject: type: string title: type: string type: type: string values: type: array items: type: object properties: enabled: type: boolean title: type: string value: type: string DeletedUserObject: type: object properties: active: type: boolean created_at: type: string email: type: string id: type: integer locale: type: string locale_id: type: integer name: type: string organization_id: type: integer phone: type: string nullable: true photo: type: object nullable: true role: type: string shared_phone_number: type: string nullable: true time_zone: type: string updated_at: type: string url: type: string required: - id - url - name - email - created_at - updated_at - time_zone - phone - shared_phone_number - photo - locale_id - locale - organization_id - role - active DeletedUserResponse: type: object properties: deleted_user: $ref: "#/components/schemas/DeletedUserObject" DeletedUsersResponse: type: object properties: deleted_users: type: array items: $ref: "#/components/schemas/DeletedUserObject" DeletionSchedule: type: object properties: active: type: boolean description: Whether the deletion schedule is active conditions: $ref: "#/components/schemas/ConditionsObject" created_at: type: string format: date-time description: The time the deletion schedule was created readOnly: true default: type: boolean description: Whether the deletion schedule is the default readOnly: true description: type: string description: The description of the deletion schedule id: type: integer description: The id of the deletion schedule readOnly: true title: type: string description: The title of the deletion schedule updated_at: type: string format: date-time description: The time the deletion schedule was last updated readOnly: true url: type: string description: Url for obtaining the deletion schedule JSON readOnly: true DynamicContentObject: title: Dynamic Content Items type: object properties: created_at: type: string format: date-time description: When this record was created readOnly: true default_locale_id: type: integer description: The default locale for the item. Must be one of the [locales the account has active](/api-reference/ticketing/account-configuration/locales/#list-locales). id: type: integer description: Automatically assigned when creating items readOnly: true name: type: string description: The unique name of the item outdated: type: boolean description: Indicates the item has outdated variants within it readOnly: true placeholder: type: string description: Automatically generated placeholder for the item, derived from name readOnly: true updated_at: type: string format: date-time description: When this record was last updated readOnly: true url: type: string description: The API url of this item readOnly: true variants: type: array description: All variants within this item. See [Dynamic Content Item Variants](/api-reference/ticketing/ticket-management/dynamic_content_item_variants/) items: $ref: "#/components/schemas/DynamicContentVariantObject" required: - name - default_locale_id - variants DynamicContentResponse: type: object properties: item: $ref: "#/components/schemas/DynamicContentObject" DynamicContentVariantObject: type: object properties: active: type: boolean description: If the variant is active and useable content: type: string description: The content of the variant created_at: type: string format: date-time description: When the variant was created readOnly: true default: type: boolean description: If the variant is the default for the item it belongs to id: type: integer description: Automatically assigned when the variant is created readOnly: true locale_id: type: integer description: An active locale outdated: type: boolean description: If the variant is outdated readOnly: true updated_at: type: string format: date-time description: When the variant was last updated readOnly: true url: type: string description: The API url of the variant readOnly: true required: - content - locale_id DynamicContentVariantResponse: type: object properties: variant: $ref: "#/components/schemas/DynamicContentVariantObject" DynamicContentVariantsResponse: type: object properties: variants: type: array items: $ref: "#/components/schemas/DynamicContentVariantObject" DynamicContentsResponse: type: object properties: items: type: array items: $ref: "#/components/schemas/DynamicContentObject" EmailCCObject: type: object allOf: - $ref: "#/components/schemas/FollowerObject" - type: object properties: action: type: string enum: - put - delete user_email: type: string user_id: type: string user_name: type: string EmailNotificationObject: type: object properties: comment_id: type: integer description: The comment ID associated to this email notification readOnly: true created_at: type: string format: date-time description: When this email notification was created readOnly: true email_id: type: string description: The email ID of this email notification readOnly: true message_id: type: string description: The value of the Message-Id header of the email readOnly: true notification_id: type: integer description: The notification id of this email notification readOnly: true recipients: type: array description: The list of recipients associated to this email notification items: $ref: "#/components/schemas/RecipientObject" readOnly: true ticket_id: type: integer description: The ticket ID associated to this email notification readOnly: true updated_at: type: string format: date-time description: When this email notification was last updated readOnly: true url: type: string description: The API url of this email notification readOnly: true EmailNotificationResponse: type: object properties: email_notification: $ref: "#/components/schemas/EmailNotificationObject" EmailNotificationsResponse: type: object properties: email_notifications: type: array items: $ref: "#/components/schemas/EmailNotificationObject" Error: type: object properties: code: type: string detail: type: string id: type: string links: type: object source: type: object status: type: string title: type: string required: - code - title Errors: type: object properties: errors: type: array items: $ref: "#/components/schemas/Error" EssentialsCardObject: type: object properties: created_at: type: string format: date-time description: Date and time the essentials card were created readOnly: true default: type: boolean description: If true, the system has used the first twenty fields for the custom object type as the essentials card. readOnly: true fields: type: array description: Fields that are displayed in the essentials card details. The order is defined by the order of the fields in the array items: type: object additionalProperties: true id: type: string description: "id of the essentials card " nullable: true readOnly: true key: type: string description: "Object type. Example: `zen:user` refers to `User` type " readOnly: true layout: type: string description: "layout type " readOnly: true max_count: type: integer description: Maximum number of fields allowed in the essentials card readOnly: true updated_at: type: string format: date-time description: Date and time the essentials card were last updated readOnly: true required: - fields EssentialsCardResponse: type: object properties: object_layout: $ref: "#/components/schemas/EssentialsCardObject" EssentialsCardsResponse: type: object properties: object_layouts: type: array items: $ref: "#/components/schemas/EssentialsCardObject" ExportIncrementalOrganizationsResponse: type: object properties: count: type: integer end_of_stream: type: boolean end_time: type: integer next_page: type: string nullable: true organizations: type: array items: $ref: "#/components/schemas/OrganizationObject" ExportIncrementalTicketEventsResponse: type: object properties: count: type: integer end_of_stream: type: boolean end_time: type: integer next_page: type: string nullable: true ticket_events: type: array items: $ref: "#/components/schemas/TicketMetricEventBaseObject" FailedResult: type: object properties: action: type: string description: 'The action the job attempted (`"action": "update"`)' details: type: string description: The details of the error error: type: string description: The error message id: type: integer description: The id of the resource the job attempted to update success: type: boolean description: 'Whether the action was successful or not (`"success": true`)' required: - id - action - error - success - details FollowerObject: type: object properties: action: type: string enum: - put - delete user_email: type: string format: email user_id: type: string GlobalClientObject: title: Global OAuth Clients type: object properties: company: type: string description: The company that users are asked to approve access to readOnly: true description: type: string description: A short description of the client readOnly: true id: type: integer description: Automatically assigned when the client is created readOnly: true identifier: type: string description: The unique identifier for the client readOnly: true logo_url: type: string description: The API logo url of this record readOnly: true name: type: string description: The name of the client readOnly: true GlobalClientsResponse: type: object properties: global_clients: type: array items: $ref: "#/components/schemas/GlobalClientObject" GroupMembershipObject: type: object properties: created_at: type: string format: date-time description: The time the group was created readOnly: true default: type: boolean description: If true, tickets assigned directly to the agent will assume this membership's group group_id: type: integer description: The id of a group id: type: integer description: Automatically assigned upon creation readOnly: true updated_at: type: string format: date-time description: The time of the last update of the group readOnly: true url: type: string description: The API url of this record readOnly: true user_id: type: integer description: The id of an agent required: - user_id - group_id GroupMembershipResponse: type: object properties: group_membership: $ref: "#/components/schemas/GroupMembershipObject" GroupMembershipsResponse: type: object properties: group_memberships: type: array items: $ref: "#/components/schemas/GroupMembershipObject" GroupObject: type: object properties: created_at: type: string format: date-time description: The time the group was created readOnly: true default: type: boolean description: If the group is the default one for the account readOnly: true deleted: type: boolean description: Deleted groups get marked as such readOnly: true description: type: string description: The description of the group id: type: integer description: Automatically assigned when creating groups readOnly: true is_public: type: boolean description: | If true, the group is public. If false, the group is private. You can't change a private group to a public group name: type: string description: The name of the group updated_at: type: string format: date-time description: The time of the last update of the group readOnly: true url: type: string description: The API url of the group readOnly: true required: - name GroupResponse: type: object properties: group: $ref: "#/components/schemas/GroupObject" GroupSLAPoliciesResponse: type: object properties: count: type: integer readOnly: true group_sla_policies: type: array items: $ref: "#/components/schemas/GroupSLAPolicyObject" next_page: type: string nullable: true readOnly: true previous_page: type: string nullable: true readOnly: true GroupSLAPolicyFilterConditionObject: type: object properties: field: type: string description: The name of a ticket field operator: type: string description: A comparison operator value: type: array description: The value of a ticket field items: oneOf: - type: string - type: integer GroupSLAPolicyFilterDefinitionResponse: type: object properties: definitions: type: object properties: all: type: array items: type: object properties: group: type: string operators: type: array items: type: object properties: title: type: string value: type: string title: type: string value: type: string values: type: object properties: list: type: array items: type: object properties: title: type: string value: type: integer nullable: true type: type: string GroupSLAPolicyFilterObject: type: object description: An object that describes the conditions a ticket must match for a Group SLA policy to be applied to the ticket. See [Filter](#filter). properties: all: type: array items: $ref: "#/components/schemas/GroupSLAPolicyFilterConditionObject" GroupSLAPolicyMetricObject: type: object properties: business_hours: type: boolean description: Whether the metric targets are being measured in business hours or calendar hours metric: type: string description: The definition of the time that is being measured priority: type: string description: Priority that a ticket must match target: type: integer description: The time within which the end-state for a metric should be met GroupSLAPolicyObject: type: object properties: created_at: type: string format: date-time description: The time the Group SLA policy was created readOnly: true description: type: string description: The description of the Group SLA policy filter: $ref: "#/components/schemas/GroupSLAPolicyFilterObject" id: type: string description: Automatically assigned when created readOnly: true policy_metrics: type: array description: Array of [policy metric](#policy-metric) objects items: $ref: "#/components/schemas/GroupSLAPolicyMetricObject" position: type: integer description: Position of the Group SLA policy. This position determines the order in which policies are matched to tickets. If not specified, the Group SLA policy is added at the last position title: type: string description: The title of the Group SLA policy updated_at: type: string format: date-time description: The time of the last update of the Group SLA policy readOnly: true url: type: string description: URL of the Group SLA policy record readOnly: true required: - title - filter GroupSLAPolicyResponse: type: object properties: group_sla_policy: $ref: "#/components/schemas/GroupSLAPolicyObject" GroupsCountObject: type: object properties: count: type: object properties: refreshed_at: type: string format: date-time description: Timestamp that indicates when the count was last updated readOnly: true value: type: integer description: Approximate count of groups readOnly: true GroupsResponse: type: object properties: groups: type: array items: $ref: "#/components/schemas/GroupObject" HostMappingObject: title: Host Mapping type: object properties: cname: type: string description: The canonical name record for a host mapping expected_cnames: type: array description: Array of expected CNAME records for host mapping(s) of a given brand items: type: string is_valid: type: boolean description: Whether a host mapping is valid or not for a given brand reason: type: string description: Reason why a host mapping is valid or not IncrementalSkillBasedRouting: title: Incremental Skill-based Routing type: object properties: attribute_values: type: array description: Routing attribute values items: $ref: "#/components/schemas/IncrementalSkillBasedRoutingAttributeValue" attributes: type: array description: Routing attributes items: $ref: "#/components/schemas/IncrementalSkillBasedRoutingAttribute" count: type: integer description: The number of results returned for the current request readOnly: true end_time: type: integer description: The most recent resource creation time present in this result set in Unix epoch time readOnly: true instance_values: type: array description: Routing instance values items: $ref: "#/components/schemas/IncrementalSkillBasedRoutingInstanceValue" next_page: type: string description: The URL that should be called to get the next set of results readOnly: true IncrementalSkillBasedRoutingAttribute: type: object properties: id: type: string description: Automatically assigned when an attribute is created readOnly: true name: type: string description: The name of the attribute readOnly: true time: type: string format: date-time description: The time the attribute was created, updated, or deleted readOnly: true type: type: string description: One of "create", "update", or "delete" readOnly: true IncrementalSkillBasedRoutingAttributeValue: type: object properties: attribute_id: type: string description: Id of the associated attribute readOnly: true id: type: string description: Automatically assigned when an attribute value is created readOnly: true name: type: string description: The name of the attribute value readOnly: true time: type: string format: date-time description: The time the attribute value was created, updated, or deleted readOnly: true type: type: string description: One of "create", "update", or "delete" readOnly: true IncrementalSkillBasedRoutingInstanceValue: type: object properties: attribute_value_id: type: string description: Id of the associated attribute value readOnly: true id: type: string description: Automatically assigned when an instance value is created readOnly: true instance_id: type: string description: Id of the associated agent or ticket readOnly: true time: type: string format: date-time description: The time the instance value was created or deleted readOnly: true type: type: string description: One of "associate_agent", "unassociate_agent", "associate_ticket", or "unassociate_ticket" readOnly: true JobStatusObject: type: object properties: id: type: string description: Automatically assigned when the job is queued readOnly: true job_type: type: string description: The type of the job readOnly: true message: type: string description: Message from the job worker, if any nullable: true readOnly: true progress: type: integer description: Number of tasks that have already been completed nullable: true readOnly: true results: description: Result data from processed tasks. See [Results](#results) below oneOf: - type: array items: $ref: "#/components/schemas/JobStatusResultObject" nullable: true - type: object properties: success: type: boolean description: Whether the action was successful or not readOnly: true required: - success readOnly: true status: type: string description: 'The current status. One of the following: "queued", "working", "failed", "completed"' readOnly: true total: type: integer description: The total number of tasks this job is batching through nullable: true readOnly: true url: type: string description: The URL to poll for status updates readOnly: true JobStatusResponse: type: object properties: job_status: $ref: "#/components/schemas/JobStatusObject" JobStatusResultObject: oneOf: - $ref: "#/components/schemas/CreateResourceResult" - $ref: "#/components/schemas/UpdateResourceResult" - $ref: "#/components/schemas/FailedResult" additionalProperties: true JobStatusesResponse: type: object properties: job_statuses: type: array items: $ref: "#/components/schemas/JobStatusObject" required: - job_statuses ListDeletedTicketsResponse: type: object allOf: - type: object properties: deleted_tickets: type: array items: type: object properties: actor: type: object properties: id: type: integer name: type: string deleted_at: type: string id: type: integer previous_state: type: string subject: type: string - $ref: "#/components/schemas/OffsetPaginationObject" ListTicketCollaboratorsResponse: type: object additionalProperties: true ListTicketEmailCCsResponse: type: object additionalProperties: true ListTicketFollowersResponse: type: object additionalProperties: true ListTicketIncidentsResponse: type: object additionalProperties: true ListTicketProblemsResponse: type: object additionalProperties: true LocaleObject: type: object properties: created_at: type: string format: date-time description: The ISO 8601 formatted date-time the locale was created readOnly: true id: type: integer description: The unique ID of the locale readOnly: true locale: type: string description: The name of the locale readOnly: true name: type: string description: The name of the language readOnly: true updated_at: type: string format: date-time description: The ISO 8601 formatted date-time when the locale was last updated readOnly: true url: type: string description: The URL of the locale record readOnly: true LocaleResponse: type: object properties: locale: $ref: "#/components/schemas/LocaleObject" LocalesResponse: type: object properties: locales: type: array items: $ref: "#/components/schemas/LocaleObject" MacroApplyTicketResponse: type: object properties: result: type: object properties: ticket: type: object properties: assignee_id: type: integer comment: type: object properties: body: type: string public: type: boolean scoped_body: type: array items: type: array items: type: string fields: type: object properties: id: type: integer value: type: string group_id: type: integer id: type: integer url: type: string MacroAttachmentObject: type: object properties: content_type: type: string description: 'The content type of the image. Example value: "image/png"' readOnly: true content_url: type: string description: A full URL where the attachment image file can be downloaded readOnly: true created_at: type: string format: date-time description: The time when this attachment was created filename: type: string description: The name of the image file readOnly: true id: type: integer description: Automatically assigned when created readOnly: true size: type: integer description: The size of the image file in bytes readOnly: true MacroAttachmentResponse: type: object properties: macro_attachment: $ref: "#/components/schemas/MacroAttachmentObject" MacroAttachmentsResponse: type: object properties: macro_attachments: type: array items: $ref: "#/components/schemas/MacroAttachmentObject" MacroCategoriesResponse: type: object properties: categories: type: array items: type: string MacroCommonObject: type: object properties: actions: type: array description: Each action describes what the macro will do. See [Actions reference](/documentation/ticketing/reference-guides/actions-reference) items: $ref: "#/components/schemas/ActionObject" active: type: boolean description: Useful for determining if the macro should be displayed created_at: type: string format: date-time description: The time the macro was created readOnly: true default: type: boolean description: If true, the macro is a default macro readOnly: true description: type: string description: The description of the macro nullable: true id: type: integer description: The id automatically assigned when a macro is created readOnly: true position: type: integer description: The position of the macro restriction: type: object description: Access to this macro. A null value allows unrestricted access for all users in the account additionalProperties: true nullable: true title: type: string description: The title of the macro updated_at: type: string format: date-time description: The time of the last update of the macro readOnly: true url: type: string description: A URL to access the macro's details readOnly: true required: - actions - title MacroInput: type: object properties: actions: type: array description: Each action describes what the macro will do items: $ref: "#/components/schemas/ActionObject" active: type: boolean description: Useful for determining if the macro should be displayed description: type: string description: The description of the macro nullable: true restriction: type: object description: Who may access this macro. Will be null when everyone in the account can access it properties: id: type: integer description: The numeric ID of the group or user ids: type: array description: The numeric IDs of the groups items: type: integer type: type: string description: Allowed values are Group or User additionalProperties: true title: type: string description: The title of the macro required: - title - actions MacroObject: type: object allOf: - $ref: "#/components/schemas/MacroCommonObject" - type: object properties: app_installation: type: string description: The app installation that requires each macro, if present nullable: true categories: type: string description: The macro categories nullable: true permissions: type: string description: Permissions for each macro nullable: true usage_1h: type: integer description: The number of times each macro has been used in the past hour usage_7d: type: integer description: The number of times each macro has been used in the past week usage_24h: type: integer description: The number of times each macro has been used in the past day usage_30d: type: integer description: The number of times each macro has been used in the past thirty days MacroResponse: type: object properties: macro: $ref: "#/components/schemas/MacroObject" MacroUpdateManyInput: type: object properties: macros: type: array items: type: object properties: active: type: boolean description: The active status of the macro (true or false) id: type: integer description: The ID of the macro to update position: type: integer description: The new position of the macro required: - id MacrosResponse: type: object allOf: - type: object properties: macros: type: array items: $ref: "#/components/schemas/MacroObject" - $ref: "#/components/schemas/OffsetPaginationObject" ManySkillBasedRoutingAttributeValues: type: object properties: agent_id: type: integer description: Id of the associated agent readOnly: true attribute_id: type: string description: Id of the associated attribute readOnly: true attribute_value_id: type: string description: Id of the associated attribute value readOnly: true created_at: type: string format: date-time description: The time of creation of the instance value readOnly: true id: type: string description: Automatically assigned when an instance value is created readOnly: true name: type: string description: Name of the associated attribute value readOnly: true updated_at: type: string format: date-time description: The time of the last update of the instance value readOnly: true url: type: string description: The URL of the associated attribute value readOnly: true ManySkillBasedRoutingAttributeValuesResponse: type: object properties: count: type: integer format: int32 description: The number of instance values returned readOnly: true instance_values: type: array items: $ref: "#/components/schemas/ManySkillBasedRoutingAttributeValues" next_page: type: string description: The URL for the next page of results nullable: true readOnly: true previous_page: type: string description: The URL for the previous page of results nullable: true readOnly: true OAuthClientObject: type: object properties: company: type: string description: The company name displayed when users are asked to grant access to your application. created_at: type: string format: date-time description: The time the client was created readOnly: true description: type: string description: A short description of your client that is displayed to users when they are considering approving access to your application global: type: boolean description: Whether this client is globally accessible. See [Set up a global OAuth client](/documentation/apps/publish-your-app-or-theme/global_oauth_intro/) readOnly: true id: type: integer description: Automatically assigned upon creation readOnly: true identifier: type: string description: The unique identifier for this client kind: type: string description: Either "public" or "confidential". Specifies whether the OAuth client operates in a public environment where credentials cannot be securely stored, or on secure servers that can safely store credentials. See [Client types](/documentation/ticketing/working-with-oauth/oauth-pkce/#client-types) logo_url: type: string description: The API logo url of this record readOnly: true name: type: string description: The name of this client redirect_uri: type: array description: An array of the valid redirect URIs for this client items: type: string secret: type: string description: The client secret. Generated automatically on creation and returned in full only at that time readOnly: true updated_at: type: string format: date-time description: The time of the last update of the client readOnly: true url: type: string description: The API url of this record readOnly: true user_id: type: integer description: The id of the admin who created the client required: - name - identifier - user_id OAuthClientsResponse: type: object properties: clients: type: array items: $ref: "#/components/schemas/OAuthClientObject" OAuthTokenForGrantTypesObject: title: OAuth Tokens for Grant Types type: object properties: access_token: type: string description: The access token readOnly: true expires_in: type: integer description: Number of seconds the access token is valid. Must be more than 300 seconds (5 minutes) and less than 172,800 seconds (2 days), or less than `refresh_token_expires_in`, whichever is the smallest. Defaults to null refresh_token: type: string description: The refresh token readOnly: true refresh_token_expires_in: type: integer description: Number of seconds the refresh token is valid. Must be more than 604,800 seconds (7 days) or `expires_in` (if given), and less than 7,776,000 seconds (90 days). Defaults to 2,592,000 seconds (30 days) scope: type: string description: The valid scopes for this token. See [Scope](#scope) below readOnly: true token_type: type: string description: Type of the access token, for example "bearer" readOnly: true OAuthTokenResponse: type: object properties: token: $ref: "#/components/schemas/OauthTokenObject" OAuthTokensResponse: type: object properties: tokens: type: array items: $ref: "#/components/schemas/OauthTokenObject" OauthClientResponse: type: object properties: client: $ref: "#/components/schemas/OAuthClientObject" OauthTokenObject: type: object properties: client_id: type: integer description: The id of the client this token belongs to readOnly: true created_at: type: string format: date-time description: The time the token was created readOnly: true expires_at: type: string format: date-time description: The time the token will expire readOnly: true id: type: integer description: Automatically assigned upon creation readOnly: true refresh_token: type: string description: The refresh token, if generated readOnly: true refresh_token_expires_at: type: string format: date-time description: The time the refresh token will expire readOnly: true scopes: type: array description: An array of the valid scopes for this token. See [Scopes](#scopes) below items: type: string readOnly: true token: type: string description: The access token readOnly: true url: type: string description: The API url of this record readOnly: true used_at: type: string format: date-time description: The latest time this token was used for authentication readOnly: true user_id: type: integer description: The id of the user this token authenticates as readOnly: true ObjectTriggerActionDefinitionObject: type: object properties: group: type: string nullable: type: boolean repeatable: type: boolean subject: type: string title: type: string type: type: string values: type: array items: type: object properties: enabled: type: boolean format: type: string title: type: string value: type: string ObjectTriggerBulkUpdateItem: type: object properties: active: type: boolean description: Whether an object trigger is active id: type: integer description: The id of the object trigger to update position: type: integer description: The new position of the object trigger required: - id ObjectTriggerBulkUpdateRequest: type: object properties: triggers: type: array items: $ref: "#/components/schemas/ObjectTriggerBulkUpdateItem" ObjectTriggerConditionDefinitionObjectAll: type: object properties: group: type: string nullable: type: boolean operators: type: array items: type: object properties: format: type: string terminal: type: boolean title: type: string value: type: string repeatable: type: boolean subject: type: string title: type: string type: type: string values: type: array items: type: object properties: enabled: type: boolean title: type: string value: type: string ObjectTriggerConditionDefinitionObjectAny: type: object properties: group: type: string nullable: type: boolean operators: type: array items: type: object properties: format: type: string terminal: type: boolean title: type: string value: type: string repeatable: type: boolean subject: type: string title: type: string type: type: string values: type: array items: type: object properties: enabled: type: boolean title: type: string value: type: string ObjectTriggerDefinitionObject: type: object properties: actions: type: array items: $ref: "#/components/schemas/ObjectTriggerActionDefinitionObject" conditions_all: type: array items: $ref: "#/components/schemas/ObjectTriggerConditionDefinitionObjectAll" conditions_any: type: array items: $ref: "#/components/schemas/ObjectTriggerConditionDefinitionObjectAny" ObjectTriggerDefinitionResponse: type: object properties: definitions: $ref: "#/components/schemas/ObjectTriggerDefinitionObject" ObjectTriggerObject: type: object properties: actions: type: array description: An array of actions the trigger does when its conditions are met. See [Actions reference](/documentation/ticketing/reference-guides/actions-reference) items: $ref: "#/components/schemas/TriggerActionObject" active: type: boolean description: Whether the trigger is active conditions: $ref: "#/components/schemas/TriggerConditionsObject" created_at: type: string description: The time the trigger was created readOnly: true default: type: boolean description: Always false for object triggers readOnly: true description: type: string description: The description of the trigger id: type: integer description: Automatically assigned when created readOnly: true position: type: integer description: Position of the trigger, determines the order they will execute in raw_title: type: string description: The raw format of the title of the trigger title: type: string description: The title of the trigger updated_at: type: string description: The time of the last update of the trigger readOnly: true url: type: string description: The url of the trigger readOnly: true required: - conditions - actions - title ObjectTriggerRequest: type: object properties: trigger: allOf: - $ref: "#/components/schemas/ObjectTriggerObject" ObjectTriggerResponse: type: object properties: trigger: $ref: "#/components/schemas/ObjectTriggerObject" ObjectTriggersResponse: type: object properties: count: type: integer next_page: type: string nullable: true previous_page: type: string nullable: true triggers: type: array items: $ref: "#/components/schemas/ObjectTriggerObject" OffsetPaginationObject: type: object properties: count: type: integer description: the total record count next_page: type: string format: url description: the URL of the next page nullable: true previous_page: type: string format: url description: the URL of the previous page nullable: true OrganizationFieldObject: type: object allOf: - $ref: "#/components/schemas/CustomFieldObject" OrganizationFieldResponse: type: object properties: organization_field: $ref: "#/components/schemas/OrganizationFieldObject" OrganizationFieldsResponse: type: object properties: count: type: integer description: Total count of records retrieved readOnly: true next_page: type: string description: URL of the next page nullable: true readOnly: true organization_fields: type: array items: $ref: "#/components/schemas/OrganizationFieldObject" previous_page: type: string description: URL of the previous page nullable: true readOnly: true OrganizationMembershipObject: type: object properties: created_at: type: string format: date-time description: When this record was created readOnly: true default: type: boolean description: Denotes whether this is the default organization membership for the user. If false, returns `null` nullable: true id: type: integer description: Automatically assigned when the membership is created readOnly: true organization_id: type: integer description: The ID of the organization associated with this user, in this membership readOnly: true organization_name: type: string description: The name of the organization associated with this user, in this membership readOnly: true updated_at: type: string format: date-time description: When this record last got updated readOnly: true url: type: string description: The API url of this membership readOnly: true user_id: type: integer description: The ID of the user for whom this memberships belongs readOnly: true view_tickets: type: boolean description: Denotes whether the user can or cannot have access to all organization's tickets. readOnly: true required: - user_id - organization_id - default OrganizationMembershipResponse: type: object properties: organization_membership: $ref: "#/components/schemas/OrganizationMembershipObject" OrganizationMembershipsResponse: type: object properties: organization_memberships: type: array items: $ref: "#/components/schemas/OrganizationMembershipObject" OrganizationMergeListResponse: type: object properties: organization_merges: type: array items: type: object properties: id: type: string format: string loser_id: type: integer status: type: string enum: - new - in_progress - error - complete url: type: string format: string winner_id: type: integer required: - id - url - loser_id - winner_id - status OrganizationMergeRequest: type: object properties: organization_merge: type: object properties: winner_id: type: integer description: The id of the winning organization. required: - winner_id OrganizationMergeResponse: type: object properties: organization_merge: type: object properties: id: type: string format: string loser_id: type: integer status: type: string enum: - new - in_progress - error - complete url: type: string format: string winner_id: type: integer required: - id - url - loser_id - winner_id - status OrganizationMetadataObject: type: object properties: tickets_count: type: integer description: The number of tickets for the organization users_count: type: integer description: The number of users for the organization OrganizationObject: type: object properties: created_at: type: string description: The time the organization was created readOnly: true details: type: string description: Any details obout the organization, such as the address nullable: true domain_names: type: array description: An array of domain names associated with this organization items: type: string external_id: type: string description: A unique external id to associate organizations to an external record. The id is case-insensitive. For example, "company1" and "Company1" are considered the same nullable: true group_id: type: integer description: New tickets from users in this organization are automatically put in this group nullable: true id: type: integer description: Automatically assigned when the organization is created name: type: string description: A unique name for the organization notes: type: string description: Any notes you have about the organization nullable: true organization_fields: type: object description: Custom fields for this organization. See [Custom organization fields](/api-reference/ticketing/organizations/organizations/#custom-organization-fields) additionalProperties: oneOf: - type: string - type: number nullable: true shared_comments: type: boolean description: End users in this organization are able to comment on each other's tickets shared_tickets: type: boolean description: End users in this organization are able to see each other's tickets tags: type: array description: The tags of the organization items: type: string updated_at: type: string description: The time of the last update of the organization readOnly: true url: type: string description: The API url of this organization readOnly: true required: - name OrganizationResponse: type: object properties: organization: $ref: "#/components/schemas/OrganizationObject" OrganizationSubscriptionCreateRequest: type: object properties: organization_subscription: $ref: "#/components/schemas/OrganizationSubscriptionInput" OrganizationSubscriptionInput: type: object properties: organization_id: type: integer description: The ID of the organization user_id: type: integer description: The ID of the user OrganizationSubscriptionObject: title: Organization Subscriptions type: object properties: created_at: type: string format: date-time description: The date the organization subscription was created id: type: integer description: The ID of the organization subscription organization_id: type: integer description: The ID of the organization user_id: type: integer description: The ID of the user OrganizationSubscriptionResponse: type: object properties: organization_subscription: $ref: "#/components/schemas/OrganizationSubscriptionObject" OrganizationSubscriptionsResponse: type: object allOf: - $ref: "#/components/schemas/OffsetPaginationObject" - type: object properties: organization_subscriptions: type: array description: An array of organization subscriptions items: $ref: "#/components/schemas/OrganizationSubscriptionObject" OrganizationsRelatedResponse: type: object properties: organization_related: $ref: "#/components/schemas/OrganizationMetadataObject" OrganizationsResponse: type: object properties: count: type: integer next_page: type: string nullable: true organizations: type: array items: $ref: "#/components/schemas/OrganizationObject" previous_page: type: string nullable: true Pagination: type: object properties: links: type: object properties: next: type: string prev: type: string meta: type: object properties: after_cursor: type: string before_cursor: type: string has_more: type: boolean PushNotificationDevicesInput: type: array items: type: string description: Mobile device token PushNotificationDevicesRequest: type: object properties: push_notification_devices: $ref: "#/components/schemas/PushNotificationDevicesInput" QueueObject: type: object properties: created_at: type: string format: date-time description: The time the queue was created readOnly: true definition: type: object description: Conditions when queue could be applied properties: all: type: array items: type: object properties: field: type: string operator: type: string value: type: string any: type: array items: type: object properties: field: type: string operator: type: string value: type: string description: type: string description: The description of the queue id: type: string description: Automatically assigned when creating queue readOnly: true name: type: string description: The name of the queue order: type: integer description: The queue-applied order primary_groups: type: object description: Primary group ids linked to the queue properties: count: type: integer groups: type: array items: type: object properties: id: type: integer name: type: string priority: type: integer description: The queue-applied priority secondary_groups: type: object description: Secondary group ids linked to the queue properties: count: type: integer groups: type: array items: type: object properties: id: type: integer name: type: string updated_at: type: string format: date-time description: The time of the queue's last update readOnly: true url: type: string description: The API URL of the queue readOnly: true QueueResponse: type: object properties: queue: $ref: "#/components/schemas/QueueObject" QueuesResponse: type: object properties: queues: type: array items: $ref: "#/components/schemas/QueueObject" RecipientObject: type: object properties: delivery_status: type: object description: Details about the delivery status properties: code: type: string description: The delivery status code (SMTP code and DSN code) readOnly: true id: type: integer description: The delivery status id readOnly: true message: type: string description: The delivery status description readOnly: true name: type: string description: The delivery status type (key) readOnly: true email_address: type: string description: The recipient's email address readOnly: true user_id: type: integer description: The recipient's user id readOnly: true RecoverSuspendedTicketResponse: type: object properties: ticket: type: array items: $ref: "#/components/schemas/TicketObject" RecoverSuspendedTicketUnprocessableContentResponse: type: object properties: ticket: type: array items: $ref: "#/components/schemas/SuspendedTicketObject" RecoverSuspendedTicketsResponse: type: object properties: tickets: type: array items: $ref: "#/components/schemas/TicketObject" RelationshipFilterDefinition: type: object properties: conditions_all: type: array items: $ref: "#/components/schemas/TriggerConditionDefinitionObjectAll" conditions_any: type: array items: $ref: "#/components/schemas/TriggerConditionDefinitionObjectAny" RelationshipFilterDefinitionResponse: type: object properties: definitions: $ref: "#/components/schemas/RelationshipFilterDefinition" RenewSessionResponse: type: object properties: authenticity_token: type: string description: A token of authenticity for the request RequestObject: type: object properties: assignee_id: type: integer description: The id of the assignee if the field is visible to end users readOnly: true can_be_solved_by_me: type: boolean description: If true, an end user can mark the request as solved. See [Update Request](/api-reference/ticketing/tickets/ticket-requests/#update-request) readOnly: true collaborator_ids: type: array description: The ids of users currently CC'ed on the ticket items: type: integer readOnly: true created_at: type: string format: date-time description: When this record was created readOnly: true custom_fields: type: array description: Custom fields for the request. See [Setting custom field values](/api-reference/ticketing/tickets/tickets/#setting-custom-field-values) in the Tickets doc items: type: object properties: id: type: integer value: type: string custom_status_id: type: integer description: The custom ticket status id of the ticket description: type: string description: Read-only first comment on the request. When [creating a request](#create-request), use `comment` to set the description readOnly: true due_at: type: string format: date-time description: When the task is due (only applies if the request is of type "task") email_cc_ids: type: array description: The ids of users who are currently email CCs on the ticket. See [CCs and followers resources](https://support.zendesk.com/hc/en-us/articles/360020585233) in the Support Help Center items: type: integer readOnly: true followup_source_id: type: integer description: The id of the original ticket if this request is a follow-up ticket. See [Create Request](#create-request) readOnly: true group_id: type: integer description: The id of the assigned group if the field is visible to end users readOnly: true id: type: integer description: Automatically assigned when creating requests readOnly: true is_public: type: boolean description: Is true if any comments are public, false otherwise readOnly: true organization_id: type: integer description: The organization of the requester readOnly: true priority: type: string description: The priority of the request, "low", "normal", "high", "urgent" recipient: type: string description: The original recipient e-mail address of the request requester_id: type: integer description: The id of the requester readOnly: true solved: type: boolean description: Whether or not request is solved (an end user can set this if "can_be_solved_by_me", above, is true for that user) status: type: string description: The state of the request, "new", "open", "pending", "hold", "solved", "closed" subject: type: string description: The value of the subject field for this request if the subject field is visible to end users; a truncated version of the description otherwise ticket_form_id: type: integer description: The numeric id of the ticket form associated with this request if the form is visible to end users - only applicable for enterprise accounts type: type: string description: The type of the request, "question", "incident", "problem", "task" updated_at: type: string format: date-time description: When this record last got updated readOnly: true url: type: string description: The API url of this request readOnly: true via: $ref: "#/components/schemas/TicketAuditViaObject" required: - subject RequestResponse: type: object properties: request: $ref: "#/components/schemas/RequestObject" RequestsResponse: type: object properties: requests: type: array items: $ref: "#/components/schemas/RequestObject" ResourceCollectionObject: type: object properties: created_at: type: string format: date-time description: When the resource collection was created readOnly: true id: type: integer description: id for the resource collection. Automatically assigned upon creation readOnly: true resources: type: array description: Array of resource metadata objects. See [Resource objects](#resource-objects) items: type: object properties: deleted: type: boolean identifier: type: string resource_id: type: integer type: type: string readOnly: true updated_at: type: string format: date-time description: Last time the resource collection was updated readOnly: true ResourceCollectionResponse: type: object properties: resource_collection: $ref: "#/components/schemas/ResourceCollectionObject" ResourceCollectionsResponse: type: object properties: count: type: integer readOnly: true next_page: type: string nullable: true readOnly: true previous_page: type: string nullable: true readOnly: true resource_collections: type: array items: $ref: "#/components/schemas/ResourceCollectionObject" ReverseLookupResponse: type: object oneOf: - $ref: "#/components/schemas/UsersResponse" SLAPoliciesResponse: type: object properties: count: type: integer readOnly: true next_page: type: string nullable: true readOnly: true previous_page: type: string nullable: true readOnly: true sla_policies: type: array items: $ref: "#/components/schemas/SLAPolicyObject" SLAPolicyFilterConditionObject: type: object properties: field: type: string description: The name of a ticket field operator: type: string description: A comparison operator value: description: The value of a ticket field oneOf: - type: string - type: array items: oneOf: - type: string - type: integer SLAPolicyFilterDefinitionResponse: type: object properties: definitions: type: object properties: all: type: array items: type: object properties: group: type: string operators: type: array items: type: object properties: title: type: string value: type: string target: type: string nullable: true title: type: string value: type: string values: type: object properties: list: type: array items: type: object properties: title: type: string value: type: string nullable: true type: type: string any: type: array items: type: object properties: group: type: string operators: type: array items: type: object properties: title: type: string value: type: string target: type: string nullable: true title: type: string value: type: string values: type: object properties: list: type: array items: type: object properties: title: type: string value: type: string nullable: true type: type: string SLAPolicyFilterObject: type: object description: An object that describes the conditions that a ticket must match in order for an SLA policy to be applied to that ticket. See [Filter](#filter). properties: all: type: array items: $ref: "#/components/schemas/SLAPolicyFilterConditionObject" any: type: array items: $ref: "#/components/schemas/SLAPolicyFilterConditionObject" SLAPolicyMetricObject: type: object properties: business_hours: type: boolean description: Whether the metric targets are being measured in business hours or calendar hours metric: type: string description: The definition of the time that is being measured priority: type: string description: Priority that a ticket must match target: type: integer description: The time within which the end-state for a metric should be met SLAPolicyObject: type: object properties: created_at: type: string format: date-time description: The time the SLA policy was created readOnly: true description: type: string description: The description of the SLA policy filter: $ref: "#/components/schemas/SLAPolicyFilterObject" id: type: integer description: Automatically assigned when created readOnly: true policy_metrics: type: array description: Array of [Policy Metric](#policy-metric) objects items: $ref: "#/components/schemas/SLAPolicyMetricObject" position: type: integer description: Position of the SLA policy that determines the order they will be matched. If not specified, the SLA policy is added as the last position title: type: string description: The title of the SLA policy updated_at: type: string format: date-time description: The time of the last update of the SLA policy readOnly: true url: type: string description: URL of the SLA Policy reacord readOnly: true required: - title - filter SLAPolicyResponse: type: object properties: sla_policy: $ref: "#/components/schemas/SLAPolicyObject" SatisfactionRatingObject: type: object properties: assignee_id: type: integer description: The id of agent assigned to at the time of rating readOnly: true comment: type: string description: The comment received with this rating, if available created_at: type: string format: date-time description: The time the satisfaction rating got created readOnly: true group_id: type: integer description: The id of group assigned to at the time of rating readOnly: true id: type: integer description: Automatically assigned upon creation readOnly: true reason: type: string description: The reason for a bad rating given by the requester in a follow-up question. Satisfaction reasons must be [enabled](https://support.zendesk.com/hc/en-us/articles/223152967) reason_code: type: integer description: The default reasons the user can select from a list menu for giving a negative rating. See [Reason codes](/api-reference/ticketing/ticket-management/satisfaction_reasons/#reason-codes) in the Satisfaction Reasons API. Can only be set on ratings with a `score` of "bad". Responses don't include this property reason_id: type: integer description: id for the reason the user gave a negative rating. Can only be set on ratings with a `score` of "bad". To get a descriptive value for the id, use the [Show Reason for Satisfaction Rating](/api-reference/ticketing/ticket-management/satisfaction_reasons/#show-reason-for-satisfaction-rating) endpoint requester_id: type: integer description: The id of ticket requester submitting the rating readOnly: true score: type: string description: The rating "offered", "unoffered", "good" or "bad" ticket_id: type: integer description: The id of ticket being rated readOnly: true updated_at: type: string format: date-time description: The time the satisfaction rating got updated readOnly: true url: type: string description: The API url of this rating readOnly: true required: - assignee_id - group_id - requester_id - ticket_id - score SatisfactionRatingResponse: type: object properties: satisfaction_rating: type: array items: $ref: "#/components/schemas/SatisfactionRatingObject" SatisfactionRatingsCountResponse: type: object properties: count: type: object properties: refreshed_at: type: string format: date-time value: type: integer SatisfactionRatingsResponse: type: object properties: satisfaction_ratings: type: array items: $ref: "#/components/schemas/SatisfactionRatingObject" SatisfactionReasonObject: type: object properties: created_at: type: string format: date-time description: The time the reason was created readOnly: true deleted_at: type: string format: date-time description: The time the reason was deleted readOnly: true id: type: integer description: Automatically assigned upon creation readOnly: true raw_value: type: string description: The dynamic content placeholder, if present, or the current "value", if not. See [Dynamic Content Items](/api-reference/ticketing/ticket-management/dynamic_content/) reason_code: type: integer description: An account-level code for referencing the reason. Custom reasons are assigned an auto-incrementing integer (non-system reason codes begin at 1000). See [Reason codes](#reason-codes) readOnly: true updated_at: type: string format: date-time description: The time the reason was updated readOnly: true url: type: string description: API URL for the resource readOnly: true value: type: string description: Translated value of the reason in the account locale required: - value SatisfactionReasonResponse: type: object properties: reason: type: array items: $ref: "#/components/schemas/SatisfactionReasonObject" SatisfactionReasonsResponse: type: object properties: reasons: type: array items: $ref: "#/components/schemas/SatisfactionReasonObject" SearchCountResponse: type: object properties: count: type: integer SearchExportResponse: type: object properties: facets: type: string description: The facets corresponding to the search query nullable: true readOnly: true links: type: object description: The links to the previous and next entries via the cursor ids in the metadata. properties: next: type: string description: The url to the next entry via the cursor. nullable: true readOnly: true prev: type: string description: The url to the previous entry via the cursor. nullable: true readOnly: true meta: type: object description: Metadata for the export query response. properties: after_cursor: type: string description: The cursor id for the next object. nullable: true readOnly: true before_cursor: type: string description: The cursor id for the previous object. nullable: true readOnly: true has_more: type: boolean description: Whether there are more items yet to be returned by the cursor. readOnly: true results: type: array description: May consist of tickets, users, groups, or organizations, as specified by the `result_type` property in each result object items: $ref: "#/components/schemas/SearchResultObject" readOnly: true SearchResponse: type: object properties: count: type: integer description: The number of resources returned by the query corresponding to this page of results in the paginated response readOnly: true facets: type: string description: The facets corresponding to the search query nullable: true readOnly: true next_page: type: string description: URL to the next page of results nullable: true readOnly: true previous_page: type: string description: URL to the previous page of results nullable: true readOnly: true results: type: array description: May consist of tickets, users, groups, or organizations, as specified by the `result_type` property in each result object items: $ref: "#/components/schemas/SearchResultObject" readOnly: true SearchResultObject: type: object properties: created_at: type: string description: When the resource was created default: type: boolean description: Flag to indicate whether this is the default resource deleted: type: boolean description: Flag to indicate whether or not resource has been deleted description: type: string description: The description of the resource id: type: integer description: The ID of the resource name: type: string description: The name of the resource result_type: type: string description: The type of the resource updated_at: type: string description: When the resource was last updated url: type: string description: The url of the resource SessionObject: type: object properties: authenticated_at: type: string description: When the session was created nullable: true id: type: integer description: Automatically assigned when the session is created last_seen_at: type: string description: The last approximate time this session was seen. This does not update on every request. nullable: true url: type: string description: The API URL of this session nullable: true user_id: type: integer description: The id of the user nullable: true required: - id SessionResponse: type: object properties: session: type: array items: $ref: "#/components/schemas/SessionObject" SessionsResponse: type: object properties: sessions: type: array items: $ref: "#/components/schemas/SessionObject" SharingAgreementObject: type: object properties: created_at: type: string format: date-time description: The time the record was created readOnly: true id: type: integer description: Automatically assigned upon creation readOnly: true name: type: string description: Name of this sharing agreement partner_name: type: string description: 'Can be one of the following: "jira", null' nullable: true remote_subdomain: type: string description: Subdomain of the remote account or null if not associated with an account status: type: string description: 'Can be one of the following: "accepted", "declined", "pending", "inactive", "failed", "ssl_error", "configuration_error"' type: type: string description: 'Can be one of the following: "inbound", "outbound"' updated_at: type: string format: date-time description: The time the record was updated readOnly: true url: type: string description: URL of the sharing agreement record readOnly: true SharingAgreementResponse: type: object properties: sharing_agreement: $ref: "#/components/schemas/SharingAgreementObject" SharingAgreementsResponse: type: object properties: sharing_agreements: type: array items: $ref: "#/components/schemas/SharingAgreementObject" SkillBasedRoutingAttributeDefinitions: type: object properties: definitions: type: object properties: conditions_all: type: array items: type: object properties: subject: type: string title: type: string conditions_any: type: array items: type: object properties: subject: type: string title: type: string SkillBasedRoutingAttributeObject: type: object properties: created_at: type: string format: date-time description: When this record was created readOnly: true id: type: string description: Automatically assigned when an attribute is created readOnly: true name: type: string description: The name of the attribute updated_at: type: string format: date-time description: When this record was last updated readOnly: true url: type: string description: URL of the attribute readOnly: true required: - name SkillBasedRoutingAttributeResponse: type: object properties: attribute: $ref: "#/components/schemas/SkillBasedRoutingAttributeObject" SkillBasedRoutingAttributeValueObject: type: object properties: attribute_id: type: string description: Id of the associated attribute created_at: type: string format: date-time description: When this record was created readOnly: true id: type: string description: Automatically assigned when an attribute value is created readOnly: true name: type: string description: The name of the attribute value updated_at: type: string format: date-time description: When this record was last updated readOnly: true url: type: string description: URL of the attribute value readOnly: true SkillBasedRoutingAttributeValueResponse: type: object properties: attribute_value: $ref: "#/components/schemas/SkillBasedRoutingAttributeValueObject" SkillBasedRoutingAttributeValuesError: type: object properties: error: type: object properties: message: type: string title: type: string SkillBasedRoutingAttributeValuesResponse: type: object properties: attribute_values: type: array items: $ref: "#/components/schemas/SkillBasedRoutingAttributeValueObject" SkillBasedRoutingAttributesResponse: type: object properties: attributes: type: array items: $ref: "#/components/schemas/SkillBasedRoutingAttributeObject" count: type: integer readOnly: true next_page: type: string nullable: true readOnly: true previous_page: type: string nullable: true readOnly: true SkillBasedRoutingTicketFulfilledResponse: type: object properties: fulfilled_ticket_ids: type: array items: type: integer SupportAddressObject: type: object properties: brand_id: type: integer description: The ID of the [brand](/api-reference/ticketing/account-configuration/brands/) cname_status: type: string description: 'Whether all of the required CNAME records are set. Possible values: "unknown", "verified", "failed"' enum: - unknown - verified - failed readOnly: true created_at: type: string format: date-time description: When the address was created readOnly: true default: type: boolean description: Whether the address is the account's default support address dns_results: type: string description: 'Verification statuses for the domain and CNAME records. Possible types: "verified", "failed"' enum: - verified - failed readOnly: true domain_verification_code: type: string description: "Verification string to be added as a TXT record to the domain. Possible types: string or null." readOnly: true domain_verification_status: type: string description: 'Whether the domain verification record is valid. Possible values: "unknown", "verified", "failed"' enum: - unknown - verified - failed readOnly: true email: type: string description: The email address. You can't change the email address of an existing support address. forwarding_status: type: string description: 'Status of email forwarding. Possible values: "unknown", "waiting", "verified", or "failed"' enum: - unknown - waiting - verified - failed readOnly: true id: type: integer description: Automatically assigned when created readOnly: true name: type: string description: The name for the address spf_status: type: string description: 'Whether the SPF record is set up correctly. Possible values: "unknown", "verified", "failed"' enum: - unknown - verified - failed readOnly: true updated_at: type: string format: date-time description: When the address was updated readOnly: true required: - email SupportAddressResponse: type: object properties: recipient_address: $ref: "#/components/schemas/SupportAddressObject" SupportAddressesResponse: type: object properties: recipient_addresses: type: array items: $ref: "#/components/schemas/SupportAddressObject" SuspendedTicketObject: type: object properties: attachments: type: array description: The attachments, if any associated to this suspended ticket. See [Attachments](/api-reference/ticketing/tickets/ticket-attachments/) items: $ref: "#/components/schemas/AttachmentObject" nullable: true readOnly: true author: type: object description: The author id (if available), name and email allOf: - $ref: "#/components/schemas/AuthorObject" readOnly: true brand_id: type: integer description: The id of the brand this ticket is associated with. Only applicable for Enterprise accounts readOnly: true cause: type: string description: Why the ticket was suspended readOnly: true cause_id: type: integer description: The ID of the cause readOnly: true content: type: string description: The content that was flagged readOnly: true created_at: type: string format: date-time description: The ticket ID this suspended email is associated with, if available readOnly: true error_messages: type: array description: The error messages if any associated to this suspended ticket items: type: object nullable: true readOnly: true id: type: integer description: Automatically assigned readOnly: true message_id: type: string description: The ID of the email, if available readOnly: true recipient: type: string description: The original recipient e-mail address of the ticket readOnly: true subject: type: string description: The value of the subject field for this ticket readOnly: true ticket_id: type: integer description: The ticket ID this suspended email is associated with, if available readOnly: true updated_at: type: string format: date-time description: When the ticket was assigned readOnly: true url: type: string description: The API url of this ticket readOnly: true via: $ref: "#/components/schemas/ViaObject" SuspendedTicketResponse: type: object properties: suspended_ticket: type: array items: $ref: "#/components/schemas/SuspendedTicketObject" SuspendedTicketsAttachmentsResponse: type: object properties: upload: type: object properties: attachments: type: array items: $ref: "#/components/schemas/AttachmentObject" token: type: string description: Token for subsequent request readOnly: true SuspendedTicketsExportResponse: type: object properties: export: type: object properties: status: type: string readOnly: true view_id: type: string readOnly: true SuspendedTicketsResponse: type: object properties: suspended_tickets: type: array items: $ref: "#/components/schemas/SuspendedTicketObject" SystemFieldOptionObject: type: object properties: name: type: string description: Name of the system field option readOnly: true value: type: string description: Value of the system field option readOnly: true TagCountObject: type: object properties: refreshed_at: type: string description: The time that the count value was last refreshed readOnly: true value: type: integer description: The count of tags created in the last 24 hours readOnly: true TagCountResponse: type: object properties: count: $ref: "#/components/schemas/TagCountObject" TagListTagObject: type: object properties: count: type: integer description: The number of tags readOnly: true name: type: string description: A name for the tag TagUrlObject: type: object properties: url: type: string description: The url associated to the api request readOnly: true TagsByObjectIdResponse: type: object properties: tags: type: array description: An array of strings items: type: string required: - tags TargetBasecamp: type: object properties: message_id: type: string description: Can be filled if it is a "message" resource password: type: string description: The 37Signals password for the Basecamp account (only writable) project_id: type: string description: The ID of the project in Basecamp where updates should be pushed resource: type: string description: '"todo" or "message"' target_url: type: string description: The URL of your Basecamp account, including protocol and path todo_list_id: type: string description: Can be filled if it is a "todo" resource token: type: string description: Get the API token from My info > Show your tokens > Token for feed readers or the Basecamp API in your Basecamp account username: type: string description: The 37Signals username of the account you use to log in to Basecamp required: - target_url - token - project_id - resource TargetCampfire: type: object properties: preserve_format: type: boolean room: type: string ssl: type: boolean subdomain: type: string token: type: string required: - subdomain - room - token TargetClickatell: type: object properties: api_id: type: string attribute: type: string description: Read-only from: type: string method: type: string description: Read-only password: type: string description: only writable target_url: type: string description: Read-only to: type: string us_small_business_account: type: string username: type: string required: - username - password - api_id - to TargetCommonFields: type: object properties: active: type: boolean description: Whether or not the target is activated created_at: type: string format: date-time description: The time the target was created readOnly: true id: type: integer description: Automatically assigned when created readOnly: true title: type: string description: A name for the target type: type: string description: A pre-defined target, such as "basecamp_target". See the additional attributes for the type that follow required: - title - type TargetEmail: type: object properties: email: type: string subject: type: string required: - email - subject TargetFailureObject: type: object properties: consecutive_failure_count: type: integer description: Number of times the target failed consecutively readOnly: true created_at: type: string format: date-time description: Time of the failure readOnly: true id: type: integer description: The ID of the target failure readOnly: true raw_request: type: string description: The raw message of the target request readOnly: true raw_response: type: string description: The raw response of the failure readOnly: true status_code: type: integer description: HTTP status code of the target failure readOnly: true target_name: type: string description: Name of the target failure readOnly: true url: type: string description: The API url of the failure record readOnly: true TargetFailureResponse: type: object properties: target_failure: $ref: "#/components/schemas/TargetFailureObject" TargetFailuresResponse: type: object properties: target_failures: type: array items: $ref: "#/components/schemas/TargetFailureObject" TargetFlowdock: type: object properties: api_token: type: string required: - api_token TargetGetSatisfaction: type: object properties: account_name: type: string email: type: string password: type: string description: only writable target_url: type: string required: - email - password - account_name TargetHTTP: type: object properties: content_type: type: string description: '"application/json", "application/xml", or "application/x-www-form-urlencoded"' method: type: string description: '"get", "patch", "put", "post", or "delete"' password: type: string description: only writable target_url: type: string username: type: string required: - target_url - method - content_type TargetJira: type: object properties: password: type: string description: only writable target_url: type: string username: type: string required: - target_url - username - password TargetObject: type: object allOf: - $ref: "#/components/schemas/TargetCommonFields" - oneOf: - $ref: "#/components/schemas/TargetBasecamp" - $ref: "#/components/schemas/TargetCampfire" - $ref: "#/components/schemas/TargetClickatell" - $ref: "#/components/schemas/TargetEmail" - $ref: "#/components/schemas/TargetFlowdock" - $ref: "#/components/schemas/TargetGetSatisfaction" - $ref: "#/components/schemas/TargetJira" - $ref: "#/components/schemas/TargetPivotal" - $ref: "#/components/schemas/TargetTwitter" - $ref: "#/components/schemas/TargetURL" - $ref: "#/components/schemas/TargetHTTP" - $ref: "#/components/schemas/TargetYammer" additionalProperties: true TargetPivotal: type: object properties: owner_by: type: string project_id: type: string requested_by: type: string story_labels: type: string story_title: type: string story_type: type: string token: type: string required: - token - project_id - story_type - story_title TargetResponse: type: object properties: target: $ref: "#/components/schemas/TargetObject" TargetTwitter: type: object properties: secret: type: string description: only writable token: type: string TargetURL: type: object properties: attribute: type: string method: type: string description: '"get"' password: type: string description: only writable target_url: type: string username: type: string required: - target_url - attribute TargetYammer: type: object properties: group_id: type: string token: type: string TargetsResponse: type: object properties: targets: type: array items: $ref: "#/components/schemas/TargetObject" TicketAuditObject: type: object properties: author_id: type: integer description: The user who created the audit readOnly: true created_at: type: string format: date-time description: The time the audit was created readOnly: true events: type: array description: An array of the events that happened in this audit. See the [Ticket Audit events reference](/documentation/ticketing/reference-guides/ticket-audit-events-reference) items: type: object additionalProperties: true id: type: integer description: Automatically assigned when creating audits readOnly: true metadata: type: object description: Metadata for the audit, custom and system data additionalProperties: true readOnly: true ticket_id: type: integer description: The ID of the associated ticket readOnly: true via: $ref: "#/components/schemas/TicketAuditViaObject" TicketAuditResponse: type: object properties: audit: $ref: "#/components/schemas/TicketAuditObject" TicketAuditViaObject: type: object description: Describes how the object was created. See the [Via object reference](/documentation/ticketing/reference-guides/via-object-reference) properties: channel: type: string description: 'This tells you how the ticket or event was created. Examples: "web", "mobile", "rule", "system"' readOnly: true source: type: object description: For some channels a source object gives more information about how or why the ticket or event was created additionalProperties: true readOnly: true TicketAuditsCountResponse: type: object properties: count: type: object properties: refreshed_at: type: string format: date-time value: type: integer TicketAuditsResponse: type: object properties: after_cursor: type: string readOnly: true after_url: type: string readOnly: true audits: type: array items: $ref: "#/components/schemas/TicketAuditObject" before_cursor: type: string readOnly: true before_url: type: string readOnly: true TicketAuditsResponseNoneCursor: type: object properties: audits: type: array items: $ref: "#/components/schemas/TicketAuditObject" count: type: integer readOnly: true next_page: type: string nullable: true readOnly: true previous_page: type: string nullable: true readOnly: true TicketBulkImportRequest: type: object properties: tickets: type: array items: $ref: "#/components/schemas/TicketImportInput" TicketChatCommentRedactionResponse: type: object properties: chat_event: type: object description: Chat event object properties: id: type: integer description: Id assigned to the chat event object readOnly: true type: type: string description: Type of chat event readOnly: true value: type: object description: The value of the chat event object properties: chat_id: type: string description: Id of the chat session readOnly: true history: type: array description: Chat events within the chat session items: type: object additionalProperties: true visitor_id: type: string description: Id assigned to the visitor readOnly: true readOnly: true readOnly: true TicketCommentObject: type: object properties: attachments: type: array description: Attachments, if any. See [Attachment](/api-reference/ticketing/tickets/ticket-attachments/) items: $ref: "#/components/schemas/AttachmentObject" readOnly: true audit_id: type: integer description: The id of the ticket audit record. See [Show Audit](/api-reference/ticketing/tickets/ticket_audits/#show-audit) readOnly: true author_id: type: integer description: The id of the comment author. See [Author id](#author-id) body: type: string description: The comment string. See [Bodies](#bodies) created_at: type: string format: date-time description: The time the comment was created readOnly: true html_body: type: string description: The comment formatted as HTML. See [Bodies](#bodies) id: type: integer description: Automatically assigned when the comment is created readOnly: true metadata: type: object description: System information (web client, IP address, etc.) and comment flags, if any. See [Comment flags](#comment-flags) additionalProperties: true readOnly: true plain_body: type: string description: The comment presented as plain text. See [Bodies](#bodies) readOnly: true public: type: boolean description: true if a public comment; false if an internal note. The initial value set on ticket creation persists for any additional comment unless you change it type: type: string description: "`Comment` or `VoiceComment`. The JSON object for adding voice comments to tickets is different. See [Adding voice comments to tickets](/documentation/ticketing/managing-tickets/adding-voice-comments-to-tickets)" readOnly: true uploads: type: array description: List of tokens received from [uploading files](/api-reference/ticketing/tickets/ticket-attachments/#upload-files) for comment attachments. The files are attached by creating or updating tickets with the tokens. See [Attaching files](/api-reference/ticketing/tickets/tickets/#attaching-files) in Tickets items: type: string via: $ref: "#/components/schemas/TicketAuditViaObject" TicketCommentResponse: type: object properties: comment: $ref: "#/components/schemas/TicketCommentObject" TicketCommentsCountResponse: type: object properties: count: type: object properties: refreshed_at: type: string format: date-time value: type: integer TicketCommentsResponse: type: object properties: comments: type: array items: $ref: "#/components/schemas/TicketCommentObject" TicketCreateInput: type: object allOf: - $ref: "#/components/schemas/TicketUpdateInput" - type: object properties: brand_id: type: integer description: Enterprise only. The id of the brand this ticket is associated with collaborators: type: array description: POST requests only. Users to add as cc's when creating a ticket. See [Setting Collaborators](/documentation/ticketing/managing-tickets/creating-and-updating-tickets#setting-collaborators) items: $ref: "#/components/schemas/CollaboratorObject" email_cc_ids: type: array description: The ids of agents or end users currently CC'ed on the ticket. See [CCs and followers resources](https://support.zendesk.com/hc/en-us/articles/360020585233) in the Support Help Center items: type: integer follower_ids: type: array description: The ids of agents currently following the ticket. See [CCs and followers resources](https://support.zendesk.com/hc/en-us/articles/360020585233) items: type: integer macro_ids: type: array description: POST requests only. List of macro IDs to be recorded in the ticket audit items: type: integer raw_subject: type: string description: 'The dynamic content placeholder, if present, or the "subject" value, if not. See [Dynamic Content Items](/api-reference/ticketing/ticket-management/dynamic_content/) ' recipient: type: string description: The original recipient e-mail address of the ticket submitter_id: type: integer description: The user who submitted the ticket. The submitter always becomes the author of the first comment on the ticket ticket_form_id: type: integer description: Enterprise only. The id of the ticket form to render for the ticket via: $ref: "#/components/schemas/ViaObject" via_followup_source_id: type: integer description: POST requests only. The id of a closed ticket when creating a follow-up ticket. See [Creating a follow-up ticket](/documentation/ticketing/managing-tickets/creating-and-updating-tickets#creating-a-follow-up-ticket) required: - comment TicketCreateRequest: type: object properties: ticket: $ref: "#/components/schemas/TicketCreateInput" TicketCreateVoicemailTicketInput: type: object properties: comment: $ref: "#/components/schemas/TicketCommentObject" priority: type: string description: The urgency with which the ticket should be addressed. enum: - urgent - high - normal - low via_id: type: integer description: Required for Create Ticket operation enum: - 44 - 45 - 46 voice_comment: type: object description: Required if creating voicemail ticket allOf: - $ref: "#/components/schemas/TicketCreateVoicemailTicketVoiceCommentInput" TicketCreateVoicemailTicketRequest: type: object properties: display_to_agent: type: integer description: Optional value such as the ID of the agent that will see the newly created ticket. ticket: type: object description: Ticket object that lists the values to set when the ticket is created allOf: - $ref: "#/components/schemas/TicketCreateVoicemailTicketInput" TicketCreateVoicemailTicketVoiceCommentInput: type: object properties: answered_by_id: type: integer description: The agent who answered the call call_duration: type: integer description: Duration in seconds of the call from: type: string description: Incoming phone number location: type: string description: Location of the caller (optional) recording_url: type: string description: Incoming phone number started_at: type: string format: date-time description: "[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp of the call starting time" to: type: string description: Dialed phone number transcription_text: type: string description: Transcription of the call (optional) TicketFieldCountResponse: type: object properties: count: type: object properties: refreshed_at: type: string format: date-time value: type: integer TicketFieldCustomStatusObject: type: object properties: active: type: boolean description: If true, if the custom status is set to active. If false, the custom status is set to inactive agent_label: type: string description: The label displayed to agents created_at: type: string format: date-time description: The date and time at which the custom ticket status was created readOnly: true default: type: boolean description: If true, the custom status is set to default. If false, the custom status is set to non-default description: type: string description: The description of when the user should select this custom ticket status end_user_description: type: string description: The description displayed to end users end_user_label: type: string description: The label displayed to end users id: type: integer description: Automatically assigned when the custom ticket status is created readOnly: true status_category: type: string description: The status category the custom ticket status belongs to enum: - new - open - pending - hold - solved updated_at: type: string format: date-time description: The date and time at which the custom ticket status was last updated readOnly: true TicketFieldObject: type: object properties: active: type: boolean description: Whether this field is available agent_can_edit: type: boolean description: Whether this field is editable by agents readOnly: true agent_description: type: string description: A description of the ticket field that only agents can see collapsed_for_agents: type: boolean description: If true, the field is shown to agents by default. If false, the field is hidden alongside infrequently used fields. Classic interface only created_at: type: string format: date-time description: The time the custom ticket field was created readOnly: true creator_app_name: type: string description: Name of the app that created the ticket field, or a null value if no app created the ticket field creator_user_id: type: integer description: The id of the user that created the ticket field, or a value of "-1" if an app created the ticket field custom_field_options: type: array description: Required and presented for a custom ticket field of type "multiselect" or "tagger" items: $ref: "#/components/schemas/CustomFieldOptionObject" custom_statuses: type: array description: List of customized ticket statuses. Only presented for a system ticket field of type "custom_status" items: $ref: "#/components/schemas/TicketFieldCustomStatusObject" readOnly: true description: type: string description: Describes the purpose of the ticket field to users editable_in_portal: type: boolean description: Whether this field is editable by end users in Help Center id: type: integer description: Automatically assigned when created readOnly: true position: type: integer description: The relative position of the ticket field on a ticket. Note that for accounts with ticket forms, positions are controlled by the different forms raw_description: type: string description: The dynamic content placeholder if present, or the `description` value if not. See [Dynamic Content](/api-reference/ticketing/ticket-management/dynamic_content/) raw_title: type: string description: The dynamic content placeholder if present, or the `title` value if not. See [Dynamic Content](/api-reference/ticketing/ticket-management/dynamic_content/) raw_title_in_portal: type: string description: The dynamic content placeholder if present, or the "title_in_portal" value if not. See [Dynamic Content](/api-reference/ticketing/ticket-management/dynamic_content/) regexp_for_validation: type: string description: For "regexp" fields only. The validation pattern for a field value to be deemed valid nullable: true relationship_filter: type: object description: A filter definition that allows your autocomplete to filter down results relationship_target_type: type: string description: A representation of what type of object the field references. Options are "zen:user", "zen:organization", "zen:ticket", or "zen:custom_object:{key}" where key is a custom object key. For example "zen:custom_object:apartment". removable: type: boolean description: If false, this field is a system field that must be present on all tickets readOnly: true required: type: boolean description: If true, agents must enter a value in the field to change the ticket status to solved required_in_portal: type: boolean description: If true, end users must enter a value in the field to create the request sub_type_id: type: integer description: For system ticket fields of type "priority" and "status". Defaults to 0. A "priority" sub type of 1 removes the "Low" and "Urgent" options. A "status" sub type of 1 adds the "On-Hold" option system_field_options: type: array description: Presented for a system ticket field of type "tickettype", "priority" or "status" items: $ref: "#/components/schemas/SystemFieldOptionObject" readOnly: true tag: type: string description: For "checkbox" fields only. A tag added to tickets when the checkbox field is selected nullable: true title: type: string description: The title of the ticket field title_in_portal: type: string description: The title of the ticket field for end users in Help Center type: type: string description: System or custom field type. Editable for custom field types and only on creation. See [Create Ticket Field](#create-ticket-field) updated_at: type: string format: date-time description: The time the custom ticket field was last updated readOnly: true url: type: string description: The URL for this resource readOnly: true visible_in_portal: type: boolean description: Whether this field is visible to end users in Help Center required: - type - title TicketFieldResponse: type: object properties: ticket_field: $ref: "#/components/schemas/TicketFieldObject" TicketFieldsResponse: type: object properties: ticket_fields: type: array items: $ref: "#/components/schemas/TicketFieldObject" TicketFormObject: type: object properties: active: type: boolean description: If the form is set as active agent_conditions: type: array description: Array of condition sets for agent workspaces items: type: object additionalProperties: true created_at: type: string format: date-time description: The time the ticket form was created readOnly: true default: type: boolean description: Is the form the default form for this account deleted_at: type: string format: date-time description: The time the ticket form was deleted readOnly: true display_name: type: string description: The name of the form that is displayed to an end user end_user_conditions: type: array description: | Array of condition sets for end user products. Sending an empty array `[]` removes the end user conditions from the form. items: type: object additionalProperties: true end_user_visible: type: boolean description: Is the form visible to the end user id: type: integer description: Automatically assigned when creating ticket form readOnly: true in_all_brands: type: boolean description: Is the form available for use in all brands on this account name: type: string description: The name of the form position: type: integer description: The position of this form among other forms in the account, i.e. dropdown raw_display_name: type: string description: The dynamic content placeholder, if present, or the "display_name" value, if not. See [Dynamic Content Items](/api-reference/ticketing/ticket-management/dynamic_content/) raw_name: type: string description: The dynamic content placeholder, if present, or the "name" value, if not. See [Dynamic Content Items](/api-reference/ticketing/ticket-management/dynamic_content/) restricted_brand_ids: type: array description: ids of all brands that this ticket form is restricted to items: type: integer readOnly: true ticket_field_ids: type: array description: ids of all ticket fields which are in this ticket form. The products use the order of the ids to show the field values in the tickets items: type: integer updated_at: type: string format: date-time description: The time of the last update of the ticket form readOnly: true url: type: string description: URL of the ticket form readOnly: true required: - name TicketFormResponse: type: object properties: ticket_form: $ref: "#/components/schemas/TicketFormObject" TicketFormStatusObject: type: object properties: custom_status_id: type: integer description: The id of the associated custom status id: type: string description: Automatically assigned when creating a ticket form readOnly: true ticket_form_id: type: integer description: The id of the associated ticket form TicketFormStatusesCreateParams: type: object properties: custom_status_id: type: integer required: - custom_status_id TicketFormStatusesParams: type: object properties: ticket_form_status: type: array items: $ref: "#/components/schemas/TicketFormStatusesCreateParams" required: - ticket_form_status TicketFormStatusesResponse: type: object properties: ticket_form_statuses: type: array items: $ref: "#/components/schemas/TicketFormStatusObject" maxItems: 1 TicketFormStatusesUpdateParams: type: object properties: _destroy: type: string description: If set to a value of \"1\" and an id value is passed, the server will delete the record custom_status_id: type: integer id: type: string TicketFormsResponse: type: object properties: ticket_forms: type: array items: $ref: "#/components/schemas/TicketFormObject" TicketImportInput: type: object properties: assignee_id: type: integer description: The agent currently assigned to the ticket comments: type: array description: The conversation between requesters, collaborators, and agents items: allOf: - type: object properties: value: type: string description: The comment string value - $ref: "#/components/schemas/TicketCommentObject" additionalProperties: true description: type: string description: Read-only first comment on the ticket. When [creating a ticket](#create-ticket), use `comment` to set the description. See [Description and first comment](#description-and-first-comment) requester_id: type: integer description: The user who requested this ticket subject: type: string description: The value of the subject field for this ticket tags: type: array description: The array of tags applied to this ticket items: type: string TicketImportRequest: type: object properties: ticket: $ref: "#/components/schemas/TicketImportInput" TicketMergeInput: type: object properties: ids: type: array description: Ids of tickets to merge into the target ticket items: type: integer source_comment: type: string description: Private comment to add to the source ticket source_comment_is_public: type: boolean description: Whether comment in source tickets are public or private target_comment: type: string description: Private comment to add to the target ticket target_comment_is_public: type: boolean description: Whether comment in target ticket is public or private required: - ids TicketMetricEventBaseObject: title: Ticket Metric Events type: object properties: deleted: type: boolean description: If true, the event has been deleted readOnly: true id: type: integer description: Automatically assigned when the record is created readOnly: true instance_id: type: integer description: The instance of the metric associated with the event. See [instance_id](#instance_id) readOnly: true metric: type: string description: The metric being tracked enum: - agent_work_time - pausable_update_time - periodic_update_time - reply_time - requester_wait_time - resolution_time - group_ownership_time readOnly: true ticket_id: type: integer description: Id of the associated ticket readOnly: true time: type: string format: date-time description: The time the event occurred readOnly: true type: type: string description: The type of the metric event. See [Ticket metric event types reference](/documentation/ticketing/reference-guides/ticket-metric-event-types-reference) enum: - activate - pause - fulfill - apply_sla - apply_group_sla - breach - update_status - measure readOnly: true TicketMetricEventBreachObject: title: Ticket Metric Event type: object allOf: - $ref: "#/components/schemas/TicketMetricEventBaseObject" - type: object properties: deleted: type: boolean description: Available if `type` is `breach`. In general, you can ignore any breach event when `deleted` is true. See [deleted](#deleted) readOnly: true TicketMetricEventGroupSLAObject: title: Ticket Metric Event type: object allOf: - $ref: "#/components/schemas/TicketMetricEventBaseObject" - type: object properties: group_sla: type: object description: Available if `type` is "apply_group_sla". The Group SLA policy and target being enforced on the ticket and metric in question, if any. See [group_sla](#group_sla) readOnly: true TicketMetricEventSLAObject: title: Ticket Metric Event type: object allOf: - $ref: "#/components/schemas/TicketMetricEventBaseObject" - type: object properties: sla: type: object description: Available if `type` is `apply_sla`. The SLA policy and target being enforced on the ticket and metric in question, if any. See [sla](#sla) readOnly: true TicketMetricEventUpdateStatusObject: title: Ticket Metric Event type: object allOf: - $ref: "#/components/schemas/TicketMetricEventBaseObject" - type: object properties: status: type: object description: Available if `type` is `update_status`. Minutes since the metric has been open. See [status](#status) readOnly: true TicketMetricEventsResponse: type: object allOf: - type: object properties: ticket_metric_events: type: array items: $ref: "#/components/schemas/TicketMetricEventBaseObject" - type: object properties: count: type: integer end_time: type: integer next_page: type: string TicketMetricObject: type: object properties: agent_wait_time_in_minutes: type: object description: Number of minutes the agent spent waiting during calendar and business hours allOf: - $ref: "#/components/schemas/TicketMetricTimeObject" readOnly: true assigned_at: type: string format: date-time description: When the ticket was assigned readOnly: true assignee_stations: type: integer description: Number of assignees the ticket had readOnly: true assignee_updated_at: type: string format: date-time description: When the assignee last updated the ticket readOnly: true created_at: type: string format: date-time description: When the record was created readOnly: true custom_status_updated_at: type: string format: date-time description: The date and time the ticket's custom status was last updated readOnly: true first_resolution_time_in_minutes: type: object description: Number of minutes to the first resolution time during calendar and business hours allOf: - $ref: "#/components/schemas/TicketMetricTimeObject" readOnly: true full_resolution_time_in_minutes: type: object description: Number of minutes to the full resolution during calendar and business hours allOf: - $ref: "#/components/schemas/TicketMetricTimeObject" readOnly: true group_stations: type: integer description: Number of groups the ticket passed through readOnly: true id: type: integer description: Automatically assigned when the client is created readOnly: true initially_assigned_at: type: string format: date-time description: When the ticket was initially assigned readOnly: true latest_comment_added_at: type: string format: date-time description: When the latest comment was added readOnly: true on_hold_time_in_minutes: type: object description: Number of minutes on hold allOf: - $ref: "#/components/schemas/TicketMetricTimeObject" readOnly: true reopens: type: integer description: Total number of times the ticket was reopened readOnly: true replies: type: integer description: The number of public replies added to a ticket by an agent readOnly: true reply_time_in_minutes: type: object description: Number of minutes to the first reply during calendar and business hours allOf: - $ref: "#/components/schemas/TicketMetricTimeObject" readOnly: true reply_time_in_seconds: type: object description: Number of seconds to the first reply during calendar hours, only available for Messaging tickets allOf: - $ref: "#/components/schemas/TicketMetricTimeObject" readOnly: true requester_updated_at: type: string format: date-time description: When the requester last updated the ticket readOnly: true requester_wait_time_in_minutes: type: object description: Number of minutes the requester spent waiting during calendar and business hours allOf: - $ref: "#/components/schemas/TicketMetricTimeObject" readOnly: true solved_at: type: string format: date-time description: When the ticket was solved readOnly: true status_updated_at: type: string format: date-time description: When the status of the ticket was last updated readOnly: true ticket_id: type: integer description: Id of the associated ticket readOnly: true updated_at: type: string format: date-time description: When the record was last updated readOnly: true url: type: string description: The API url of the ticket metric readOnly: true TicketMetricTimeObject: type: object properties: business: type: integer description: Time in business hours readOnly: true calendar: type: integer description: Time in calendar hours readOnly: true TicketMetricsByTicketMetricIdResponse: type: object properties: ticket_metric: type: array items: $ref: "#/components/schemas/TicketMetricObject" TicketMetricsResponse: type: object properties: ticket_metrics: type: array items: $ref: "#/components/schemas/TicketMetricObject" TicketObject: type: object properties: allow_attachments: type: boolean description: Permission for agents to add add attachments to a comment. Defaults to true readOnly: true allow_channelback: type: boolean description: Is false if channelback is disabled, true otherwise. Only applicable for channels framework ticket readOnly: true assignee_email: type: string description: Write only. The email address of the agent to assign the ticket to writeOnly: true assignee_id: type: integer description: The agent currently assigned to the ticket attribute_value_ids: type: array description: Write only. An array of the IDs of attribute values to be associated with the ticket items: type: integer writeOnly: true brand_id: type: integer description: The id of the brand this ticket is associated with. See [Setting up multiple brands](https://support.zendesk.com/hc/en-us/articles/4408829476378) collaborator_ids: type: array description: The ids of users currently CC'ed on the ticket items: type: integer collaborators: type: array description: POST requests only. Users to add as cc's when creating a ticket. See [Setting Collaborators](/documentation/ticketing/managing-tickets/creating-and-updating-tickets#setting-collaborators) items: $ref: "#/components/schemas/CollaboratorObject" comment: type: object description: Write only. An object that adds a comment to the ticket. See [Ticket comments](/api-reference/ticketing/tickets/ticket_comments/). To include an attachment with the comment, see [Attaching files](/documentation/ticketing/managing-tickets/creating-and-updating-tickets/#attaching-files). A ticket can contain up to 5000 comments in total, including both public and private comments. Once this limit is reached, any additional attempts to add comments results in a 422 error. The ticket can still be updated in other ways, provided that no new comments are added. writeOnly: true created_at: type: string format: date-time description: When this record was created readOnly: true custom_fields: type: array description: Custom fields for the ticket. See [Setting custom field values](/documentation/ticketing/managing-tickets/creating-and-updating-tickets#setting-custom-field-values) items: type: object properties: id: type: integer description: The id of the custom field value: description: The value of the custom field nullable: true oneOf: - type: string - type: integer - type: boolean - type: array items: type: string - type: number custom_status_id: type: integer description: The custom ticket status id of the ticket. See [custom ticket statuses](#custom-ticket-statuses) description: type: string description: "Read-only first comment on the ticket. When [creating a ticket](#create-ticket), use `comment` to set the description. See [Description and first comment](#description-and-first-comment) " readOnly: true due_at: type: string format: date-time description: If this is a ticket of type "task" it has a due date. Due date format uses [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) format nullable: true email_cc_ids: type: array description: The ids of agents or end users currently CC'ed on the ticket. Ignored when [CCs and followers](https://support.zendesk.com/hc/en-us/articles/360020585233) is not enabled items: type: integer email_ccs: type: object description: Write only. An array of objects that represents agent or end users email CCs to add or delete from the ticket. See [Setting email CCs](/documentation/ticketing/managing-tickets/creating-and-updating-tickets/#setting-email-ccs). Ignored when [CCs and followers](https://support.zendesk.com/hc/en-us/articles/360020585233) is not enabled writeOnly: true external_id: type: string description: An id you can use to link Zendesk Support tickets to local records follower_ids: type: array description: The ids of agents currently following the ticket. Ignored when [CCs and followers](https://support.zendesk.com/hc/en-us/articles/360020585233) is not enabled items: type: integer followers: type: object description: Write only. An array of objects that represents agent followers to add or delete from the ticket. See [Setting followers](/documentation/ticketing/managing-tickets/creating-and-updating-tickets/#setting-followers). Ignored when [CCs and followers](https://support.zendesk.com/hc/en-us/articles/360020585233) is not enabled writeOnly: true followup_ids: type: array description: The ids of the followups created from this ticket. Ids are only visible once the ticket is closed items: type: integer readOnly: true forum_topic_id: type: integer description: The topic in the Zendesk Web portal this ticket originated from, if any. The Web portal is deprecated readOnly: true from_messaging_channel: type: boolean description: If true, the ticket's [via type](/documentation/ticketing/reference-guides/via-object-reference/) is a messaging channel. readOnly: true generated_timestamp: type: integer description: A Unix timestamp that represents the most accurate reading of when this record was last updated. It is updated for all ticket updates, including system updates readOnly: true group_id: type: integer description: The group this ticket is assigned to has_incidents: type: boolean description: Is true if a ticket is a problem type and has one or more incidents linked to it. Otherwise, the value is false. readOnly: true id: type: integer description: Automatically assigned when the ticket is created readOnly: true is_public: type: boolean description: Is true if any comments are public, false otherwise readOnly: true macro_id: type: integer description: Write only. A macro ID to be recorded in the ticket audit writeOnly: true macro_ids: type: array description: POST requests only. List of macro IDs to be recorded in the ticket audit items: type: integer metadata: type: object description: Write only. Metadata for the audit. In the `audit` object, the data is specified in the `custom` property of the `metadata` object. See [Setting Metadata](/documentation/ticketing/managing-tickets/creating-and-updating-tickets/#setting-metadata) writeOnly: true organization_id: type: integer description: The organization of the requester. You can only specify the ID of an organization associated with the requester. See [Organization Memberships](/api-reference/ticketing/organizations/organization_memberships/) priority: type: string description: The urgency with which the ticket should be addressed enum: - urgent - high - normal - low problem_id: type: integer description: For tickets of type "incident", the ID of the problem the incident is linked to raw_subject: type: string description: 'The dynamic content placeholder, if present, or the "subject" value, if not. See [Dynamic Content Items](/api-reference/ticketing/ticket-management/dynamic_content/) ' recipient: type: string description: The original recipient e-mail address of the ticket. Notification emails for the ticket are sent from this address requester: type: object description: Write only. See [Creating a ticket with a new requester](/documentation/ticketing/managing-tickets/creating-and-updating-tickets/#creating-a-ticket-with-a-new-requester) writeOnly: true requester_id: type: integer description: The user who requested this ticket safe_update: type: boolean description: Write only. Optional boolean. When true and an `update_stamp` date is included, protects against ticket update collisions and returns a message to let you know if one occurs. See [Protecting against ticket update collisions](/documentation/ticketing/managing-tickets/creating-and-updating-tickets/#protecting-against-ticket-update-collisions). A value of false has the same effect as true. Omit the property to force the updates to not be safe writeOnly: true satisfaction_rating: type: object description: The satisfaction rating of the ticket, if it exists, or the state of satisfaction, "offered" or "unoffered". The value is null for plan types that don't support CSAT additionalProperties: true readOnly: true sharing_agreement_ids: type: array description: The ids of the sharing agreements used for this ticket items: type: integer status: type: string description: | The state of the ticket. If your account has activated custom ticket statuses, this is the ticket's status category. See [custom ticket statuses](#custom-ticket-statuses) enum: - new - open - pending - hold - solved - closed subject: type: string description: "The value of the subject field for this ticket. See [Subject](/api-reference/ticketing/tickets/tickets/#subject) " submitter_id: type: integer description: The user who submitted the ticket. The submitter always becomes the author of the first comment on the ticket tags: type: array description: The array of tags applied to this ticket. Unless otherwise specified, the [set tag](/api-reference/ticketing/ticket-management/tags/#set-tags) behavior is used, which overwrites and replaces existing tags items: type: string ticket_form_id: type: integer description: Enterprise only. The id of the ticket form to render for the ticket type: type: string description: The type of this ticket enum: - problem - incident - question - task updated_at: type: string format: date-time description: When this record last got updated. It is updated only if the update generates a [ticket event](#incremental-ticket-event-export) readOnly: true updated_stamp: type: string description: Write only. Datetime of last update received from API. See the `safe_update` property writeOnly: true url: type: string description: The API url of this ticket readOnly: true via: type: object description: For more information, see the [Via object reference](/documentation/ticketing/reference-guides/via-object-reference) properties: channel: type: string description: 'This tells you how the ticket or event was created. Examples: "web", "mobile", "rule", "system" ' source: type: object description: "For some channels a source object gives more information about how or why the ticket or event was created " additionalProperties: true via_followup_source_id: type: integer description: POST requests only. The id of a closed ticket when creating a follow-up ticket. See [Creating a follow-up ticket](/documentation/ticketing/managing-tickets/creating-and-updating-tickets#creating-a-follow-up-ticket) via_id: type: integer description: Write only. For more information, see the [Via object reference](/documentation/ticketing/reference-guides/via-object-reference/) writeOnly: true voice_comment: type: object description: Write only. See [Creating voicemail ticket](/api-reference/voice/talk-partner-edition-api/reference/#creating-voicemail-tickets) writeOnly: true required: - requester_id TicketRelatedInformation: type: object properties: followup_source_ids: type: array items: type: string description: Sources to follow up from_archive: type: boolean description: Is true if the current ticket is archived incidents: type: integer description: A count of related incident occurrences jira_issue_ids: type: array items: type: string description: Associated jira issues topic_id: type: string description: Related topic in the Web portal (deprecated feature) nullable: true TicketResponse: type: object properties: ticket: $ref: "#/components/schemas/TicketObject" TicketSkipCreation: type: object properties: skip: $ref: "#/components/schemas/TicketSkipObject" TicketSkipObject: type: object properties: created_at: type: string format: date-time description: Time the skip was created readOnly: true id: type: integer description: Automatically assigned upon creation readOnly: true reason: type: string description: Reason for skipping the ticket readOnly: true ticket: type: object description: The skipped ticket. See the [Ticket object reference](/api-reference/ticketing/tickets/tickets/#json-format) allOf: - $ref: "#/components/schemas/TicketObject" ticket_id: type: integer description: ID of the skipped ticket readOnly: true updated_at: type: string format: date-time description: Time the skip was last updated readOnly: true user_id: type: integer description: ID of the skipping agent readOnly: true TicketSkipsResponse: type: object properties: skips: type: array items: $ref: "#/components/schemas/TicketSkipObject" TicketUpdateInput: type: object properties: additional_collaborators: type: array description: An array of numeric IDs, emails, or objects containing name and email properties. See [Setting Collaborators](/api-reference/ticketing/tickets/tickets/#setting-collaborators). An email notification is sent to them when the ticket is updated items: $ref: "#/components/schemas/CollaboratorObject" assignee_email: type: string format: email description: The email address of the agent to assign the ticket to assignee_id: type: integer description: The agent currently assigned to the ticket attribute_value_ids: type: array description: An array of the IDs of attribute values to be associated with the ticket items: type: integer collaborator_ids: type: array description: The ids of users currently CC'ed on the ticket items: type: integer comment: $ref: "#/components/schemas/TicketCommentObject" custom_fields: type: array description: Custom fields for the ticket. See [Setting custom field values](/documentation/ticketing/managing-tickets/creating-and-updating-tickets#setting-custom-field-values) items: type: object properties: id: type: integer description: The id of the custom field value: oneOf: - type: string - type: integer - type: boolean - type: array items: type: string - type: number description: The value of the custom field custom_status_id: type: integer description: The custom ticket status id of the ticket. See [custom ticket statuses](#custom-ticket-statuses) due_at: type: string format: date-time description: If this is a ticket of type "task" it has a due date. Due date format uses [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) format. nullable: true email_ccs: type: array description: An array of objects that represent agent or end users email CCs to add or delete from the ticket. See [Setting email CCs](/documentation/ticketing/managing-tickets/creating-and-updating-tickets#setting-email-ccs) items: $ref: "#/components/schemas/EmailCCObject" external_id: type: string description: An id you can use to link Zendesk Support tickets to local records followers: type: array description: An array of objects that represent agent followers to add or delete from the ticket. See [Setting followers](/documentation/ticketing/managing-tickets/creating-and-updating-tickets#setting-followers) items: $ref: "#/components/schemas/FollowerObject" group_id: type: integer description: The group this ticket is assigned to organization_id: type: integer description: The organization of the requester. You can only specify the ID of an organization associated with the requester. See [Organization Memberships](/api-reference/ticketing/organizations/organization_memberships/) priority: type: string description: The urgency with which the ticket should be addressed. enum: - urgent - high - normal - low problem_id: type: integer description: For tickets of type "incident", the ID of the problem the incident is linked to requester_id: type: integer description: The user who requested this ticket safe_update: type: boolean description: Optional boolean. Prevents updates with outdated ticket data (`updated_stamp` property required when true) sharing_agreement_ids: type: array description: An array of the numeric IDs of sharing agreements. Note that this replaces any existing agreements items: type: integer status: type: string description: | The state of the ticket. If your account has activated custom ticket statuses, this is the ticket's status category. See [custom ticket statuses](#custom-ticket-statuses). enum: - new - open - pending - hold - solved - closed subject: type: string description: The value of the subject field for this ticket tags: type: array description: The array of tags applied to this ticket items: type: string type: type: string description: The type of this ticket. enum: - problem - incident - question - task updated_stamp: type: string format: date-time description: Datetime of last update received from API. See the safe_update property TicketUpdateRequest: type: object properties: ticket: $ref: "#/components/schemas/TicketUpdateInput" TicketUpdateResponse: type: object properties: audit: $ref: "#/components/schemas/AuditObject" ticket: $ref: "#/components/schemas/TicketObject" TicketsCreateRequest: type: object properties: tickets: type: array items: $ref: "#/components/schemas/TicketCreateInput" TicketsUpdateManyRequestBody: type: object description: Arbitrary JSON payload for updating multiple tickets additionalProperties: true TicketsResponse: type: object properties: tickets: type: array items: $ref: "#/components/schemas/TicketObject" TimeBasedExportIncrementalTicketsResponse: type: object description: "See [Tickets](/api-reference/ticketing/tickets/tickets/) for a detailed example. " properties: count: type: integer end_of_stream: type: boolean end_time: type: integer next_page: type: string nullable: true tickets: type: array items: $ref: "#/components/schemas/TicketObject" TimeBasedExportIncrementalUsersResponse: type: object properties: count: type: integer end_of_stream: type: boolean end_time: type: integer next_page: type: string nullable: true users: type: array items: $ref: "#/components/schemas/UserObject" TrialAccountObject: type: object properties: name: type: string description: The name of the account subdomain: type: string description: The subdomain of the account url: type: string description: The URL of the account TrialAccountResponse: type: object properties: account: $ref: "#/components/schemas/TrialAccountObject" TriggerActionDefinitionObject: type: object properties: group: type: string nullable: type: boolean repeatable: type: boolean subject: type: string title: type: string type: type: string values: type: array items: type: object properties: enabled: type: boolean title: type: string value: type: string TriggerActionDiffObject: type: object properties: field: type: array description: An array of [change](#change) objects. items: $ref: "#/components/schemas/TriggerChangeObject" value: type: array description: An array of [change](#change) objects. items: $ref: "#/components/schemas/TriggerChangeObject" TriggerActionObject: type: object properties: field: type: string value: oneOf: - type: string - type: integer - type: array items: oneOf: - type: string - type: integer TriggerBatchRequest: type: object properties: active: type: boolean category_id: type: string id: type: string position: type: integer format: int64 required: - id TriggerBulkUpdateItem: type: object properties: active: type: boolean description: The active status of the ticket trigger (true or false) category_id: type: string description: The ID of the new category the ticket trigger is to be moved to id: type: integer description: The ID of the ticket trigger to update position: type: integer description: The new position of the ticket trigger required: - id TriggerBulkUpdateRequest: type: object properties: triggers: type: array items: $ref: "#/components/schemas/TriggerBulkUpdateItem" TriggerCategoriesResponse: type: object properties: trigger_categories: type: array items: type: object oneOf: - $ref: "#/components/schemas/TriggerCategoryRuleCounts" allOf: - $ref: "#/components/schemas/TriggerCategory" TriggerCategory: type: object properties: created_at: type: string readOnly: true id: type: string readOnly: true name: type: string position: type: integer format: int64 updated_at: type: string readOnly: true TriggerCategoryBatchRequest: type: object properties: id: type: string position: type: integer format: int64 required: - id - position TriggerCategoryId: type: string TriggerCategoryRequest: type: object properties: name: type: string position: type: integer format: int64 TriggerCategoryRequestRequired: type: object required: - name TriggerCategoryResponse: type: object properties: trigger_category: $ref: "#/components/schemas/TriggerCategory" TriggerCategoryRuleCounts: type: object properties: active_count: type: integer format: int64 inactive_count: type: integer format: int64 TriggerChangeObject: type: object properties: change: type: string description: One of `-`, `+`, `=` representing the type of change content: description: The value of the item it represents oneOf: - type: boolean - type: string - type: integer - type: array items: oneOf: - type: string - type: integer - type: boolean TriggerConditionDefinitionObjectAll: type: object properties: group: type: string nullable: type: boolean operators: type: array items: type: object properties: terminal: type: boolean title: type: string value: type: string repeatable: type: boolean subject: type: string title: type: string type: type: string values: type: array items: type: object properties: enabled: type: boolean title: type: string value: type: string TriggerConditionDefinitionObjectAny: type: object properties: group: type: string nullable: type: boolean operators: type: array items: type: object properties: terminal: type: boolean title: type: string value: type: string repeatable: type: boolean subject: type: string title: type: string type: type: string TriggerConditionDiffObject: type: object properties: field: type: array description: An array of [change](#change) objects items: $ref: "#/components/schemas/TriggerChangeObject" operator: type: array description: An array of [change](#change) objects items: $ref: "#/components/schemas/TriggerChangeObject" value: type: array description: An array of [change](#change) objects items: $ref: "#/components/schemas/TriggerChangeObject" TriggerConditionObject: type: object properties: field: type: string operator: type: string value: oneOf: - type: string - type: integer - type: array items: oneOf: - type: string - type: integer TriggerConditionsDiffObject: type: object properties: all: type: array items: $ref: "#/components/schemas/TriggerConditionDiffObject" nullable: true any: type: array items: $ref: "#/components/schemas/TriggerConditionDiffObject" nullable: true TriggerConditionsObject: type: object description: An object that describes the circumstances under which the trigger performs its actions. See [Conditions reference](/documentation/ticketing/reference-guides/conditions-reference) properties: all: type: array items: $ref: "#/components/schemas/TriggerConditionObject" nullable: true any: type: array items: $ref: "#/components/schemas/TriggerConditionObject" nullable: true TriggerDefinitionObject: type: object properties: actions: type: array items: $ref: "#/components/schemas/TriggerActionDefinitionObject" conditions_all: type: array items: $ref: "#/components/schemas/TriggerConditionDefinitionObjectAll" conditions_any: type: array items: $ref: "#/components/schemas/TriggerConditionDefinitionObjectAny" TriggerDefinitionResponse: type: object properties: definitions: $ref: "#/components/schemas/TriggerDefinitionObject" TriggerObject: type: object properties: actions: type: array description: An array of actions describing what the ticket trigger will do. See [Actions reference](/documentation/ticketing/reference-guides/actions-reference) items: $ref: "#/components/schemas/TriggerActionObject" active: type: boolean description: Whether the ticket trigger is active category_id: type: string description: The ID of the category the ticket trigger belongs to conditions: $ref: "#/components/schemas/TriggerConditionsObject" created_at: type: string description: The time the ticket trigger was created readOnly: true default: type: boolean description: If true, the ticket trigger is a standard trigger readOnly: true description: type: string description: The description of the ticket trigger id: type: integer description: Automatically assigned when created readOnly: true position: type: integer description: Position of the ticket trigger, determines the order they will execute in raw_title: type: string description: The raw format of the title of the ticket trigger title: type: string description: The title of the ticket trigger updated_at: type: string description: The time of the last update of the ticket trigger readOnly: true url: type: string description: The url of the ticket trigger readOnly: true required: - conditions - actions - title TriggerResponse: type: object properties: trigger: $ref: "#/components/schemas/TriggerObject" TriggerRevisionResponse: type: object properties: trigger_revision: type: object properties: author_id: type: integer created_at: type: string id: type: integer snapshot: type: object properties: actions: type: array items: $ref: "#/components/schemas/TriggerActionObject" active: type: boolean conditions: $ref: "#/components/schemas/TriggerConditionsObject" description: type: string nullable: true title: type: string url: type: string TriggerRevisionsResponse: type: object properties: after_cursor: type: string after_url: type: string before_cursor: type: string before_url: type: string count: type: integer trigger_revisions: type: array items: type: object properties: author_id: type: integer created_at: type: string diff: type: object properties: actions: type: array description: An array that contain [action diff objects](#Action Diffs) items: $ref: "#/components/schemas/TriggerActionDiffObject" active: type: array description: An array of [change](#change) objects items: $ref: "#/components/schemas/TriggerChangeObject" conditions: $ref: "#/components/schemas/TriggerConditionDiffObject" description: type: array description: An array of [change](#change) objects items: $ref: "#/components/schemas/TriggerChangeObject" source_id: type: integer description: ID of the source revision target_id: type: integer description: ID of the target revision title: type: array description: An array of [change](#change) objects items: $ref: "#/components/schemas/TriggerChangeObject" id: type: integer snapshot: $ref: "#/components/schemas/TriggerSnapshotObject" url: type: string TriggerSnapshotObject: type: object properties: actions: type: array description: An array of [Actions](#actions) describing what the ticket trigger will do items: $ref: "#/components/schemas/TriggerActionObject" active: type: boolean description: Whether the ticket trigger is active conditions: $ref: "#/components/schemas/TriggerConditionsObject" description: type: string description: The description of the ticket trigger nullable: true title: type: string description: The title of the ticket trigger TriggerWithCategoryRequest: type: object properties: trigger: allOf: - $ref: "#/components/schemas/TriggerObject" - oneOf: - $ref: "#/components/schemas/TriggerCategory" - $ref: "#/components/schemas/TriggerCategoryId" TriggersResponse: type: object properties: count: type: integer next_page: type: string nullable: true previous_page: type: string nullable: true triggers: type: array items: $ref: "#/components/schemas/TriggerObject" TwitterChannelObject: title: Monitored X handles type: object properties: allow_reply: type: boolean description: If replies are allowed for this handle readOnly: true avatar_url: type: string description: The profile image url of the handle readOnly: true brand_id: type: integer description: What brand the handle is associated with readOnly: true can_reply: type: boolean description: If replies are allowed for this handle readOnly: true created_at: type: string format: date-time description: The time the handle was created readOnly: true id: type: integer description: Automatically assigned upon creation readOnly: true name: type: string description: The profile name of the handle readOnly: true screen_name: type: string description: The X handle readOnly: true twitter_user_id: type: integer description: The country's code readOnly: true updated_at: type: string format: date-time description: The time of the last update of the handle readOnly: true required: - id - screen_name - twitter_user_id TwitterChannelResponse: type: object properties: monitored_twitter_handle: $ref: "#/components/schemas/TwitterChannelObject" TwitterChannelTwicketStatusResponse: type: object properties: statuses: type: array items: type: object properties: favorited: type: boolean id: type: integer retweeted: type: boolean user_followed: type: boolean TwitterChannelsResponse: type: object properties: monitored_twitter_handles: type: array items: $ref: "#/components/schemas/TwitterChannelObject" UpdateResourceResult: type: object properties: action: type: string description: 'the action the job attempted (`"action": "update"`) ' id: type: integer description: the id of the resource the job attempted to update status: type: string description: 'the status (`"status": "Updated"`) ' success: type: boolean description: 'whether the action was successful or not (`"success": true`) ' required: - id - action - success - status UpdateTicketFormStatusesParams: type: object properties: ticket_form_status: type: array items: $ref: "#/components/schemas/TicketFormStatusesUpdateParams" required: - ticket_form_status UrlObject: type: object properties: url: type: string readOnly: true UserCreateInput: type: object properties: agent_brand_ids: type: array items: type: integer custom_role_id: type: integer email: type: string external_id: type: string identities: type: array items: type: object properties: type: type: string value: type: string required: - type - value name: type: string organization: type: object properties: name: type: string required: - name organization_id: type: integer role: type: string required: - name - email UserFieldObject: type: object allOf: - $ref: "#/components/schemas/CustomFieldObject" UserFieldResponse: type: object properties: user_field: $ref: "#/components/schemas/UserFieldObject" UserFieldsResponse: type: object properties: count: type: integer description: Total count of records retrieved readOnly: true next_page: type: string description: URL of the next page nullable: true readOnly: true previous_page: type: string description: URL of the previous page nullable: true readOnly: true user_fields: type: array items: $ref: "#/components/schemas/UserFieldObject" UserForAdmin: title: Users type: object properties: active: type: boolean description: false if the user has been deleted readOnly: true alias: type: string description: An alias displayed to end users chat_only: type: boolean description: Whether or not the user is a chat-only agent readOnly: true created_at: type: string format: datetime description: The time the user was created readOnly: true custom_role_id: type: integer description: A custom role if the user is an agent on the Enterprise plan or above nullable: true default_group_id: type: integer description: The id of the user's default group details: type: string description: Any details you want to store about the user, such as an address email: type: string description: The user's primary email address. *Writeable on create only. On update, a secondary email is added. See [Email Address](#email-address) external_id: type: string description: 'A unique identifier from another system. The API treats the id as case insensitive. Example: "ian1" and "IAN1" are the same value.' nullable: true iana_time_zone: type: string description: The time zone for the user readOnly: true id: type: integer description: Automatically assigned when the user is created readOnly: true last_login_at: type: string format: datetime description: | Last time the user signed in to Zendesk Support or made an API request using an API token or basic authentication readOnly: true locale: type: string description: The user's locale. A BCP-47 compliant tag for the locale. If both "locale" and "locale_id" are present on create or update, "locale_id" is ignored and only "locale" is used. locale_id: type: integer description: The user's language identifier moderator: type: boolean description: Designates whether the user has forum moderation capabilities name: type: string description: The user's name notes: type: string description: Any notes you want to store about the user only_private_comments: type: boolean description: true if the user can only create private comments organization_id: type: integer description: The id of the user's organization. If the user has more than one [organization memberships](/api-reference/ticketing/organizations/organization_memberships/), the id of the user's default organization. If updating, see [Organization ID](#organization-id) nullable: true phone: type: string description: The user's primary phone number. See [Phone Number](#phone-number) below nullable: true photo: type: object description: The user's profile picture represented as an [Attachment](/api-reference/ticketing/tickets/ticket-attachments/) object additionalProperties: true nullable: true remote_photo_url: type: string description: A URL pointing to the user's profile picture. report_csv: type: boolean description: | This parameter is inert and has no effect. It may be deprecated in the future. Previously, this parameter determined whether a user could access a CSV report in a legacy Guide dashboard. This dashboard has been removed. See [Announcing Guide legacy reporting upgrade to Explore](https://support.zendesk.com/hc/en-us/articles/4762263171610-Announcing-Guide-legacy-reporting-upgrade-to-Explore-) readOnly: true restricted_agent: type: boolean description: If the agent has any restrictions; false for admins and unrestricted agents, true for other agents role: type: string description: The user's role. Possible values are "end-user", "agent", or "admin" role_type: type: integer description: The user's role id. 0 for a custom agent, 1 for a light agent, 2 for a chat agent, 3 for a chat agent added to the Support account as a contributor ([Chat Phase 4](https://support.zendesk.com/hc/en-us/articles/360022365373#topic_djh_1zk_4fb)), 4 for an admin, and 5 for a billing admin nullable: true readOnly: true shared: type: boolean description: If the user is shared from a different Zendesk Support instance. Ticket sharing accounts only readOnly: true shared_agent: type: boolean description: If the user is a shared agent from a different Zendesk Support instance. Ticket sharing accounts only readOnly: true shared_phone_number: type: boolean description: Whether the `phone` number is shared or not. See [Phone Number](#phone-number) below nullable: true signature: type: string description: The user's signature. Only agents and admins can have signatures suspended: type: boolean description: If the agent is suspended. Tickets from suspended users are also suspended, and these users cannot sign in to the end user portal tags: type: array description: The user's tags. Only present if your account has user tagging enabled items: type: string ticket_restriction: type: string description: 'Specifies which tickets the user has access to. Possible values are: "organization", "groups", "assigned", "requested", null. "groups" and "assigned" are valid only for agents. If you pass an invalid value to an end user (for example, "groups"), they will be assigned to "requested", regardless of their previous access' nullable: true time_zone: type: string description: The user's time zone. See [Time Zone](#time-zone) two_factor_auth_enabled: type: boolean description: If two factor authentication is enabled nullable: true readOnly: true updated_at: type: string format: datetime description: The time the user was last updated readOnly: true url: type: string description: The user's API url readOnly: true user_fields: type: object description: Values of custom fields in the user's profile. See [User Fields](#user-fields) additionalProperties: true verified: type: boolean description: Any of the user's identities is verified. See [User Identities](/api-reference/ticketing/users/user_identities) required: - name UserForEndUser: type: object properties: created_at: type: string format: datetime description: The time the user was created readOnly: true email: type: string description: The primary email address of this user. If the primary email address is not [verified](https://support.zendesk.com/hc/en-us/articles/4408886752410), the secondary email address is used iana_time_zone: type: string description: The time zone for the user readOnly: true id: type: integer description: Automatically assigned when creating users readOnly: true locale: type: string description: The locale for this user readOnly: true locale_id: type: integer description: The language identifier for this user name: type: string description: The name of the user organization_id: type: integer description: The id of the user's organization. If the user has more than one [organization memberships](/api-reference/ticketing/organizations/organization_memberships/), the id of the user's default organization. If updating, see [Organization ID](/api-reference/ticketing/users/users/#organization-id) phone: type: string description: The primary phone number of this user. See [Phone Number](/api-reference/ticketing/users/users/#phone-number) in the Users API photo: type: object description: The user's profile picture represented as an [Attachment](/api-reference/ticketing/tickets/ticket-attachments/) object additionalProperties: true role: type: string description: 'The role of the user. Possible values: `"end-user"`, `"agent"`, `"admin"`' shared_phone_number: type: boolean description: Whether the `phone` number is shared or not. See [Phone Number](/api-reference/ticketing/users/users/#phone-number) in the Users API time_zone: type: string description: The time-zone of this user updated_at: type: string format: datetime description: The time of the last update of the user readOnly: true url: type: string description: The API url of this user readOnly: true verified: type: boolean description: Any of the user's identities is verified. See [User Identities](/api-reference/ticketing/users/user_identities) required: - name UserIdentitiesResponse: type: object properties: identities: type: array items: $ref: "#/components/schemas/UserIdentityObject" UserIdentityObject: type: object properties: created_at: type: string format: date-time description: The time the identity was created readOnly: true deliverable_state: type: string description: Email identity type only. Indicates if Zendesk sends notifications to the email address. See [Deliverable state](#deliverable-state) readOnly: true id: type: integer description: Automatically assigned on creation readOnly: true primary: type: boolean description: If the identity is the primary identity. *Writable only when creating, not when updating. Use the [Make Identity Primary](#make-identity-primary) endpoint instead type: type: string description: The type of this identity enum: - email - twitter - facebook - google - phone_number - agent_forwarding - any_channel - foreign - sdk readOnly: true undeliverable_count: type: integer description: The number of times a soft-bounce response was received at that address readOnly: true updated_at: type: string format: date-time description: The time the identity was updated readOnly: true url: type: string description: The API url of this identity readOnly: true user_id: type: integer description: The id of the user readOnly: true value: type: string description: The identifier for this identity, such as an email address readOnly: true verification_method: type: string description: Indicates the state of user identity verification. See [Verification method](#verification-method). enum: - none - low - sso - embed - full verified: type: boolean description: If the identity has been verified. Deprecated. Use `verification_method` as a more accurate representation of a user's state of verification. deprecated: true verified_at: type: string format: date-time description: The last time a full verification flow was completed for the identity nullable: true readOnly: true required: - user_id - type - value UserIdentityResponse: type: object properties: identity: $ref: "#/components/schemas/UserIdentityObject" UserInput: oneOf: - $ref: "#/components/schemas/UserCreateInput" - $ref: "#/components/schemas/UserMergePropertiesInput" - $ref: "#/components/schemas/UserMergeByIdInput" additionalProperties: true UserMergeByIdInput: type: object properties: id: type: integer UserMergePropertiesInput: type: object properties: email: type: string name: type: string organization_id: type: integer password: type: string UserObject: oneOf: - $ref: "#/components/schemas/UserForAdmin" - $ref: "#/components/schemas/UserForEndUser" additionalProperties: true UserPasswordRequirementsResponse: type: object properties: requirements: type: array items: type: string UserRelatedObject: type: object properties: assigned_tickets: type: integer description: Count of assigned tickets ccd_tickets: type: integer description: Count of collaborated tickets organization_subscriptions: type: integer description: Count of organization subscriptions requested_tickets: type: integer description: Count of requested tickets UserRelatedResponse: type: object properties: user_related: $ref: "#/components/schemas/UserRelatedObject" UserRequest: type: object properties: user: $ref: "#/components/schemas/UserInput" required: - user UserResponse: type: object properties: user: $ref: "#/components/schemas/UserObject" UsersRequest: type: object properties: users: type: array items: $ref: "#/components/schemas/UserInput" required: - users UsersResponse: type: object properties: users: type: array items: $ref: "#/components/schemas/UserObject" ViaObject: type: object description: "An object explaining how the ticket was created. See the [Via object reference](/documentation/ticketing/reference-guides/via-object-reference) " properties: channel: type: string description: 'This tells you how the ticket or event was created. Examples: "web", "mobile", "rule", "system" ' source: type: object description: "For some channels a source object gives more information about how or why the ticket or event was created " properties: from: type: object properties: address: type: string nullable: true id: type: integer nullable: true name: type: string nullable: true title: type: string nullable: true rel: type: string nullable: true to: type: object properties: address: type: string name: type: string additionalProperties: true readOnly: true ViewCountObject: type: object properties: active: type: boolean description: Only active views if true, inactive views if false, all views if null. readOnly: true fresh: type: boolean description: false if the cached data is stale and the system is still loading and caching new data readOnly: true pretty: type: string description: A pretty-printed text approximation of the view count readOnly: true url: type: string description: The API url of the count readOnly: true value: type: integer description: The cached number of tickets in the view. Can also be null if the system is loading and caching new data. Not to be confused with 0 tickets nullable: true readOnly: true view_id: type: integer description: The id of the view readOnly: true ViewCountResponse: type: object properties: view_count: $ref: "#/components/schemas/ViewCountObject" ViewCountsResponse: type: object properties: view_counts: type: array items: $ref: "#/components/schemas/ViewCountObject" ViewExportResponse: type: object properties: export: type: object properties: status: type: string readOnly: true view_id: type: integer readOnly: true ViewObject: type: object properties: active: type: boolean description: Whether the view is active conditions: type: object description: Describes how the view is constructed. See [Conditions reference](/documentation/ticketing/reference-guides/conditions-reference) additionalProperties: true created_at: type: string format: date-time description: The time the view was created readOnly: true default: type: boolean description: If true, the view is a default view readOnly: true description: type: string description: The description of the view execution: type: object description: Describes how the view should be executed. See [Execution](#execution) additionalProperties: true id: type: integer description: Automatically assigned when created readOnly: true position: type: integer description: The position of the view restriction: type: object description: Who may access this account. Is null when everyone in the account can access it additionalProperties: true title: type: string description: The title of the view updated_at: type: string format: date-time description: The time the view was last updated readOnly: true ViewResponse: type: object properties: columns: type: array items: type: object additionalProperties: true groups: type: array items: type: object additionalProperties: true rows: type: array items: type: object additionalProperties: true view: $ref: "#/components/schemas/ViewObject" ViewsCountResponse: type: object properties: count: type: object properties: refreshed_at: type: string format: date-time value: type: integer ViewsResponse: type: object properties: count: type: integer readOnly: true next_page: type: string nullable: true readOnly: true previous_page: type: string nullable: true readOnly: true views: type: array items: $ref: "#/components/schemas/ViewObject" WorkspaceInput: type: object properties: conditions: $ref: "#/components/schemas/ConditionsObject" description: type: string description: User-defined description of this workspace's purpose macros: type: array items: type: number ticket_form_id: type: number title: type: string description: The title of the workspace WorkspaceObject: type: object properties: activated: type: boolean description: If true, this workspace is available for use apps: type: array description: The apps associated to this workspace items: type: object additionalProperties: true conditions: $ref: "#/components/schemas/ConditionsObject" created_at: type: string format: date-time description: The time the workspace was created description: type: string description: User-defined description of this workspace's purpose id: type: integer description: Automatically assigned upon creation macro_ids: type: array description: The ids of the macros associated to this workspace items: type: integer macros: type: array description: The ids of the macros associated to this workspace items: type: integer position: type: integer description: Ordering of the workspace relative to other workspaces prefer_workspace_app_order: type: boolean description: If true, the order of apps within the workspace will be preserved selected_macros: type: array description: An array of the macro objects that will be used in this workspace. See [Macros](/api-reference/ticketing/business-rules/macros/) items: $ref: "#/components/schemas/MacroObject" ticket_form_id: type: integer description: The id of the ticket web form associated to this workspace title: type: string description: The title of the workspace updated_at: type: string format: date-time description: The time of the last update of the workspace url: type: string description: The URL for this resource WorkspaceResponse: type: object allOf: - type: object properties: workspaces: type: array items: $ref: "#/components/schemas/WorkspaceObject" - $ref: "#/components/schemas/OffsetPaginationObject" Webhook: type: object properties: id: type: string readOnly: true description: An auto-generated webhook id name: type: string description: Webhook name description: type: string description: Webhook description endpoint: type: string description: The destination URL that the webhook notifies when Zendesk events occur http_method: type: string enum: - GET - POST - PUT - PATCH - DELETE description: HTTP method used for the webhook's requests. To subscribe the webhook to Zendesk events, this must be "POST" request_format: type: string enum: - json - xml - form_encoded description: The format of the data that the webhook will send. To subscribe the webhook to Zendesk events, this must be "json" status: type: string enum: - active - inactive description: Current status of the webhook subscriptions: type: array items: type: string description: | Event subscriptions for the webhook. To subscribe the webhook to Zendesk events, specify one or more event types. To connect the webhook to a trigger or automation, specify only "conditional_ticket_events" in the array authentication: oneOf: - $ref: "#/components/schemas/BasicAuthAuthentication" - $ref: "#/components/schemas/BearerTokenAuthentication" - $ref: "#/components/schemas/ApiKeyAuthentication" description: Adds authentication to the webhook's HTTP requests, if not specified, the webhook will be unauthenticated custom_headers: type: object additionalProperties: type: string description: Custom headers to deliver additional non-credential info to destinations signing_secret: $ref: "#/components/schemas/WebhookSigningSecret" external_source: type: object description: External source by which a webhook is created, e.g. Zendesk Marketplace properties: name: type: string description: Name of the external source version: type: string description: Version of the external source created_at: type: string format: date-time readOnly: true description: When the webhook was created created_by: type: string readOnly: true description: id of the user who created the webhook. "-1" represents the Zendesk system updated_at: type: string format: date-time readOnly: true description: When the webhook was last updated updated_by: type: string readOnly: true description: id of the user who last updated the webhook required: - name - endpoint - http_method - request_format - status BasicAuthAuthentication: type: object description: Basic authentication configuration properties: type: type: string enum: - basic_auth data: type: object properties: username: type: string description: Username for basic authentication password: type: string description: Password for basic authentication required: - username required: - type BearerTokenAuthentication: type: object description: Bearer token authentication configuration properties: type: type: string enum: - bearer_token data: type: object properties: token: type: string description: Bearer token for authentication required: - type ApiKeyAuthentication: type: object description: API key authentication configuration properties: type: type: string enum: - api_key data: type: object properties: name: type: string description: Name of the API key parameter value: type: string description: Value of the API key required: - name add_position: type: string enum: - header - query_string description: Where to add the API key (header or query string) default: header required: - type - add_position WebhookSigningSecret: type: object description: Signing secret used to verify webhook requests properties: algorithm: type: string description: Signing algorithm (e.g., sha256) secret: type: string description: The signing secret value WebhookCreateRequest: type: object properties: webhook: type: object allOf: - $ref: "#/components/schemas/Webhook" properties: id: readOnly: true created_at: readOnly: true created_by: readOnly: true updated_at: readOnly: true updated_by: readOnly: true required: - webhook WebhookUpdateRequest: type: object properties: webhook: type: object allOf: - $ref: "#/components/schemas/Webhook" properties: id: readOnly: true created_at: readOnly: true created_by: readOnly: true updated_at: readOnly: true updated_by: readOnly: true required: - webhook WebhookPatchRequest: type: object properties: webhook: type: object description: Partial webhook object with fields to update properties: name: type: string description: type: string endpoint: type: string http_method: type: string enum: - GET - POST - PUT - PATCH - DELETE request_format: type: string enum: - json - xml - form_encoded status: type: string enum: - active - inactive subscriptions: type: array items: type: string authentication: oneOf: - $ref: "#/components/schemas/BasicAuthAuthentication" - $ref: "#/components/schemas/BearerTokenAuthentication" - $ref: "#/components/schemas/ApiKeyAuthentication" custom_headers: type: object additionalProperties: type: string WebhookTestRequest: type: object properties: webhook: type: object description: Webhook configuration for testing properties: endpoint: type: string description: The test endpoint URL http_method: type: string enum: - GET - POST - PUT - PATCH - DELETE default: POST request_format: type: string enum: - json - xml - form_encoded default: json authentication: oneOf: - $ref: "#/components/schemas/BasicAuthAuthentication" - $ref: "#/components/schemas/BearerTokenAuthentication" - $ref: "#/components/schemas/ApiKeyAuthentication" custom_headers: type: object additionalProperties: type: string required: - endpoint required: - webhook WebhookResponse: type: object properties: webhook: $ref: "#/components/schemas/Webhook" WebhookListResponse: type: object properties: webhooks: type: array items: $ref: "#/components/schemas/Webhook" meta: $ref: "#/components/schemas/PaginationMeta" links: $ref: "#/components/schemas/PaginationLinks" WebhookTestResponse: type: object properties: test: type: object properties: status: type: string description: Test status (e.g., "success", "failed") message: type: string description: Test result message response_code: type: integer description: HTTP response code from the test endpoint response_body: type: string description: Response body from the test endpoint WebhookInvocation: type: object properties: id: type: string description: Unique invocation identifier webhook_id: type: string description: ID of the webhook that was invoked status: type: string enum: - unknown - accepted - success - failed - timeout - circuit broken - throttled - client error - server error description: Status of the webhook invocation created_at: type: string format: date-time description: When the invocation was created latest_completed_at: type: string format: date-time description: When the invocation was last completed event_type: type: string description: Type of event that triggered the webhook attempts_count: type: integer description: Number of delivery attempts made WebhookInvocationListResponse: type: object properties: invocations: type: array items: $ref: "#/components/schemas/WebhookInvocation" meta: $ref: "#/components/schemas/PaginationMeta" links: $ref: "#/components/schemas/PaginationLinks" WebhookInvocationAttempt: type: object properties: id: type: string description: Unique attempt identifier invocation_id: type: string description: ID of the parent invocation status: type: string enum: - success - failed - timeout - client error - server error description: Status of the delivery attempt response_code: type: integer description: HTTP response code received response_body: type: string description: Response body received (may be truncated) response_headers: type: object additionalProperties: type: string description: Response headers received error_message: type: string description: Error message if the attempt failed created_at: type: string format: date-time description: When the attempt was made duration_ms: type: integer description: Duration of the attempt in milliseconds WebhookInvocationAttemptListResponse: type: object properties: attempts: type: array items: $ref: "#/components/schemas/WebhookInvocationAttempt" WebhookSigningSecretResponse: type: object properties: signing_secret: $ref: "#/components/schemas/WebhookSigningSecret" PaginationMeta: type: object properties: has_more: type: boolean description: Whether there are more results available after_cursor: type: string description: Cursor for the next page of results before_cursor: type: string description: Cursor for the previous page of results count: type: integer description: Total number of items (may not always be present) PaginationLinks: type: object properties: prev: type: string format: uri description: URL for the previous page of results next: type: string format: uri description: URL for the next page of results ErrorResponse: type: object properties: error: type: object properties: title: type: string description: Error title message: type: string description: Detailed error message code: type: string description: Error code details: type: object description: Additional error details additionalProperties: true errors: type: array items: type: object properties: field: type: string description: Field that caused the error code: type: string description: Error code for this field message: type: string description: Error message for this field description: Field-specific validation errors GroupCreateRequest: type: object properties: group: type: object properties: name: type: string description: The name of the group description: type: string description: The description of the group is_public: type: boolean description: Whether the group is public required: - name required: - group GroupUpdateRequest: type: object properties: group: type: object properties: name: type: string description: The name of the group description: type: string description: The description of the group is_public: type: boolean description: Whether the group is public required: - name required: - group TagsResponse: type: object required: - tags properties: tags: type: array description: An array of tag strings items: type: string TagsRequest: type: object required: - tags properties: tags: type: array description: An array of tag strings to add or set items: type: string SafeTagsRequest: allOf: - $ref: "#/components/schemas/TagsRequest" - type: object properties: updated_stamp: type: string format: date-time description: | The ticket's latest updated_at timestamp for safe updates. Must match the current timestamp to prevent collision. safe_update: type: string description: Enable safe update mode to prevent collisions enum: - "true" - "false" TagsCountResponse: type: object required: - count properties: count: type: object required: - value properties: value: type: integer description: The approximate count of tags refreshed_at: type: string format: date-time nullable: true description: "Timestamp when the count was last updated. May be null\ \ when \ncount exceeds 100,000 and is being updated in the background.\n" GroupMembershipRequest: type: object required: - group_membership properties: group_membership: type: object required: - user_id - group_id properties: user_id: type: integer description: The id of an agent group_id: type: integer description: The id of a group default: type: boolean description: If true, tickets assigned directly to the agent will assume this membership's group default: false responses: NotFound: description: The specified resource was not found content: application/json: schema: $ref: "#/components/schemas/Error" TooManyRequests: description: Rate limit exceeded headers: Retry-After: description: Number of seconds to wait before retrying schema: type: integer content: application/json: schema: $ref: "#/components/schemas/Error" Conflict: description: | Conflict occurred, typically due to a ticket update collision when using safe updates. The updated_stamp timestamp did not match the current ticket timestamp. content: application/json: schema: $ref: "#/components/schemas/Error" parameters: PageBefore: name: page[before] in: query description: "A [pagination cursor](/documentation/api-basics/pagination/paginating-through-lists-using-cursor-pagination) that tells the endpoint which page to start on. It should be a `meta.before_cursor` value from a previous request. Note: `page[before]` and `page[after]` can't be used together in the same request. " schema: type: string PageAfter: name: page[after] in: query description: "A [pagination cursor](/documentation/api-basics/pagination/paginating-through-lists-using-cursor-pagination) that tells the endpoint which page to start on. It should be a `meta.after_cursor` value from a previous request. Note: `page[before]` and `page[after]` can't be used together in the same request. " schema: type: string PageSize: name: page[size] in: query description: "Specifies how many records should be returned in the response. You can specify up to 100 records per page. " schema: type: integer minimum: 1 maximum: 100 default: 100 ActivityId: name: activity_id in: path description: The activity ID required: true schema: type: integer ActivitySince: name: since in: query description: A UTC time in ISO 8601 format to return ticket activities since said date. schema: type: string AgentId: name: agent_id in: path description: ID of an agent required: true schema: type: integer ApprovalRequestId: name: approval_request_id in: path description: The id of the approval request required: true schema: type: string ApprovalWorkflowInstanceId: name: approval_workflow_instance_id in: path description: The id of the approval workflow instance required: true schema: type: string ArchiveImmediately: name: archive_immediately in: query description: If `true`, any ticket created with a `closed` status bypasses the normal ticket lifecycle and will be created directly in your ticket archive schema: type: boolean AssigneeFieldSearchValue: name: name in: query description: Query string used to search assignable groups & agents in the AssigneeField required: true schema: type: string AttachmentId: name: attachment_id in: path description: The ID of the attachment required: true schema: type: integer AuditLogId: name: audit_log_id in: path description: The ID of the audit log required: true schema: type: integer AutomationActive: name: active in: query description: Filter by active automations if true or inactive automations if false schema: type: boolean AutomationId: name: automation_id in: path description: The ID of the automation required: true schema: type: integer AutomationInclude: name: include in: query description: A sideload to include in the response. See [Sideloads](#sideloads-2) schema: type: string AutomationSearchQuery: name: query in: query description: Query string used to find all automations with matching title required: true schema: type: string AutomationSortBy: name: sort_by in: query description: Possible values are "alphabetical", "created_at", "updated_at", and "position". If unspecified, the automations are sorted by relevance schema: type: string AutomationSortOrder: name: sort_order in: query description: One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others schema: type: string BookmarkId: name: bookmark_id in: path description: The ID of the bookmark required: true schema: type: integer BrandAgentId: name: brand_agent_id in: path description: The id of the brand agent required: true schema: type: string BrandId: name: brand_id in: path description: The ID of the brand required: true schema: type: integer CommentId: name: comment_id in: path description: The ID of the comment required: true schema: type: integer CommentIds: name: comment_ids in: query description: Comma-separated list of comment ids required: true schema: type: string Creator: name: creator in: query description: | If true, displays the `creator_user_id` and `creator_app_name` properties. If the ticket field is created by an app, `creator_app_name` is the name of the app and `creator_user_id` is `-1`. If the ticket field is not created by an app, then `creator_app_name` is null schema: type: boolean CustomObjectFieldKeyOrId: name: custom_object_field_key_or_id in: path description: The key or id of a custom object field required: true schema: type: string CustomObjectKey: name: custom_object_key in: path description: The key of a custom object required: true schema: type: string CustomObjectRecordExternalId: name: external_id in: query description: The external id of a custom object record required: true schema: type: string CustomObjectRecordId: name: custom_object_record_id in: path description: The id of a custom object record required: true schema: type: string CustomObjectRecordName: name: name in: query description: The name of a custom object record required: true schema: type: string CustomRoleId: name: custom_role_id in: path description: The ID of the custom agent role required: true schema: type: integer CustomStatusId: name: custom_status_id in: path description: The id of the custom status required: true schema: type: integer DeletedUserId: name: deleted_user_id in: path description: The ID of the deleted user required: true schema: type: integer DeletionScheduleId: name: deletion_schedule_id in: path description: The id of the deletion schedule required: true schema: type: integer DynamicContentItemId: name: dynamic_content_item_id in: path description: The ID of the dynamic content item required: true schema: type: integer DynamicContentVariantId: name: dynammic_content_variant_id in: path description: The ID of the variant required: true schema: type: integer EmailNotificationsByTicketIds: name: ticket_ids in: query description: Comma-separated list of ticket ids required: true schema: type: string EmailNotificationsFilter: name: filter in: query description: "Filters the email notifications by ticket, comment, or notification id. " schema: type: string enum: - ticket_id - comment_id - notification_id EssentialsCardKey: name: object_type in: path description: "Essentials card type. Example: `zen:user` refers user type " required: true schema: type: string ExcludeDeleted: name: exclude_deleted in: query description: Whether to exclude deleted entities schema: type: boolean GroupId: name: group_id in: path description: The ID of the group required: true schema: type: integer GroupMembershipId: name: group_membership_id in: path description: The ID of the group membership required: true schema: type: integer GroupSLAPolicyId: name: group_sla_policy_id in: path description: The id of the Group SLA policy required: true schema: type: integer HostMapping: name: host_mapping in: query description: The hostmapping to a brand, if any (only admins view this key) required: true schema: type: string IncludeStandardFields: name: include_standard_fields in: query description: Include standard fields if true. Exclude them if false schema: type: boolean IncrementalCursor: name: cursor in: query description: The cursor pointer to work with for all subsequent exports after the initial request schema: type: string IncrementalPage: name: per_page in: query description: The number of records to return per page schema: type: integer IncrementalResource: name: incremental_resource in: path description: The resource requested for incremental sample export required: true schema: type: string IncrementalTimeQueryParameter: name: unix_time in: query description: A query start time for incremental exports schema: type: integer IncrementalUnixTime: name: start_time in: query description: 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 required: true schema: type: integer JobStatusId: name: job_status_id in: path description: the Id of the Job status required: true schema: type: string LocaleId: name: locale_id in: path description: "The ID or the [BCP-47 code](https://en.wikipedia.org/wiki/IETF_language_tag) of the locale. Examples: es-419, en-us, pr-br " required: true schema: type: string LookupRelationshipAutocompleteFieldIdFragment: name: field_id in: query description: | The id of a lookup relationship field. The type of field is determined by the `source` param schema: type: string LookupRelationshipAutocompleteSourceFragment: name: source in: query description: | If a `field_id` is provided, this specifies the type of the field. For example, if the field is on a "zen:user", it references a field on a user schema: type: string MacroAccess: name: access in: query description: 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. schema: type: string MacroActive: name: active in: query description: Filter by active macros if true or inactive macros if false schema: type: boolean MacroCategory: name: category in: query description: Filter macros by category schema: type: integer MacroGroupId: name: group_id in: query description: Filter macros by group schema: type: integer MacroId: name: macro_id in: path description: The ID of the macro required: true schema: type: integer MacroIdQuery: name: macro_id in: query description: The ID of the macro to replicate required: true schema: type: integer MacroInclude: name: include in: query description: A sideload to include in the response. See [Sideloads](#sideloads-2) schema: type: string MacroOnlyViewable: name: only_viewable in: query description: If true, returns only macros that can be applied to tickets. If false, returns all macros the current user can manage. Default is false schema: type: boolean MacroQuery: name: query in: query description: Query string used to find macros with matching titles required: true schema: type: string MacroSearchSortBy: name: sort_by in: query description: Possible values are "alphabetical", "created_at", "updated_at", or "position". Defaults to alphabetical schema: type: string MacroSortBy: name: sort_by in: query description: Possible values are "alphabetical", "created_at", "updated_at", "usage_1h", "usage_24h", "usage_7d", or "usage_30d". Defaults to alphabetical schema: type: string MacroSortOrder: name: sort_order in: query description: One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others schema: type: string MonitoredTwitterHandleId: name: monitored_twitter_handle_id in: path description: The ID of the custom agent role required: true schema: type: integer NotificationId: name: notification_id in: path description: The id of the email notification required: true schema: type: integer NotificationIds: name: ids in: query description: Comma-separated list of notification ids required: true schema: type: string OAuthAllTokensQuery: name: all in: query description: A boolean that returns all OAuth tokens in the account. Requires admin role schema: type: boolean OAuthClientId: name: oauth_client_id in: path description: The ID of the OAuth client required: true schema: type: integer OAuthClientIdQuery: name: client_id in: query description: The id of the OAuth client schema: type: integer OAuthGlobalClientIdQuery: name: global_client_id in: query description: The id of the global OAuth client schema: type: integer OAuthIncludExpiredTokensQuery: name: include_expired in: query description: If true, returns all OAuth tokens in the account, including expired tokens. Must be used with the `all` query parameter schema: type: boolean OAuthTokenId: name: oauth_token_id in: path description: The ID of the OAuth token required: true schema: type: integer ObjectKey: name: object_zrn_type in: path description: | Custom object type. Example: `zen:custom_object:car` refers to a custom object type with the `car` key required: true schema: type: string OcrQueueId: name: queue_id in: path description: The id of the omnichannel routing queue required: true schema: type: string OrganizationExternalId: name: external_id in: query description: The external id of an organization schema: type: integer OrganizationExternalIds: name: external_ids in: query description: A list of external ids schema: type: string OrganizationFieldId: name: organization_field_id in: path description: The ID or key of the organization field required: true schema: oneOf: - type: integer - type: string OrganizationId: name: organization_id in: path description: The ID of an organization required: true schema: type: integer OrganizationIds: name: ids in: query description: A list of organization ids schema: type: string OrganizationMembershipId: name: organization_membership_id in: path description: The ID of the organization membership required: true schema: type: integer OrganizationMergeId: name: organization_merge_id in: path description: The ID of the organization merge required: true schema: type: string OrganizationName: name: name in: query description: The name of an organization schema: type: string OrganizationQueryFragment: name: name in: query description: A substring of an organization to search for required: true schema: type: string OrganizationSubscriptionId: name: organization_subscription_id in: path description: The ID of the organization subscription required: true schema: type: integer RequestId: name: request_id in: path description: The ID of the request required: true schema: type: integer ResourceCollectionId: name: resource_collection_id in: path description: The id of the resource collection required: true schema: type: integer SLAPolicyId: name: sla_policy_id in: path description: The ID of the SLA Policy required: true schema: type: integer SessionId: name: session_id in: path description: The ID of the session required: true schema: type: integer SharingAgreementId: name: sharing_agreement_id in: path description: The ID of the sharing agreement required: true schema: type: integer SkillBasedRoutingAttributeId: name: attribute_id in: path description: The ID of the skill-based routing attribute required: true schema: type: string SkillBasedRoutingAttributeValueId: name: attribute_value_id in: path description: The ID of the skill-based routing attribute value required: true schema: type: string SkipTicketUserId: name: user_id in: path description: User ID of an agent required: true schema: type: integer Sort: name: sort in: query description: The field to sort the list. Possible values are "created_at", "updated_at" (ascending order) or "-created_at", "-updated_at" (descending order) schema: type: string Subdomain: name: subdomain in: query description: Subdomain for a given Zendesk account address required: true schema: type: string SupportAddressId: name: support_address_id in: path description: The ID of the support address required: true schema: type: integer SuspendedTicketId: name: id in: path description: id of the suspended ticket required: true schema: type: number SuspendedTicketIds: name: ids in: query description: A list of suspended ticket ids schema: type: string SuspendedTicketsDeleteIds: name: ids in: query description: A comma separated list of ids of suspended tickets to delete. required: true schema: type: string SuspendedTicketsRecoverIds: name: ids in: query description: A comma separated list of ids of suspended tickets to recover. required: true schema: type: string SuspendedTicketsSortBy: name: sort_by in: query description: The field to sort the suspended tickets by. One of "author_email", "cause", "created_at", or "subject" schema: type: string SuspendedTicketsSortOrder: name: sort_order in: query description: The order in which to sort the suspended tickets. This can take value `asc` or `desc`. schema: type: string TagNameFragment: name: name in: query description: A substring of a tag to search for schema: type: string TargetFailureId: name: target_failure_id in: path description: The ID of the target failure required: true schema: type: integer TargetId: name: target_id in: path description: The ID of the target required: true schema: type: integer TicketAuditId: name: ticket_audit_id in: path description: The ID of the ticket audit required: true schema: type: integer TicketCommentId: name: ticket_comment_id in: path description: The ID of the ticket comment required: true schema: type: integer TicketFieldId: name: ticket_field_id in: path description: The ID of the ticket field required: true schema: type: integer TicketFieldOptionId: name: ticket_field_option_id in: path description: The ID of the ticket field option required: true schema: type: integer TicketFormId: name: ticket_form_id in: path description: The ID of the ticket form required: true schema: type: integer TicketFormStatusId: name: ticket_form_status_id in: path description: The id of the ticket form status required: true schema: type: string TicketId: name: ticket_id in: path description: The ID of the ticket required: true schema: type: integer TicketIds: name: ids in: query description: Comma-separated list of ticket ids required: true schema: type: string TicketSortBy: name: sort_by in: query description: Sort by schema: type: string enum: - id - subject - deleted_at TicketSortOrder: name: sort_order in: query description: Sort order. Defaults to "asc" schema: type: string enum: - asc - desc TriggerActive: name: active in: query description: Filter by active triggers if true or inactive triggers if false schema: type: boolean TriggerCategoryId: name: category_id in: query description: Filter triggers by category ID schema: type: string TriggerId: name: trigger_id in: path description: The ID of the trigger required: true schema: type: integer TriggerIds: name: ids in: query description: A comma separated list of trigger IDs required: true schema: type: string TriggerInclude: name: include in: query description: A sideload to include in the response. See [Sideloads](#sideloads-2) schema: type: string TriggerRevisionId: name: trigger_revision_id in: path description: The ID of the revision for a particular trigger required: true schema: type: integer TriggerSearchFilter: name: filter in: query description: Trigger attribute filters for the search. See [Filter](#filter) schema: type: object properties: json: $ref: "#/components/schemas/TriggerObject" TriggerSearchQuery: name: query in: query description: Query string used to find all triggers with matching title required: true schema: type: string TriggerSort: name: sort in: query description: Cursor-based pagination only. Possible values are "alphabetical", "created_at", "updated_at", or "position". schema: type: string TriggerSortBy: name: sort_by in: query description: Offset pagination only. Possible values are "alphabetical", "created_at", "updated_at", "usage_1h", "usage_24h", or "usage_7d". Defaults to "position" schema: type: string TriggerSortOrder: name: sort_order in: query description: One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others schema: type: string UserExternalIdFilter: name: external_id in: query description: List users by external id. External id has to be unique for each user under the same account. schema: type: string UserFieldId: name: user_field_id in: path description: The ID or key of the user field required: true schema: oneOf: - type: integer - type: string UserFieldOptionId: name: user_field_option_id in: path description: The ID of the user field option required: true schema: type: integer UserId: name: user_id in: path description: The id of the user required: true schema: type: integer UserIdentityId: name: user_identity_id in: path description: The ID of the user identity required: true schema: type: integer UserPermissionSetFilter: name: permission_set in: query description: For custom roles which is available on the Enterprise plan and above. You can only filter by one role ID per request schema: type: integer UserRoleFilter: name: role in: query description: 'Filters the results by role. Possible values are "end-user", "agent", or "admin" ' schema: type: string enum: - end-user - agent - admin UserRolesFilter: name: role[] in: query description: "Filters the results by more than one role using the format `role[]={role}&role[]={role}` " explode: true schema: type: string ViewId: name: view_id in: path description: The ID of the view required: true schema: type: integer WorkspaceId: name: workspace_id in: path description: The id of the workspace required: true schema: type: integer securitySchemes: apiTokenAuth: type: http scheme: basic description: | HTTP Basic Authentication using your Zendesk email and an API token. - Username: `{your_email}/token` - Password: `{your_api_token}` security: - apiTokenAuth: []