This documentation describes an old release, version 2025.1.22. Documentation for the latest release, 2025.4.24, can be found here.

Zendesk Input

Overview

Inputter is an HTTP input which uses Python zenpy library. Because of that the configuration uses collections that zenpy library exposes in form of API.

For example: we want to access Tickets API and pull tickets using incremental. The inputter configuration will look like this:

{
  "use": "zendesk.io.ZendeskInput",
  "collection_path": ["tickets", "incremental"]
}

We use a collection_path parameter to allow access to nested collections. For example:

{
  "use": "zendesk.io.ZendeskInput",
  "collection_path": ["tickets", "incremental"],
  "includes": ["user"]  // where 'user' is additianally requested to the 'tickets'
}

Specific logic

CHATS

All Chat related Endpoints require another type of authorization credentials. We have to replace creds with auth2 token.

You must register your application to generate OAuth credentials that your application can use to authenticate API calls to Zendesk. Docs: https://support.zendesk.com/hc/en-us/articles/4408845965210-Using-OAuth-authentication-with-your-application#topic_pbc_cdl_1l

Example:

{
  "subdomain": "test_subdomain",
  "auth2_token": "tyuinmf56789knbgf/knkjvjh"
}

SEARCH

In Search endpoint there is an extra field “search_query” where you can provide your search request: Example:

{
    "input": {
        "credentials": {},
        "use": "zendesk.io#ZendeskInput",
        "collection_path": [
            "search"
        ],
        "include": [],
        "search_query": "Please provide search query"
    }

ATTACHMENTS

In Attachment endpoint there is an extra field “id” where you can provide your attachment_id: Example:

{
    "input": {
        "credentials": {},
        "use": "zendesk.io#ZendeskInput",
        "collection_path": [
            "attachments"
        ],
        "id": ""
    }

Site loading

Several Endpoints support extra parameter to get additional info during one job call. List of supported: https://developer.zendesk.com/documentation/ticketing/using-the-zendesk-api/side_loading/#supported-endpoints

Example: ["talk", "calls", "incremental"].

Upsert

Upsert can be used only for endpoints that support start_time parameter. Usually it’s used only with incremental endpoint.

Tickets and Ticket Fields

For Tickets API the input will include ticket_fields and add every field to a ticket row (root row). The field has the following format:"cr_" + field["id"]). And the ticket row will look like this:

{
  ...,
  "cr_description": "field_value",
  "cr_status": false,
  "cr_subject": null,
  "cr...": "..."
}

Extend Resources

It is possible to extend root record with result of another API resource using extend_resources configuration field.

Having the following inputter configuration

{
  "use": "zendesk.io.ZendeskInput",
  "collection_path": ["tickets", "incremental"],
  "extend_resources": [
    {
      "collection_path": ["tickets", "metrics"]
    }
  ]
}

extend_resources will be applied for each root record. In this example the input will make one additional HTTP requests per ticket record. The call list would look like this:

GET /tickets

GET tickets/1/metrics
GET tickets/2/metrics
GET tickets/.../metrics

The resulting inputter records will look like this:

[
  {
    "id": 1111,
    "title": "Ticket 1",
    "tickets_metrics": [
      {"id": 1, "ticket_id": 1111, "solved_at": "2020-07-20T06:21:26Z", ...},
      {"id": 2, "ticket_id": 1111, "solved_at": "2020-07-20T06:21:26Z", ...},
      ...
    ]
  },
  {
    "id": 1222,
    "title": "Ticket 2",
    "tickets_metrics": [
      {"id": 11, "ticket_id": 1222, "solved_at": "2020-07-20T06:21:26Z", ...},
      {"id": 12, "ticket_id": 1222, "solved_at": "2020-07-20T06:21:26Z", ...},
      ...
    ]
  },
  ...
]

Configuration Errors

Invalid ‘collection_path’:

{
  "use": "zendesk.io.ZendeskInput",
  "collection_path": ["tickets", "invalid_collection"]
}

‘collection_path’ is not callable;

{
  "use": "zendesk.io.ZendeskInput",
  "collection_path": ["tickets", "non_callable_attribute"]
}

Input reference: