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 by making an API call to the Create Integration endpoint. The name of your integration <YOUR_INTEGRATION> is specified in the request URL, and needs to be globally unique.

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

Make an API request and include a description in request body. To authenticate your request, you can use basic authentication with a Zendesk username and password or an API token. If you haven't already, check that API access is enabled in Admin Center under Apps and Integrations > APIs > Zendesk APIs. See Using the API dashboard.

Example cURL request using basic authentication:

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