Links

A ZIS Link is a relationship between entities in an integration. The relationship can be one-to-one such as a ticket ID to a Slack thread, or one-to-many such as a ticket ID to many Jira issues. A link contains a left object representing one entity, a right object which is the other entity, and a type assigned to it. See Understanding ZIS Links for information about using links.

The Links API is used for creating, viewing, and managing the storage of links for your integration.

Run in Postman

If you use Postman, you can import the ZIS Links API endpoints as a collection into your Postman app, then try out different requests to learn how the API works. Click the following button to get started:

If you don't use Postman, you can sign up for a free account on the Postman website and download the app. For more information about using Postman with Zendesk APIs, see Exploring Zendesk APIs with Postman.

JSON format

Links are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
account_id	integer	true	true	ID of the account that the link belongs to
created_at	string	true	true	The date and time the Link was created
id	string	true	true	The unique ID of the link
integration	string	true	true	Name of the integration that the link belongs to
left_object	object	false	true	Data of the entity to be linked
link_type	string	false	true	The type assigned to the link
right_object	object	false	true	Data of the entity to be linked
updated_at	string	true	true	The date and time the Link was last updated
uuid	string	true	false	The UUID of the link (deprecated)

Search Links

• GET /api/services/zis/links/{integration}?link_type={link_type}

Searches links by object name. In addition to link_type, you must specify left_object_name, right_object_name, or both.

Pagination

• Cursor pagination

See Pagination.

Returns a maximum of 100 records per page. Defaults to 20 records per page.

Parameters

Name	Type	In	Required	Description
left_object_name	string	Query	false	Left object name to filter by. Supports a trailing wildcard (*) to match an object name based on a prefix. The wildcard must be the last character in the value. A value of only "*" is not supported.
link_type	string	Query	true	Returned links are filtered by the provided link type
right_object_name	string	Query	false	Right object name to filter by. Supports a trailing wildcard (*) to match an object name based on a prefix. The wildcard must be the last character in the value. A value of only "*" is not supported.
integration	string	Path	true	Name of the integration that the link belongs to

Code Samples

cURL

curl 'https://{subdomain}.zendesk.com/api/services/zis/links/{integration}?link_type=example_link&left_object_name=zendesk:ticket1' \
-H "Authorization: Bearer {access_token}"

cURL

curl 'https://{subdomain}.zendesk.com/api/services/zis/links/{integration}?link_type=example_link&left_object_name=zendesk:ticket*' \
-H "Authorization: Bearer {access_token}"

cURL

curl 'https://{subdomain}.zendesk.com/api/services/zis/links/{integration}?link_type=example_link&left_object_name=zendesk:ticket*&right_object_name=external:*' \
-H "Authorization: Bearer {access_token}"

Go

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

func main() {
	url := "https://support.zendesk.com/api/services/zis/links/my_integration?left_object_name=foo%2A&link_type=example_link&right_object_name=foo%2A"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")

	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/links/my_integration")
		.newBuilder()
		.addQueryParameter("left_object_name", "foo*")
		.addQueryParameter("link_type", "example_link")
		.addQueryParameter("right_object_name", "foo*");

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

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://support.zendesk.com/api/services/zis/links/my_integration',
  headers: {
	'Content-Type': 'application/json',
  },
  params: {
    'left_object_name': 'foo%2A',
    'link_type': 'example_link',
    'right_object_name': 'foo%2A',
  },
};

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

Python

import requests

url = "https://support.zendesk.com/api/services/zis/links/my_integration?left_object_name=foo%2A&link_type=example_link&right_object_name=foo%2A"
headers = {
	"Content-Type": "application/json",
}

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

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/services/zis/links/my_integration")
uri.query = URI.encode_www_form("left_object_name": "foo*", "link_type": "example_link", "right_object_name": "foo*")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
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

{
  "count": 1,
  "links": [
    {
      "account_id": 1,
      "created_at": "2022-02-03T09:30:12Z",
      "id": "01FDVK3EZ0CW6ZV1SWV6S0G64T",
      "integration": "my_integration",
      "left_object": {
        "metadata": {
          "ID": 123
        },
        "name": "zendesk:ticket1",
        "name_attrs": {
          "zendesk": "ticket1"
        }
      },
      "link_type": "example_link",
      "right_object": {
        "metadata": {
          "ID": 456
        },
        "name": "external:object1",
        "name_attrs": {
          "external": "object1"
        }
      },
      "updated_at": "2022-03-07T01:23:45Z",
      "uuid": "ea6ec94a-c92f-c506-3ee7-ab4c09964785"
    }
  ],
  "meta": {
    "after": "first_link",
    "before": "twentieth_link",
    "has_more": true
  }
}

