Zendesk

Shows the settings that are available for the account. #### Allowed For * Agents

Updates settings for the account. See [JSON Format](https://developer.zendesk.com) above for the settings you can update. #### Allowed For * Admins

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](https://developer.zendesk.com). Returns a maximum of 100 records per page. #### Allowed For * Agents

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

Lists a specific activity. #### Allowed For * Agents

List assignable groups on the AssigneeField #### Allowed For * Agents

List assignable agents from a group on the AssigneeField #### Allowed For * Agents

List assignable groups and agents based on query matched against name #### Allowed For * Agents

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

Toggles enabling or restricting agent access to attachments with detected malware. #### Allowed For * Admins

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AttachmentUpdateRequest"
      },
      "examples": {
        "default": {
          "$ref": "#/components/examples/AttachmentUpdateRequestExample"
        }
      }
    }
  }
}

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)

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](https://developer.zendesk.com). 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 3 days. **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](https://developer.zendesk.com) 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

#### Allowed for * End Users

#### Allowed For * Admins on accounts that have audit log access #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](https://developer.zendesk.com). Returns a maximum of 100 records per page.

#### Allowed For * Admins on accounts that have audit log access

#### Allowed For * Admins on accounts that have audit-log access

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](https://developer.zendesk.com). Returns a maximum of 100 records per page.

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

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

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" } ```

#### 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](https://developer.zendesk.com). | 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

**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} ] } ```

**Note**: You might be restricted from deleting some default automations. #### Allowed For * Agents

#### Allowed For * Agents

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

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

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

#### 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. 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)

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketCreateVoicemailTicketRequest"
      },
      "examples": {
        "default": {
          "$ref": "#/components/examples/TicketCreateTicketViaTalkRequestExample"
        }
      }
    }
  }
}

#### Allowed For - Agents

#### Allowed For - Agents

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BookmarkCreateRequest"
      },
      "examples": {
        "default": {
          "$ref": "#/components/examples/BookmarkCreateRequest"
        }
      }
    }
  }
}

#### 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`.

Returns a list of all brands for your account sorted by name. #### Allowed for * Admins, Agents #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](https://developer.zendesk.com).

#### Allowed for - Admins

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BrandCreateRequest"
      },
      "examples": {
        "default": {
          "$ref": "#/components/examples/BrandCreateRequestExample"
        }
      }
    }
  }
}

Returns a JSON object determining whether a host mapping is valid for a given subdomain. #### Allowed for * Admins

Deletes a brand. #### Allowed for - Admins

Returns a brand for your account. #### Allowed for * Admins, Agents

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.

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BrandUpdateRequest"
      },
      "examples": {
        "default": {
          "$ref": "#/components/examples/BrandUpdateRequestExample"
        }
      }
    }
  }
}

Returns a JSON object determining whether a host mapping is valid for the given brand. #### Allowed for - Admins

#### Allowed For * Admins #### Request parameters The POST request takes a JSON object parameter which contains information about the problematic [channelback](https://developer.zendesk.com). | 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

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](https://developer.zendesk.com) 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](https://developer.zendesk.com) below | display_info | array | | no | Array of integration-specific data used by apps to modify the agent UI. See [display_info object](https://developer.zendesk.com) 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](https://developer.zendesk.com) | 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](https://developer.zendesk.com). 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](https://developer.zendesk.com) 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](https://developer.zendesk.com) #### status object | Name | Type | Comments | ----------- | ------ | ------------------- | code | string | A code indicating the status of the import of the resource, as described in [status codes](https://developer.zendesk.com) | 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](https://developer.zendesk.com), could not be found. The unrecognized parent ID is returned in the description of the [status](https://developer.zendesk.com) | processing_error | An internal exception occurred while processing the resource. See `description` in the [status object](https://developer.zendesk.com) | halted | This resource was not processed because processing of previous resources failed

#### 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.

Lists all undeleted custom fields for the specified object. #### Allowed For * Agents #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](https://developer.zendesk.com).

Creates any of the following custom field types: * text (default when no "type" is specified) * textarea * checkbox * date * integer * decimal * regexp * dropdown * lookup See [About custom field types](https://support.zendesk.com/hc/en-us/articles/203661866) in Zendesk help. #### Allowed For * Admins

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CustomObjectFieldsCreateRequest"
      },
      "examples": {
        "default": {
          "$ref": "#/components/examples/CustomObjectFieldsCreateRequestExample"
        }
      }
    }
  }
}

