Zendesk Integration Services (ZIS) lets you build and run private integrations in your Zendesk instance. This article describes the main steps for developing and managing a private integration.

ZIS is available on the Suite Growth plan or above, and the Support Professional plan or above.

Zendesk recommends building and testing a private integration in a sponsored test account before running it in a customer account.

This article covers the following development workflow:

Registering the integration name

The first step in building an integration is registering the name of the integration with the ZIS Registry Service.

To register the integration, make a POST request to the Create Integration endpoint specifying a unique name for the integration.

Example:

curl https://example.zendesk.com/api/services/zis/registry/slack_integration_development_acme1234 \  -d '{"description": "An example integration"}' \  -H "Content-type: application/json" \  -v -u [email protected]:northw00ds -X POST

The request registers an integration named slack_integration_development_acme1234.

The integration name can be a string up to 64 characters long consisting of lower-case letters (a-z), numbers, the dash (-) character, or the underscore (_) character.

Since the name of an integration must be globally unique, use one name when building an integration in your test account and a different name when running it in production in your customer's account. For example, you can use “slack_integration_development_acme1234” in your developer account and “slack_integration_acme1234” in your customer account.

You can authorize the API request using basic authentication or a Zendesk API token. See Security and authentication in the Zendesk API documentation.

You must be a Zendesk admin to make the API request. If you're not an admin, ask an admin in your organization to assign the admin role to you.

If successful, the response returns OAuth client details. Example:

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

Save the client identifier and secret values, which you'll use to obtain a ZIS OAuth token in the next step.

Obtaining a ZIS OAuth token

A ZIS OAuth token lets developers access ZIS services when building and testing integrations without having to be Zendesk admins.

The OAuth flow will require you to sign in as a Zendesk admin to grant access to the Zendesk account.

You can get a ZIS OAuth token by making a request to the ZIS Connections API. Before you start, you’ll need the client identifier and secret values you received when you registered the integration name in the previous step.

Postman is recommended for getting the token.

To get an OAuth token

  1. In Postman, create a new request and leave the request URL empty for now.

  2. Select the Authorization tab.

  3. Choose OAuth 2.0 from the Type menu.

  4. Complete the Configure New Token section with the following information:

    Field Value Notes
    Token Name A token name Example: "my ZIS token"
    Grant Type Authorization Code
    Callback URL https://zis.zendesk.com/api/services/zis/connections/oauth/callback Leave "Authorize using browser" unchecked
    Auth URL https://{subdomain}.zendesk.com/oauth/authorizations/new Replace {subdomain} with your Zendesk subdomain
    Access Token URL https://{subdomain}.zendesk.com/oauth/tokens Replace {subdomain} with your Zendesk subdomain
    Client ID The client identifier returned after registering the integration The string starts with zis_
    Client Secret The client secret returned after registering the integration
    Scope read write See Using OAuth authentication with your application to learn more about Zendesk OAuth scopes
    State Leave blank
    Client Authentication **Send as Basic Auth header **

    Here's an example of what your setup should look like:

  5. Click Get New Access Token.

    A popup browser window appears to take you through the OAuth flow. Sign in as a Zendesk admin and grant access. After granting access, a window opens in Postman that displays the newly obtained access token:

  6. If you want to use the token in Postman requests, click Use Token in the upper-right corner. The token is saved in the Authorization options of the current collection.

  7. Save the access token in a safe place.

Creating a ZIS bundle

A ZIS Bundle is a JSON object that defines the logic of your integration. It contains three types of nested objects:

  • Action objects specify the work to be done
  • Flow objects specify the actions to run in what order
  • JobSpec objects specify the flows to run when given events happen

See Anatomy of a ZIS bundle.

To create a simple bundle for testing, see Building your first ZIS integration.

Uploading the ZIS bundle

To deploy your integration, upload the bundle to the ZIS Registry Service using the Upload or Update Bundle endpoint.

Example request:

curl https://example.zendesk.com/api/services/zis/registry/slack_integration_development_acme1234/bundles \  -d @my_bundle_file.json \  -H "Content-type: application/json" \  -v -u [email protected]:northw00ds -X POST

If the bundle was uploaded successfully, the request returns an empty 200 response.

Installing the jobspec

A ZIS JobSpec is an object in the ZIS bundle that specifies the flow to run when a given event happens. Example:

"react_to_ticket_created_job_spec": {  "type": "ZIS::JobSpec",  "properties": {    "name": "react_to_ticket_created_job_spec",    "event_source": "support",    "event_type": "ticket.TicketCreated",    "flow_name": "zis:my_integration:flow:my_new_ticket_flow"  }}

After uploading your ZIS bundle, you need to tell ZIS to install each jobspec contained in the uploaded bundle.

To install a jobspec, make an API request to the Install JobSpec endpoint.

Example request:

curl "https://example.zendesk.com/api/services/zis/registry/job_specs/install?job_spec_name=zis:slack_integration_development_acme1234:job_spec:handle-ticket-created-event" \  -H "Authorization: Bearer 29cb46de50dd1d7d600fc1057e7b72" \  -X POST

Make sure to enclose the endpoint in quotes because of the special characters.

If the jobspec was uploaded successfully, the request returns an empty 200 response.

Testing and updating the integration

You can test your the ZIS integration after deploying it. The workflow is to test, update the ZIS bundle locally, upload the bundle, then test the update.

See Uploading the ZIS bundle for more information.

You can use the integrations log in the Zendesk Admin Center to help troubleshoot issues:

  1. Sign into your Zendesk account as a admin.

  2. In Admin Center, click Apps and integrations in the sidebar, then select Integrations > Logs.

For more information, see Viewing the integrations log in the Zendesk help center.

Disabling the integration

You can disable a private integration by uninstalling the JobSpec in a customer’s account using the Uninstall JobSpec endpoint.

Example request:

curl "https://example.zendesk.com/api/services/zis/registry/job_specs/install?job_spec_name=zis:slack_integration_development_acme1234:job_spec:handle-ticket-created-event" \  -H "Authorization: Bearer 29cb46de50dd1d7d600fc1057e7b72" \  -X DELETE

If the jobspec was uninstalled successfully, the request returns an empty 204 response.