400 Bad Request

// Status 400 Bad Request

{
  "errors": [
    {
      "code": "1100",
      "detail": "error message",
      "status": "4XX"
    }
  ]
}

401 Unauthorized

// Status 401 Unauthorized

"Authentication failed"

422 Unprocessable Entity

// Status 422 Unprocessable Entity

{
  "errors": [
    {
      "code": "1100",
      "detail": "error message",
      "status": "4XX"
    }
  ]
}

Create Link

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

Creates a link.

Parameters

Name	Type	In	Required	Description
integration	string	Path	true	Name of the integration that the link belongs to

Example body

{
  "left_object": {
    "metadata": {
      "ID": 123
    },
    "name": "zendesk:ticket1"
  },
  "link_type": "example_link",
  "right_object": {
    "metadata": {
      "ID": 456
    },
    "name": "external:object1"
  }
}

Code Samples

cURL

curl -X POST \
-H "Authorization: Bearer {access_token}" \
https://{subdomain}.zendesk.com/api/services/zis/links/{integration} \
-H 'content-type: application/json' \
-d '{
  "link_type": "example_link",
  "left_object": {
    "name": "zendesk:ticket1",
    "metadata": {
      "ID": 123
    }
  },
  "right_object": {
    "name": "external:object1",
    "metadata": {
      "ID": 456
    }
  }
}'

Go

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