Sets a preferred order of custom fields for a specific object by providing field ids in the desired order. #### Allowed For * Admins

Deletes a field with the specified key. Note: You can't delete standard fields. #### Allowed For * Admins

Returns a custom field for a specific object using a provided key or id of the field. #### Allowed For * Agents

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` and `description` properties can be updated. #### Allowed For * Admins

List the current count and the limit for a custom object's fields #### Allowed For * Agents

List the current count and the limit for custom object records #### Allowed For * Agents

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"` * `"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 * For an `"update"` action, an array of JSON objects representing the custom object records being updated #### 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.

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CustomObjectRecordsBulkCreateRequest"
      },
      "examples": {
        "default": {
          "$ref": "#/components/examples/CustomObjectRecordsBulkCreateRequestExample"
        }
      }
    }
  }
}

Deletes a record with the specified external id. #### Allowed For * Agents

Lists all undeleted custom object records for the specified object #### Pagination * [Cursor pagination](/api-reference/introduction/pagination/#cursor-pagination) only. #### Allowed For * Agents

If a record exists for the given external id, updates it. Only the specified attributes are updated. Otherwise, creates a new record with the provided external id and attributes. #### Allowed For * Agents

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CustomObjectRecordsUpsertRequest"
      },
      "examples": {
        "default": {
          "$ref": "#/components/examples/CustomObjectRecordsUpsertRequestExample"
        }
      }
    }
  }
}

Creates a custom object record according to all the properties described by a custom object definition #### Allowed For * Agents

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CustomObjectRecordsCreateRequest"
      },
      "examples": {
        "default": {
          "$ref": "#/components/examples/CustomObjectRecordsCreateRequestExample"
        }
      }
    }
  }
}

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

Returns a total count of records for a specific custom object as well as the time the count was refreshed. #### Allowed For * Agents

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

Deletes a record with the specified id #### Allowed For * Agents

Returns a custom record for a specific object using a provided id. #### Allowed For * Agents

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

Lists all undeleted custom objects for the account #### Allowed For * Agents

Creates an object describing all the properties required to create a custom object record #### Allowed For * Admins

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CustomObjectsCreateRequest"
      },
      "examples": {
        "default": {
          "$ref": "#/components/examples/CustomObjectsCreateRequestExample"
        }
      }
    }
  }
}

List the current count and the limit for custom objects #### Allowed For * Admins

Permanently deletes the custom object with the specified key #### Allowed For * Admins

Returns an object with the specified key #### Allowed For * Agents

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

#### Availability * Accounts on the Enterprise plan or above #### Allowed For * Agents

#### Availability * Accounts on the Enterprise plan or above #### Allowed for * Administrators * Agents with the `manage_roles` permission

#### Availability * Accounts on the Enterprise plan or above #### Allowed for * Administrators * Agents with the `manage_roles` permission

#### Availability * Accounts on the Enterprise plan or above #### Allowed for * Administrators * Agents with the `manage_roles` permission

#### Availability * Accounts on the Enterprise plan or above #### Allowed for * Administrators Agents with the `manage_roles` permission

Updates the default values for many custom ticket statuses at once. #### Allowed For * Admins

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BulkUpdateDefaultCustomStatusRequest"
      },
      "examples": {
        "default": {
          "$ref": "#/components/examples/BulkUpdateDefaultCustomStatusRequestExample"
        }
      }
    }
  }
}

Lists all undeleted custom ticket statuses for the account. No pagination is provided. #### Allowed For * End Users

Takes a `custom_status` object that specifies the custom ticket status properties to create. #### Allowed For * Admins

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CustomStatusCreateRequest"
      },
      "examples": {
        "default": {
          "$ref": "#/components/examples/CustomStatusCreateRequestExample"
        }
      }
    }
  }
}

Returns the custom ticket status object. #### Allowed For * End Users

Takes a `custom_status` object that specifies the properties to update. #### Allowed For * Admins

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CustomStatusUpdateRequest"
      },
      "examples": {
        "default": {
          "$ref": "#/components/examples/CustomStatusUpdateRequestExample"
        }
      }
    }
  }
}

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](https://developer.zendesk.com).

Create a new content item, with one or more variants in the item's `variants` array. See [Specifying item variants](https://developer.zendesk.com). 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

#### Stability * Development #### Allowed For * Admins, Agents

#### Allowed For * Admins, Agents

#### Allowed For * Admins, Agents

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

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](https://developer.zendesk.com).

You can only create one variant for each locale id. If a locale variant already exists, the request is rejected. #### Allowed For * Admins, Agents

#### Allowed For * Admins, Agents

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

#### Allowed For * Admins, Agents

#### Allowed For * Admins, Agents

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

Gets the list of essentials cards. #### Allowed For * Admins

Delete the essentials card for an object type. #### Allowed For * Admins and agents

Gets the essentials card for an object type. #### Allowed For * Admins and agents

Updates the essentials card for an object type. #### Allowed For * Admins

#### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](https://developer.zendesk.com). Returns a maximum of 100 records per page. #### Allowed For: * Agents

Assigns an agent to a given group. #### Allowed For * Admins * Agents assigned to a custom role with permissions to manage group memberships (Enterprise only)

Returns a maximum of 100 group memberships per page. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](https://developer.zendesk.com). Returns a maximum of 100 records per page. #### Allowed For: * Agents

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.

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)

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)

The 'id' is the group membership id, not a group id. #### Allowed For * Agents

#### Allowed For: * Agents

#### Allowed For * Admins

#### Allowed For * Admins

#### Allowed For * Admins

#### Allowed For * Admins

#### Allowed For * Admins

#### Allowed For * Admins

Updates the specified policy. #### Allowed For * Admins

#### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](https://developer.zendesk.com). Returns a maximum of 100 records per page. #### Allowed For * Admins * Agents

#### Allowed For * Admins * Agents assigned to a custom role with permissions to manage groups (Enterprise only)

#### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](https://developer.zendesk.com). Returns a maximum of 100 records per page. #### Allowed For * Admins * Agents

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

#### Allowed For * Admins * Agents assigned to a custom role with permissions to manage groups (Enterprise only)

#### Allowed For * Admins * Agents

#### Allowed For * Admins

#### Allowed For * Admins #### Sideloading See [Organizations sideloads](/documentation/ticketing/using-the-zendesk-api/side_loading/#supported-endpoints).

Returns a stream of changes that occurred on tickets. Each event is tied to an update on a ticket and contains all the fields that were updated in that change. For more information, see: - [Exporting ticket events](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#exporting-ticket-events) in [Using the Incremental Exports API](https://developer.zendesk.com) - [Time-based incremental exports](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#time-based-incremental-exports) in [Using the Incremental Exports API](https://developer.zendesk.com) 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" }, ... ], ... ```

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](https://developer.zendesk.com). 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](https://developer.zendesk.com). You can also return tickets using cursor-based pagination. See [Incremental Ticket Export, Cursor Based](https://developer.zendesk.com). 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](https://developer.zendesk.com). 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](https://developer.zendesk.com). 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.

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](https://developer.zendesk.com). 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](https://developer.zendesk.com). #### 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.

#### Allowed For * Admins #### Sideloading See [Users sideloads](/documentation/ticketing/using-the-zendesk-api/side_loading/#supported-endpoints).

#### Allowed For * Admins #### Sideloading See [Users sideloads](/documentation/ticketing/using-the-zendesk-api/side_loading/#supported-endpoints).

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".

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](https://developer.zendesk.com).

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](https://developer.zendesk.com).

Returns a stream of changes that occurred on routing instance values. Changes are grouped by `attribute_value_id`, with unassociate type events listed with associate type events by the associate event’s timestamp. #### Allowed For * Admins #### Parameters Optional | Name | Type | Comment | ------ | ------ | ------- | cursor | string | The `cursor` parameter is a non-human-readable argument you can use to move forward or backward in time. The cursor is a read-only URL parameter that's only available in API responses. See [Pagination](https://developer.zendesk.com).

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](https://developer.zendesk.com).

Accepts a comma-separated list of job status ids. #### Allowed For: * Agents

Shows the status of a background job. #### Allowed For: * Agents

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

Lists the translation locales that have been localized for agents on a specific account. #### Allowed For * Anyone

This works like [Show Locale](https://developer.zendesk.com), but instead of taking a locale id as an argument, it renders the locale of the user performing the request. #### Allowed For * Anyone

#### Allowed For * Anyone

Lists the translation locales that are available to all accounts. #### Allowed For * Anyone

#### Allowed For * Anyone

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`.

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](https://developer.zendesk.com).

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](https://developer.zendesk.com). Returns a maximum of 100 records per page. #### Allowed For * Agents

#### Allowed For * Agents

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MacrosCreateNewMacroRequest"
      },
      "examples": {
        "default": {
          "value": {
            "macro": {
              "title": "Roger Wilco",
              "actions": [
                {
                  "field": "status",
                  "value": "solved"
                }
              ]
            }
          }
        }
      }
    }
  }
}

#### Allowed For * Agents

Lists all active shared and personal macros available to the current user. #### Allowed For * Agents

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

Shows the properties of the specified macro attachment. #### Allowed For * Agents

Lists all macro categories available to the current user. #### Allowed For * Agents

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](https://developer.zendesk.com). #### Allowed For * Agents

Deletes the macros corresponding to the provided comma-separated list of IDs. #### Allowed For * Agents

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

#### Pagination * Offset pagination only See [Using Offset Pagination](/api-reference/ticketing/introduction/#using-offset-pagination). #### Allowed For * Agents

Updates the provided macros with the specified changes. #### Allowed For * Agents

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MacroUpdateManyInput"
      },
      "examples": {
        "default": {
          "value": {
            "macros": [
              {
                "id": 25,
                "active": false
              },
              {
                "id": 23,
                "position": 5
              }
            ]
          }
        }
      }
    }
  }
}

#### Allowed For * Agents, with restrictions applying on certain actions

#### Allowed For * Agents

#### Allowed For * Agents

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MacrosUpdateMacroAgentRequest"
      },
      "examples": {
        "default": {
          "value": {
            "macro": {
              "title": "Sets the ticket status to `solved`",
              "actions": [
                {
                  "field": "status",
                  "value": "solved"
                }
              ]
            }
          }
        }
      }
    }
  }
}

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](https://developer.zendesk.com) 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](https://developer.zendesk.com). #### Allowed For * Agents

Lists the attachments associated with a macro. #### Allowed For * Agents

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

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](https://developer.zendesk.com). #### Allowed For * Agents

#### Allowed For * Admins

#### Allowed For * Admins

#### Allowed For * Admins

#### Allowed For * Admins

#### Allowed For * Admins

#### Allowed For * Admins

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](https://developer.zendesk.com) resource. #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](https://developer.zendesk.com). Returns a maximum of 100 records per page. #### Allowed For * Agents

Creates any of the following custom field types: * text (default when no "type" is specified) * textarea * checkbox * date * integer * decimal * regexp * dropdown * lookup See [About custom field types](https://support.zendesk.com/hc/en-us/articles/203661866) in Zendesk help. #### Allowed For * Admins

#### Allowed For * Admins

#### Allowed for * Admins

#### Allowed for * Agents

#### Updating a Drop-down (Tagger) Field Drop-down fields return an array of `custom_field_options` which specify the name, value, and order of drop-down options. When updating a drop-down 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}:{password} ``` #### Allowed for * Admins

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](https://developer.zendesk.com). Returns a maximum of 100 records per page. #### Allowed For - Agents - End users

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

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

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

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

#### Allowed for * Agents

Sets the default organization membership of a given user. #### Allowed for * Admins * Agents when setting the default organization membership for an end user

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

Sets the default organization membership of a given user. #### Allowed For * Agents

#### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](https://developer.zendesk.com). 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.

#### Allowed For: * Agents * End users End users can only subscribe to shared organizations in which they're members.

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganizationSubscriptionCreateRequest"
      },
      "examples": {
        "default": {
          "$ref": "#/components/examples/OrganizationSubscriptionCreateRequestExample"
        }
      }
    }
  }
}

