Zendesk Requests API

openapi: 3.2.0
info:
  title: Zendesk Requests API
  version: '1.0'
  description: 'Operations tagged Requests across 2 of this provider''s published API definitions: requests-openapi-original.yml, search-openapi-original.yml. Each path carries the servers of the definition it was published in.'
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.'
      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)


        #### Additional properties


        In addition to the writable request properties in the JSON Format table 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

        | 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

        | requester | object | yes* | \*Required for anonymous requests. Specifies the requester of the anonymous request. See 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 |

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


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


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


        #### Results limit


        The Search Requests endpoint returns up to 1,000 results per query, with a maximum of 100 results per page. See 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'
    TicketCommentResponse:
      type: object
      properties:
        comment:
          $ref: '#/components/schemas/TicketCommentObject'
    RequestResponse:
      type: object
      properties:
        request:
          $ref: '#/components/schemas/RequestObject'
    RequestsResponse:
      type: object
      properties:
        requests:
          type: array
          items:
            $ref: '#/components/schemas/RequestObject'
x-refined-from:
- requests-openapi-original.yml
- search-openapi-original.yml