func main() {
	url := "https://support.zendesk.com/api/services/zis/links/my_integration"
	method := "POST"
	payload := strings.NewReader(`{
  "left_object": {
    "metadata": {
      "ID": 123
    },
    "name": "zendesk:ticket1"
  },
  "link_type": "example_link",
  "right_object": {
    "metadata": {
      "ID": 456
    },
    "name": "external:object1"
  }
}`)
	req, err := http.NewRequest(method, url, payload)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")

	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/links/my_integration")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"left_object\": {
    \"metadata\": {
      \"ID\": 123
    },
    \"name\": \"zendesk:ticket1\"
  },
  \"link_type\": \"example_link\",
  \"right_object\": {
    \"metadata\": {
      \"ID\": 456
    },
    \"name\": \"external:object1\"
  }
}""");

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

Nodejs

var axios = require('axios');
var data = JSON.stringify({
  "left_object": {
    "metadata": {
      "ID": 123
    },
    "name": "zendesk:ticket1"
  },
  "link_type": "example_link",
  "right_object": {
    "metadata": {
      "ID": 456
    },
    "name": "external:object1"
  }
});

var config = {
  method: 'POST',
  url: 'https://support.zendesk.com/api/services/zis/links/my_integration',
  headers: {
	'Content-Type': 'application/json',
  },
  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/links/my_integration"

payload = json.loads("""{
  "left_object": {
    "metadata": {
      "ID": 123
    },
    "name": "zendesk:ticket1"
  },
  "link_type": "example_link",
  "right_object": {
    "metadata": {
      "ID": 456
    },
    "name": "external:object1"
  }
}""")
headers = {
	"Content-Type": "application/json",
}

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

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/services/zis/links/my_integration")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
request.body = %q({
  "left_object": {
    "metadata": {
      "ID": 123
    },
    "name": "zendesk:ticket1"
  },
  "link_type": "example_link",
  "right_object": {
    "metadata": {
      "ID": 456
    },
    "name": "external:object1"
  }
})
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

201 Created

// Status 201 Created

{
  "link": {
    "account_id": 1,
    "created_at": "2022-02-03T09:30:12Z",
    "id": "01FDVK3EZ0CW6ZV1SWV6S0G64T",
    "integration": "my_integration",
    "left_object": {
      "metadata": {
        "ID": 123
      },
      "name": "zendesk:ticket1",
      "name_attrs": {
        "zendesk": "ticket1"
      }
    },
    "link_type": "example_link",
    "right_object": {
      "metadata": {
        "ID": 456
      },
      "name": "external:object1",
      "name_attrs": {
        "external": "object1"
      }
    },
    "updated_at": "2022-03-07T01:23:45Z",
    "uuid": "ea6ec94a-c92f-c506-3ee7-ab4c09964785"
  }
}

400 Bad Request

// Status 400 Bad Request

{
  "errors": [
    {
      "code": "1100",
      "detail": "error message",
      "status": "4XX"
    }
  ]
}

401 Unauthorized

// Status 401 Unauthorized

"Authentication failed"

422 Unprocessable Entity

// Status 422 Unprocessable Entity

{
  "errors": [
    {
      "code": "1100",
      "detail": "error message",
      "status": "4XX"
    }
  ]
}

Update Link

• PATCH /api/services/zis/links/{integration}?left_object_name={left_object_name}&link_type={link_type}&right_object_name={right_object_name}

Updates an existing link. The link to patch is identified by the query parameters. All the parameters must be provided and no wildcards are allowed. Note: When updating the left and right object the metadata will be merged. To remove a field from metadata, set it to "null".

Parameters

Name	Type	In	Required	Description
left_object_name	string	Query	true	The left object name of the target Link
link_type	string	Query	true	The link type of the target Link
right_object_name	string	Query	true	The right object name of the target Link
integration	string	Path	true	Name of the integration that the link belongs to

Example body

{
  "left_object": {
    "metadata": {
      "ID": 123
    },
    "name": "zendesk:ticket1"
  },
  "link_type": "example_link",
  "right_object": {
    "metadata": {
      "ID": 456
    },
    "name": "external:object1"
  }
}

Code Samples

cURL

curl -X PATCH \
-H "Authorization: Bearer {access_token}" \
https://{subdomain}.zendesk.com/api/services/zis/links/{integration}?link_type=example_link&left_object_name=zendesk:ticket1&right_object_name=external:object1 \
-H 'content-type: application/json' \
-d '{
  "left_object": {
    "metadata": {
      "ID": "Updated ID"
    }
  },
  "right_object": {
    "metadata": {
      "addedField": 123
      "removedField": null
    }
  }
}'

Go

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

func main() {
	url := "https://support.zendesk.com/api/services/zis/links/my_integration?left_object_name=zendesk%3Aticket1&link_type=example_link&right_object_name=external%3Aobject1"
	method := "PATCH"
	payload := strings.NewReader(`{
  "left_object": {
    "metadata": {
      "ID": 123
    },
    "name": "zendesk:ticket1"
  },
  "link_type": "example_link",
  "right_object": {
    "metadata": {
      "ID": 456
    },
    "name": "external:object1"
  }
}`)
	req, err := http.NewRequest(method, url, payload)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")

	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/links/my_integration")
		.newBuilder()
		.addQueryParameter("left_object_name", "zendesk:ticket1")
		.addQueryParameter("link_type", "example_link")
		.addQueryParameter("right_object_name", "external:object1");
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"left_object\": {
    \"metadata\": {
      \"ID\": 123
    },
    \"name\": \"zendesk:ticket1\"
  },
  \"link_type\": \"example_link\",
  \"right_object\": {
    \"metadata\": {
      \"ID\": 456
    },
    \"name\": \"external:object1\"
  }
}""");

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

Nodejs

var axios = require('axios');
var data = JSON.stringify({
  "left_object": {
    "metadata": {
      "ID": 123
    },
    "name": "zendesk:ticket1"
  },
  "link_type": "example_link",
  "right_object": {
    "metadata": {
      "ID": 456
    },
    "name": "external:object1"
  }
});