#### Allowed For: * Agents * End users

#### Allowed For: * Agents * End users For end users, the response will only list the subscriptions created by the requesting end user.

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

#### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](https://developer.zendesk.com). 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.

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)

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

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

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

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

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)

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.

Accepts a comma-separated list of up to 100 organization ids or external ids. #### Allowed For * Admins * Agents

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.

#### Allowed For * Admins * Agents assigned to a custom role with permissions to manage organizations (Enterprise only)

#### Allowed For * Admins * Agents

#### 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" } } ```

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: - The "losing" organization will be deleted. - Other organization fields and their values will not be carried over to the "winning" organization. - The merge operation creates an `Organization Merge` record which contains a status indicating the progress of the merge. **Note**: This operation is irreversible. #### Merge Statuses | Status | Description | |--------|-------------| | new | A job has been queued to merge the two organizations. | | in progress | The job to merge the two organizations has started. | | error | An error occurred during the merge job. The merge can be retried by repeating the API call. | | complete | The merge has been completed successfully. | #### Allowed For * Admins

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganizationMergeRequest"
      },
      "examples": {
        "default": {
          "$ref": "#/components/examples/OrganizationMergeRequestExample"
        }
      }
    }
  },
  "required": true
}

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](https://developer.zendesk.com) for more details. #### Allowed For * Admins

#### Allowed For * Agents

Unregisters the mobile devices that are receiving push notifications. Specify the devices as an array of mobile device tokens. #### Allowed for * Admins

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PushNotificationDevicesRequest"
      },
      "examples": {
        "default": {
          "$ref": "#/components/examples/PushNotificationDevicesRequestExample"
        }
      }
    }
  }
}

