Zendesk Requests API

openapi: 3.2.0
info:
  version: '1.0'
  title: Zendesk Account Account Settings Requests API
  description: Needs a description.
tags:
- name: Requests
paths:
  /api/v2/requests:
    get:
      operationId: ListRequests
      tags:
      - Requests
      summary: Zendesk Get  Api V2 Requests
      description: '#### Allowed for


        * End Users


        #### Pagination


        * Cursor pagination (recommended)

        * Offset pagination


        See [Pagination](/api-reference/introduction/pagination/).

        '
      parameters:
      - name: sort_by
        in: query
        description: Possible values are "updated_at", "created_at"
        schema:
          type: string
      - name: sort_order
        in: query
        description: One of "asc", "desc". Defaults to "asc"
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestsResponse'
              examples:
                default:
                  $ref: '#/components/examples/RequestsResponseExample'
    post:
      operationId: CreateRequest
      tags:
      - Requests
      summary: Zendesk Post  Api V2 Requests
      description: 'Accepts a `request` object that sets one or more properties.


        #### Allowed for


        * End users

        * Anonymous users (rate limit of 5 requests per hour for [trial accounts](/documentation/developer-tools/getting-started/getting-a-trial-or-sponsored-account-for-development/))


        #### Additional properties


        In addition to the writable request properties in the [JSON Format table](#json-format) above, you can set the following properties when creating a request.


        | Name                | Type   | Mandatory | Comment

        | ----------------    | -------| --------- | -------

        | comment             | object | yes       | Describes the problem, incident, question, or task. See [Request comments](#request-comments)

        | collaborators       | array  | no        | Adds collaborators (cc''s) to the request. An email notification is sent to them when the ticket is created. See [Setting collaborators](/documentation/ticketing/managing-tickets/creating-and-managing-requests#setting-collaborators)

        | requester           | object | yes*      | \*Required for anonymous requests. Specifies the requester of the anonymous request. See [Creating anonymous requests](/documentation/ticketing/managing-tickets/creating-and-managing-requests#creating-anonymous-requests)


        #### Creating follow-up requests


        Once a ticket is closed (as distinct from solved), it can''t be reopened. However, you can create a new request that references the closed ticket. To create the follow-up request, include a `via_followup_source_id` property in the `request` object that specifies the closed ticket. The parameter only works with closed tickets. It has no effect with other tickets.

        '
      responses:
        '201':
          description: Created response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestResponse'
              examples:
                default:
                  $ref: '#/components/examples/RequestCreateResponseExample'
  /api/v2/requests/{request_id}:
    parameters:
    - $ref: '#/components/parameters/RequestId'
    get:
      operationId: ShowRequest
      tags:
      - Requests
      summary: Zendesk Get  Api V2 Requests Request_id
      description: '#### Sideloads


        The following sideloads are supported:


        | Name             | Will sideload

        | ---------------- | -------------

        | users            | The email ccs for a request by side-loading users


        #### Allowed For


        * End Users

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestResponse'
              examples:
                default:
                  $ref: '#/components/examples/RequestResponseExample'
    put:
      operationId: UpdateRequest
      tags:
      - Requests
      summary: Zendesk Put  Api V2 Requests Request_id
      description: 'Updates a request with a comment or collaborators (cc''s). The end user who created the request can also use it to mark the request as solved. The endpoint can''t be used to update other request attributes.


        #### Writable properties

        This endpoint can only update the following properties in the request.


        | Name                     | Type    | Required | Description                                          |

        | ------------------------ | ------- | -------- | ---------------------------------------------------- |

        | comment                  | object  | no       | Adds a comment to the request. See [Request comments](#request-comments) |

        | solved                   | boolean | no       | Marks the request as solved. Example: `{"request": {"solved": "true"}}`. End users can mark requests as solved only if the request''s `can_be_solved_by_me` property is true. The property is true only when the ticket is assigned to an agent and the ticket type is not a problem but a question, task, or incident |

        | additional_collaborators | array   | no       | Adds collaborators to the request. An email notification is sent to them when the ticket is updated. See [Adding collaborators](/documentation/ticketing/managing-tickets/creating-and-managing-requests#adding-collaborators) |


        #### Allowed For


        * End users

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestResponse'
              examples:
                default:
                  $ref: '#/components/examples/RequestCreateResponseExample'
  /api/v2/requests/{request_id}/comments:
    parameters:
    - $ref: '#/components/parameters/RequestId'
    get:
      operationId: ListComments
      tags:
      - Requests
      summary: Zendesk Get  Api V2 Requests Request_id Comments
      description: '#### Pagination


        - Cursor pagination (recommended)

        - Offset pagination


        See [Pagination](/api-reference/introduction/pagination/).


        #### Sorting


        By default, comments are sorted by creation date in ascending order.


        When using cursor pagination, use the following parameter to change the sort order:


        | Name   | Type   | Required | Comments

        | ------ | ------ | -------- | --------

        | `sort` | string | no       | Possible values are "created_at" (ascending order) or "-created_at" (descending order)


        When using offset pagination, use the following parameters to change the sort order:


        | Name         | Type   | Required | Comments

        | ------------ | ------ | -------- | --------

        | `sort_by`    | string | no       | One of `created_at`, `updated_at`

        | `sort_order` | string | no       | One of `asc`, `desc`


        #### Allowed For


        * End Users

        '
      parameters:
      - name: since
        in: query
        description: Filters the comments from the given datetime
        schema:
          type: string
      - name: role
        in: query
        description: One of "agent", "end_user". If not specified it does not filter
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketCommentsResponse'
              examples:
                default:
                  $ref: '#/components/examples/RequestListCommentsResponseExample'
  /api/v2/requests/{request_id}/comments/{ticket_comment_id}:
    parameters:
    - $ref: '#/components/parameters/RequestId'
    - $ref: '#/components/parameters/TicketCommentId'
    get:
      operationId: ShowComment
      tags:
      - Requests
      summary: Zendesk Get  Api V2 Requests Request_id Comments Ticket_comment_id
      description: '#### Allowed For


        * End Users

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketCommentResponse'
              examples:
                default:
                  $ref: '#/components/examples/RequestGetCommentResponseExample'
  /api/v2/requests/search:
    get:
      operationId: SearchRequests
      tags:
      - Requests
      summary: Zendesk Get  Api V2 Requests Search
      description: 'Examples:


        * `GET /api/v2/requests/search.json?query=printer`

        * `GET /api/v2/requests/search.json?query=printer&organization_id=1`

        * `GET /api/v2/requests/search.json?query=printer&cc_id=true`

        * `GET /api/v2/requests/search.json?query=printer&status=hold,open`


        #### Pagination


        * Offset pagination only


        See [Using Offset Pagination](/api-reference/introduction/pagination/#using-offset-pagination).


        #### Results limit


        The Search Requests endpoint returns up to 1,000 results per query, with a maximum of 100 results per page. See [Pagination](/api-reference/ticketing/introduction/#pagination). If you request a page past the limit (`page=11` at 100 results per page), a 422 Insufficient Resource Error is returned.


        #### Allowed For


        * End Users

        '
      parameters:
      - name: query
        in: query
        description: The syntax and matching logic for the string is detailed in the [Zendesk Support search reference](https://support.zendesk.com/hc/en-us/articles/203663226). See also [Query basics](/api-reference/ticketing/ticket-management/search/#query-basics) in the Tickets API doc.
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestsResponse'
              examples:
                default:
                  $ref: '#/components/examples/RequestsResponseExample'
components:
  schemas:
    TicketCommentsResponse:
      type: object
      properties:
        comments:
          type: array
          items:
            $ref: '#/components/schemas/TicketCommentObject'
    RequestResponse:
      type: object
      properties:
        request:
          $ref: '#/components/schemas/RequestObject'
    TicketCommentResponse:
      type: object
      properties:
        comment:
          $ref: '#/components/schemas/TicketCommentObject'
    RequestsResponse:
      type: object
      properties:
        requests:
          type: array
          items:
            $ref: '#/components/schemas/RequestObject'