Integrations

Use the Create integration endpoint to register a ZIS integration. You can then create resources and workflows for the integration.

JSON format

Integrations are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
description	string	true	false	The description of the integration
jwt_public_key	string	true	false	The public key of the JWT
zendesk_oauth_client	object	false	false	OAuth client for Zendesk. ZIS automatically creates this client when you register the integration.

List Integrations

• GET /api/services/zis/registry/integrations

List all integrations

Authentication

You can authorize requests using basic authentication, an API token, A Zendesk app can also authorize requests to this endpoint using an admin's browser session. See Making API requests from a Zendesk app.

Allowed for

• Admins

Code Samples

cURL

curl https://{subdomain}.zendesk.com/api/services/zis/registry/integrations \
-u {email_address}/token:{api_token} \
-X GET \
-H "Content-Type: application/json"

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://support.zendesk.com/api/services/zis/registry/integrations"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/services/zis/registry/integrations")
		.newBuilder();
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://support.zendesk.com/api/services/zis/registry/integrations',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests
from requests.auth import HTTPBasicAuth

url = "https://support.zendesk.com/api/services/zis/registry/integrations"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"GET",
	url,
	auth=auth,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://support.zendesk.com/api/services/zis/registry/integrations")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// Status 200 OK

{
  "integrations": [
    {
      "description": "example my_integration",
      "jwt_public_key": "The RSA Public Key to be saved",
      "name": "my_integration",
      "zendesk_oauth_client": {
        "id": 10066,
        "identifier": "zis_my_integration",
        "secret": "************"
      }
    }
  ]
}

400 Bad Request

// Status 400 Bad Request

{
  "errors": [
    {
      "code": "1010",
      "detail": "error message",
      "status": "400"
    }
  ],
  "message": "Unauthorized"
}

401 Unauthorized

// Status 401 Unauthorized

{
  "errors": [
    {
      "code": "1001",
      "detail": "error message",
      "status": "401"
    }
  ],
  "message": "Unauthorized"
}

500 Internal Server Error

// Status 500 Internal Server Error

{
  "errors": [
    {
      "code": "1050",
      "detail": "error message",
      "status": "500"
    }
  ],
  "message": "Server Error"
}

Create Integration

• POST /api/services/zis/registry/{integration}

Creates an integration using the specified integration parameter.

Authentication

You can authorize requests using basic authentication, an API token, or OAuth token with zis:write permission

A Zendesk app can also authorize requests to this endpoint using an admin's browser session. See Making API requests from a Zendesk app.

Allowed for

• Admins

Deleting an integration

You can’t delete an integration. However, you can uninstall a job spec to stop a flow from executing. Alternatively, you can use the respective delete endpoint to remove resources that are no longer needed.

Parameters

Name	Type	In	Required	Description
integration	string	Path	true	The name of the integration. integration can be up to 64 characters long. It can only include lower-case letters (a-z), numbers, dash (-), and underscore (_) characters

Example body

{
  "description": "example integration"
}

Code Samples

cURL

curl https://{subdomain}.zendesk.com/api/services/zis/registry/{integration} \
-u {email_address}/token:{api_token} \
-X POST \
-H "Content-Type: application/json" \
-d '{"description":"example integration"}'

Go

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://support.zendesk.com/api/services/zis/registry/my_integration"
	method := "POST"
	payload := strings.NewReader(`{
  "description": "example integration"
}`)
	req, err := http.NewRequest(method, url, payload)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/services/zis/registry/my_integration")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"description\": \"example integration\"
}""");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("POST", body)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');
var data = JSON.stringify({
  "description": "example integration"
});

var config = {
  method: 'POST',
  url: 'https://support.zendesk.com/api/services/zis/registry/my_integration',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
  data : data,
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests
import json
from requests.auth import HTTPBasicAuth

url = "https://support.zendesk.com/api/services/zis/registry/my_integration"

payload = json.loads("""{
  "description": "example integration"
}""")
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"POST",
	url,
	auth=auth,
	headers=headers,
	json=payload
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://support.zendesk.com/api/services/zis/registry/my_integration")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
request.body = %q({
  "description": "example integration"
})
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// Status 200 OK

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

400 Bad Request

// Status 400 Bad Request

{
  "errors": [
    {
      "code": "1010",
      "detail": "error message",
      "status": "400"
    }
  ],
  "message": "Unauthorized"
}

401 Unauthorized

// Status 401 Unauthorized

{
  "errors": [
    {
      "code": "1001",
      "detail": "error message",
      "status": "401"
    }
  ],
  "message": "Unauthorized"
}

500 Internal Server Error

// Status 500 Internal Server Error

{
  "errors": [
    {
      "code": "1050",
      "detail": "error message",
      "status": "500"
    }
  ],
  "message": "Server Error"
}