var config = {
  method: 'PATCH',
  url: 'https://support.zendesk.com/api/services/zis/links/my_integration',
  headers: {
	'Content-Type': 'application/json',
  },
  params: {
    'left_object_name': 'zendesk%3Aticket1',
    'link_type': 'example_link',
    'right_object_name': 'external%3Aobject1',
  },
  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/links/my_integration?left_object_name=zendesk%3Aticket1&link_type=example_link&right_object_name=external%3Aobject1"

payload = json.loads("""{
  "left_object": {
    "metadata": {
      "ID": 123
    },
    "name": "zendesk:ticket1"
  },
  "link_type": "example_link",
  "right_object": {
    "metadata": {
      "ID": 456
    },
    "name": "external:object1"
  }
}""")
headers = {
	"Content-Type": "application/json",
}

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

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/services/zis/links/my_integration")
uri.query = URI.encode_www_form("left_object_name": "zendesk:ticket1", "link_type": "example_link", "right_object_name": "external:object1")
request = Net::HTTP::Patch.new(uri, "Content-Type": "application/json")
request.body = %q({
  "left_object": {
    "metadata": {
      "ID": 123
    },
    "name": "zendesk:ticket1"
  },
  "link_type": "example_link",
  "right_object": {
    "metadata": {
      "ID": 456
    },
    "name": "external:object1"
  }
})
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

{
  "link": {
    "account_id": 1,
    "created_at": "2022-02-03T09:30:12Z",
    "id": "01FDVK3EZ0CW6ZV1SWV6S0G64T",
    "integration": "my_integration",
    "left_object": {
      "metadata": {
        "ID": 123
      },
      "name": "zendesk:ticket1",
      "name_attrs": {
        "zendesk": "ticket1"
      }
    },
    "link_type": "example_link",
    "right_object": {
      "metadata": {
        "ID": 456
      },
      "name": "external:object1",
      "name_attrs": {
        "external": "object1"
      }
    },
    "updated_at": "2022-03-07T01:23:45Z",
    "uuid": "ea6ec94a-c92f-c506-3ee7-ab4c09964785"
  }
}

400 Bad Request

// Status 400 Bad Request

{
  "errors": [
    {
      "code": "1100",
      "detail": "error message",
      "status": "4XX"
    }
  ]
}

401 Unauthorized

// Status 401 Unauthorized

"Authentication failed"

422 Unprocessable Entity

// Status 422 Unprocessable Entity

{
  "errors": [
    {
      "code": "1100",
      "detail": "error message",
      "status": "4XX"
    }
  ]
}

Delete Link

• DELETE /api/services/zis/links/{integration}?left_object_name={left_object_name}&link_type={link_type}&right_object_name={right_object_name}

Deletes a link.

Parameters

Name	Type	In	Required	Description
left_object_name	string	Query	true	The left object name of the target Link
link_type	string	Query	true	The link type of the target Link
right_object_name	string	Query	true	The right object name of the target Link
integration	string	Path	true	Name of the integration that the link belongs to

Code Samples

cURL

curl 'https://{subdomain}.zendesk.com/api/services/zis/links/{integration}?link_type=example_link&left_object_name=zendesk:ticket1&right_object_name=external:object1' \
-H "Authorization: Bearer {access_token}" \
-X DELETE

Go

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

func main() {
	url := "https://support.zendesk.com/api/services/zis/links/my_integration?left_object_name=zendesk%3Aticket1&link_type=example_link&right_object_name=external%3Aobject1"
	method := "DELETE"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")

	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/links/my_integration")
		.newBuilder()
		.addQueryParameter("left_object_name", "zendesk:ticket1")
		.addQueryParameter("link_type", "example_link")
		.addQueryParameter("right_object_name", "external:object1");

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

Nodejs

var axios = require('axios');

var config = {
  method: 'DELETE',
  url: 'https://support.zendesk.com/api/services/zis/links/my_integration',
  headers: {
	'Content-Type': 'application/json',
  },
  params: {
    'left_object_name': 'zendesk%3Aticket1',
    'link_type': 'example_link',
    'right_object_name': 'external%3Aobject1',
  },
};

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

Python

import requests

url = "https://support.zendesk.com/api/services/zis/links/my_integration?left_object_name=zendesk%3Aticket1&link_type=example_link&right_object_name=external%3Aobject1"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"DELETE",
	url,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/services/zis/links/my_integration")
uri.query = URI.encode_www_form("left_object_name": "zendesk:ticket1", "link_type": "example_link", "right_object_name": "external:object1")
request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

204 No Content

// Status 204 No Content

null

400 Bad Request

// Status 400 Bad Request

{
  "errors": [
    {
      "code": "1100",
      "detail": "error message",
      "status": "4XX"
    }
  ]
}

401 Unauthorized

// Status 401 Unauthorized

"Authentication failed"

404 Not Found

// Status 404 Not Found

null

422 Unprocessable Entity

// Status 422 Unprocessable Entity

{
  "errors": [
    {
      "code": "1100",
      "detail": "error message",
      "status": "4XX"
    }
  ]
}