#### Allowed for * End Users #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](https://developer.zendesk.com).

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](https://developer.zendesk.com)) #### Additional properties In addition to the writable request properties in the [JSON Format table](https://developer.zendesk.com) 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](https://developer.zendesk.com) | 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.

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

#### Sideloads The following sideloads are supported: | Name | Will sideload | ---------------- | ------------- | users | The email ccs for a request by side-loading users #### Allowed For * End Users

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](https://developer.zendesk.com) | | 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

#### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](https://developer.zendesk.com). #### 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

#### Allowed For * End Users

Zendesk Support credentials are not required to access this endpoint. You can use any Zendesk Support subdomain. Returns "true" if the subdomain is available.

Lists resource collections for the account. #### Allowed for * Admins

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](https://developer.zendesk.com) in the Zendesk Apps framework docs. The response includes a [job status](https://developer.zendesk.com) for creation of the specified resources. #### Allowed for * Admins

Deletes a specified resource collection. The response includes a [job status](https://developer.zendesk.com) for deletion of the collection's resources. #### Allowed for * Admins

Retrieves details for a specified resource collection. #### Allowed for * Admins

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](https://developer.zendesk.com) in the Zendesk Apps framework docs. The response includes a [job status](https://developer.zendesk.com) for the resource updates. #### Allowed for * Admins

#### Availability * Accounts on the Support Professional or Suite Growth plan or above #### Allowed For * Admins

#### Availability * Accounts on the Support Professional or Suite Growth plan or above #### Allowed For * Admins

#### Availability * Accounts on the Support Professional or Suite Growth plan or above #### Allowed For * Admins

#### Availability * Accounts on the Support Professional or Suite Growth plan or above #### Allowed For * Admins

#### Availability * Accounts on the Support Professional or Suite Growth plan or above #### Allowed For * Admins

#### Availability * Accounts on the Support Professional or Suite Growth plan or above #### Allowed For * Admins

Updates the specified policy. #### Availability * Accounts on the Support Professional or Suite Growth plan or above #### Allowed For * Admins

#### Allowed For * Admins #### Pagination * Cursor pagination (recommended) * Offset pagination See [Pagination](https://developer.zendesk.com). #### Filters | Parameter | Value | ---------- | ----- | score | offered, unoffered, received, received\_with\_comment, received\_without\_comment,<br/>good, good\_with\_comment, good\_without\_comment,<br/>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`

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

Returns a specific satisfaction rating. You can get the id from the [List Satisfaction Ratings](https://developer.zendesk.com) endpoint. #### Allowed For * Admins

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.

List all reasons for an account #### Allowed For * Admins

#### Allowed For * Admins

Use the ampersand character (&) to append the `sort_by` or `sort_order` parameters to the URL. For examples, see [Searching with Zendesk API](https://developer.zendesk.com). #### 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 [Pagination](https://developer.zendesk.com) for more information. #### Allowed For * Admins, Agents and Light Agents #### 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." } ```

Returns the number of items matching the query rather than the items. The search string works the same as a regular search.

Exports a set of results. See [Query basics](https://developer.zendesk.com) for the syntax of the `query` parameter. This endpoint is 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](https://developer.zendesk.com). 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](https://developer.zendesk.com) - [Paginating through lists using cursor pagination](https://developer.zendesk.com) #### 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.

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](https://developer.zendesk.com). #### Allowed For * Admins, Agents, End users

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

#### Allowed For * Admins, Agents, End users

#### Allowed For * Admins, Agents, End users

Deletes all the sessions for a user. #### Allowed For * Admins, Agents, End users

#### Allowed For * Admins, Agents, End users

#### Allowed For * Admins, Agents, End users

#### Allowed For * Agents

#### Allowed For * Admins

Deletes a sharing agreement. #### Allowed For * Admins

Returns a sharing agreement for your account. #### Allowed For * Agents

Returns an updated sharing agreement. Only `status` is allowed to be updated. #### Allowed For * Admins

Returns an attribute value. #### Allowed For * Agents and admins

Adds the specified attributes if no attributes exists, or replaces all existing attributes with the specified attributes. #### Allowed For * Admins

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

Creates an attribute. #### Allowed For * Agents

Returns the condition definitions that can be configured to apply attributes to a ticket. #### Allowed For * Admins

Deletes an attribute. #### Allowed For * Admins

Returns an attribute. #### Allowed For * Admins

Updates an attribute. #### Allowed For * Admins

Returns a list of attribute values for a provided attribute. #### Allowed For * Admins

Creates an attribute value. #### Allowed For * Admins

Deletes an attribute value. #### Allowed For * Agents

Returns an attribute value. #### Allowed For * Admins

Updates an attribute value. #### Allowed For * Admins

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

Returns a list of attributes values for the ticket. #### Allowed For * Agents and admins

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

Lists all the support addresses for the account. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](https://developer.zendesk.com). Returns a maximum of 100 records per page. #### Allowed For * Admins * Agents

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](https://developer.zendesk.com) 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

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

#### Allowed For * Admins * Agents

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](https://developer.zendesk.com) 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

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](https://developer.zendesk.com) 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](https://developer.zendesk.com) 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

#### 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](https://developer.zendesk.com).

Makes copies of any attachments on a suspended ticket and returns them as [attachment tokens](https://developer.zendesk.com). 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

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

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).

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

#### Allowed For * Unrestricted agents

#### 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

**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](https://developer.zendesk.com) endpoint with the single ticket. This endpoint does not queue an asynchronous job that can be tracked from [Job Statuses](https://developer.zendesk.com). 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

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

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](https://developer.zendesk.com). Returns a maximum of 100 records per page. #### Allowed For * Agents

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 * Admins

You can also delete tags from multiple tickets with the [Update Many Tickets](/api-reference/ticketing/tickets/tickets/#update-many-tickets) endpoint. This endpoint supports safe updates. See [Safe Update](/api-reference/ticketing/ticket-management/tags/#safe-update). #### Allowed For * Agents

#### Allowed For * Agents

#### Allowed For * Agents

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

Returns the 25 most recent target failures, per target. #### Stability * Development #### Allowed For * Admins

#### Stability * Development #### Allowed For * Admins

#### Allowed For * Agents

#### Allowed For * Admins

#### Allowed For * Admins

#### Allowed For * Agents

#### Allowed For * Admins

Returns ticket audits. Archived tickets are not included in the response. Use the [List Audits for a Ticket](https://developer.zendesk.com) 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). #### Pagination - Cursor pagination See [Pagination](https://developer.zendesk.com). Returns a maximum of 100 records per page. #### Allowed For * Admins

Lists the audits for a specified ticket. #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](https://developer.zendesk.com). 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

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**: 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

#### Allowed for * Agents

#### Allowed for * Agents

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](https://developer.zendesk.com). #### 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](https://developer.zendesk.com) | | chat_indexes | array | true | The array of `chat_index` in the `ChatFileAttachment` event in the ticket audit. See [Ticket Audits](https://developer.zendesk.com) | To get the required body properties, make a request to the [Ticket Audits](https://developer.zendesk.com) 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" } ] } } ] ] } ```

Permanently removes words or strings from a chat ticket's comment. Wrap `<redact>` tags around the content in the chat comment you want redacted. Example: ```json { "text": "My ID number is <redact>847564</redact>!" } ``` The characters contained in the tag will be replaced by the ▇ symbol. **Note**: This does not work on active chats. For chat tickets that predate March 2020, consider using [Redact Ticket Comment In Agent Workspace](https://developer.zendesk.com). #### 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](https://developer.zendesk.com) | | chat_index | integer | true | The `chat_index` in the `ChatMessage` event in the ticket audit. See [Ticket Audits](https://developer.zendesk.com) | | text | string | true | The `message` in the `ChatMessage` event in the ticket audit. See [Ticket Audits](https://developer.zendesk.com). Wrap `message` with `<redact>` tags | To get the required body properties, make a request to the [Ticket Audit](https://developer.zendesk.com) 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": "ChatMessage", "message": "My ID number is 847564!" } ] } } ] ] } ```

Redaction allows you to permanently remove words, strings, or attachments from a ticket comment. In the `html_body` of the comment, wrap the content you want redacted in `<redact>` tags. Example: ```json { "html_body": "<div class=\"zd-comment\" dir=\"auto\">My ID number is <redact>847564</redact>!</div>", "ticket_id":100 } ``` The characters in the redact tag will be replaced by the ▇ symbol. To redact HTML elements such inline images, anchor tags, and links, add the `redact` tag attribute to the element as well as the `<redact>` tag to inner text, if any. Example: `<a href="http://example.com" redact><redact>some link</redact></a>` The `redact` attribute only redacts the tag. Any inner text will be left behind if not enclosed in a `<redact>` tag. Redaction is permanent and can not be undone. Data is permanently deleted from Zendesk servers with no way to recover it. This 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: - Redaction of comments in closed tickets - Redaction of comments in archived tickets - Redaction of formatted text (bold, italics, hyperlinks) **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. **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. #### Allowed For - Agents [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. #### Request Body Properties | Name | Type | Required | Description | | -------------------------| ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | ticket_id | integer | true | The ID of the ticket | | html_body | string | false | The `html_body` of the comment containing `<redact>` tags or `redact` attributes | | external_attachment_urls | array | false | Array of attachment URLs belonging to the comment to be redacted. See [`content_url` property of Attachment](https://developer.zendesk.com) |

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](https://developer.zendesk.com). #### Pagination - Cursor pagination (recommended) - Offset pagination See [Pagination](https://developer.zendesk.com). 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

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

#### Allowed For * Agents

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 ▇ symbol. If the comment was made by email, the endpoint also attempts to redact the string from the original email retained by Zendesk for audit purposes. **Note**: If you use the rich text editor, support for redacting formatted text (bold, italics, hyperlinks) is limited. 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. To use this endpoint, the "Agents can delete tickets" option must be enabled in the Zendesk Support admin interface at **Admin** > **Settings** > **Agents**. #### Allowed For * Agents

Returns a list of all system and custom ticket fields in your account. 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 and id. For accounts without access to multiple ticket forms, positions can be changed using the [Update Ticket Field](/api-reference/ticketing/tickets/ticket_fields/#update-ticket-field) endpoint or the Ticket Forms page in Zendesk Support (**Admin** > **Manage** > **Ticket Forms**). The Ticket Forms page shows the fields for the account. The order of the fields is used in the different products to show the field values in the tickets. For accounts with access to multiple ticket forms, positions can only be changed using the [Update Ticket Field](/api-reference/ticketing/tickets/ticket_fields/#update-ticket-field) endpoint because products use the order defined on each form to show the field values instead of the general position of the ticket field in the account. 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](https://developer.zendesk.com). #### Sideloads The following sideloads are supported: | Name | Will sideload | ---------------- | ------------- | users | The user or users that created the ticket field #### Allowed For * Agents

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 | | 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 | | 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](https://developer.zendesk.com)) to another object such as a user, ticket, or organization | 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

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