Integrations
The Integrations API provides an endpoint to register an integration of another system with ZIS. This enables you to create ZIS resources and workflows.
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 |
Create Integration
POST /api/services/zis/registry/{integration}
Creates an integration using the specified integration
parameter.
Authentication
You can authorize requests using basic authentication or an API token.
Allowed for
- Admins
Deleting an integration
You can't delete an integration. However, you can disable it by uninstalling its JobSpec. See the Uninstall JobSpec endpoint.
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}:{password} \
-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 "username:password"
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\"
}""");
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("POST", body)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
.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 "username:password"
},
data : data,
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python
import requests
import json
url = "https://support.zendesk.com/api/services/zis/registry/my_integration"
payload = json.loads("""{
"description": "example integration"
}""")
headers = {
"Content-Type": "application/json",
}
response = requests.request(
"POST",
url,
auth=('<username>', '<password>'),
headers=headers,
json=payload
)
print(response.text)
Ruby
require "net/http"
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"
})
request.basic_auth "username", "password"
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"
}