Building your first integration - Part 1: Creating an integration

This three part tutorial series has been designed to gradually introduce Zendesk Integration Services (ZIS) concepts, starting with building a simple integration and incrementally adding new features. The integration you'll build reacts to Ticket Created events and posts the events to a webhook URL.

The other tutorials in the series will teach you how to build an integration:

If you haven’t done so already, we suggest reading Understanding Zendesk Integration Services (ZIS) and Anatomy of a ZIS Bundle before you begin. Then go through each tutorial in order and finish them before moving on to the next one.

Note: To avoid manipulating data such as tickets and users on your Zendesk account, we recommend using a trial or developer account.

Prerequisites

To start using ZIS, you’ll need the following:

  1. A Zendesk account for testing - If you don't already have a test account, you can obtain a free developer Zendesk account. See Getting a trial or sponsored account for development.
  2. ZIS enabled on that Zendesk account - You can create ZIS-based integrations to use on your own Zendesk instance on:
    • Zendesk Suite Growth plan or above
    • Support Professional plan or above

Creating an integration

In this step, you'll register the integration with ZIS. This is done using the ZIS Registry API. The name of your integration <YOUR_INTEGRATION> is specified in the request URL, and needs to be globally unique.

Your integration name can be up to 64 characters long. It can only include lower-case letters (a-z), numbers, and dash (-) and underscore (_) characters.

To authenticate requests, you can use basic authentication with a Zendesk username and password or an API token. If you haven't already, you'll need to enable API access in your Admin Center under Apps and Integrations > APIs > Zendesk APIs. For more information, see Using the API dashboard.

Example request using Basic Auth:

curl \  --request POST \  --url https://<SUBDOMAIN>.zendesk.com/api/services/zis/registry/<YOUR_INTEGRATION> \  --user <EMAIL>:<PASSWORD> \  --header 'content-type: application/json' \  --data '{"description": "An example integration"}'

Example request using an API token:

curl \  --request POST \  --url https://<SUBDOMAIN>.zendesk.com/api/services/zis/registry/<YOUR_INTEGRATION> \  --user <EMAIL>/token:<API_TOKEN> \  --header 'content-type: application/json' \  --data '{"description": "An example integration"}'

Replace <API_TOKEN> with API token generated in the Zendesk admin interface.

Example response:

{  "description": "An example integration",  "jwt_public_key": "***The RSA Public Key to be saved***",  "zendesk_oauth_client": {    "id": 10066,    "identifier": "zis_<SUBDOMAIN>_<YOUR_INTEGRATION>",    "secret": "***secret***"  }}

Save the response securely as you'll be using some of the values in other tutorials in the series.

Next: Part 2- Obtaining an OAuth token