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. SeeUnderstanding ZIS Linksfor 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:
如果你不使用邮递员,你可以注册一个free account on thePostman websiteand download the app. For more information about using Postman with Zendesk APIs, seeExploring 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 tolink_type
, you must specifyleft_object_name
,right_object_name
, or both.
Pagination
- Cursor pagination
SeePagination.
Returns a maximum of 100 records per page. Defaults to 20 records per page.
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
left_object_name | string | 查询 | 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 | 查询 | true | Returned links are filtered by the provided link type |
right_object_name | string | 查询 | 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
旋度'https://{subdomain}.zendesk.com/api/services/zis/links/{integration}?link_type=example_link&left_object_name=zendesk:ticket1'\
-H"Authorization: Bearer {access_token}"
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
旋度'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"
)
funcmain(){
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)
iferr!=nil{
fmt.Println(err)
return
}
req.Header.Add("Content-Type","application/json")
client:=&http.Client{}
res,err:=client.Do(req)
iferr!=nil{
fmt.Println(err)
return
}
deferres.Body.Close()
body,err:=io.ReadAll(res.Body)
iferr!=nil{
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
importcom.squareup.okhttp.*;
OkHttpClientclient=newOkHttpClient();
HttpUrl.BuilderurlBuilder=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*");
Requestrequest=newRequest.Builder()
.url(urlBuilder.build())
.method("GET",null)
.addHeader("Content-Type","application/json")
.build();
Responseresponse=client.newCall(request).execute();
Nodejs
varaxios=require('axios');
varconfig={
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
importrequests
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:truedo|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}
创建一个链接。
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
旋度-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"
)
funcmain(){
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)
iferr!=nil{
fmt.Println(err)
return
}
req.Header.Add("Content-Type","application/json")
client:=&http.Client{}
res,err:=client.Do(req)
iferr!=nil{
fmt.Println(err)
return
}
deferres.Body.Close()
body,err:=io.ReadAll(res.Body)
iferr!=nil{
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
importcom.squareup.okhttp.*;
OkHttpClientclient=newOkHttpClient();
HttpUrl.BuilderurlBuilder=HttpUrl.parse("https://support.zendesk.com/api/services/zis/links/my_integration")
.newBuilder();
RequestBodybody=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\"
}
}""");
Requestrequest=newRequest.Builder()
.url(urlBuilder.build())
.method("POST",body)
.addHeader("Content-Type","application/json")
.build();
Responseresponse=client.newCall(request).execute();
Nodejs
varaxios=require('axios');
vardata=JSON.stringify({
"left_object":{
"metadata":{
"ID":123
},
"name":"zendesk:ticket1"
},
"link_type":"example_link",
"right_object":{
"metadata":{
"ID":456
},
"name":"external:object1"
}
});
varconfig={
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
importrequests
importjson
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:truedo|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. Toremovea field from metadata, set it to "null".
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
left_object_name | string | 查询 | true | The left object name of the target Link |
link_type | string | 查询 | true | The link type of the target Link |
right_object_name | string | 查询 | 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
旋度-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"
)
funcmain(){
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)
iferr!=nil{
fmt.Println(err)
return
}
req.Header.Add("Content-Type","application/json")
client:=&http.Client{}
res,err:=client.Do(req)
iferr!=nil{
fmt.Println(err)
return
}
deferres.Body.Close()
body,err:=io.ReadAll(res.Body)
iferr!=nil{
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
importcom.squareup.okhttp.*;
OkHttpClientclient=newOkHttpClient();
HttpUrl.BuilderurlBuilder=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");
RequestBodybody=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\"
}
}""");
Requestrequest=newRequest.Builder()
.url(urlBuilder.build())
.method("PATCH",body)
.addHeader("Content-Type","application/json")
.build();
Responseresponse=client.newCall(request).execute();
Nodejs
varaxios=require('axios');
vardata=JSON.stringify({
"left_object":{
"metadata":{
"ID":123
},
"name":"zendesk:ticket1"
},
"link_type":"example_link",
"right_object":{
"metadata":{
"ID":456
},
"name":"external:object1"
}
});
varconfig={
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
importrequests
importjson
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:truedo|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"
}
]
}
删除Link
DELETE /api/services/zis/links/{integration}?left_object_name={left_object_name}&link_type={link_type}&right_object_name={right_object_name}
删除s a link.
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
left_object_name | string | 查询 | true | The left object name of the target Link |
link_type | string | 查询 | true | The link type of the target Link |
right_object_name | string | 查询 | 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
旋度'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"
)
funcmain(){
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)
iferr!=nil{
fmt.Println(err)
return
}
req.Header.Add("Content-Type","application/json")
client:=&http.Client{}
res,err:=client.Do(req)
iferr!=nil{
fmt.Println(err)
return
}
deferres.Body.Close()
body,err:=io.ReadAll(res.Body)
iferr!=nil{
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
importcom.squareup.okhttp.*;
OkHttpClientclient=newOkHttpClient();
HttpUrl.BuilderurlBuilder=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");
Requestrequest=newRequest.Builder()
.url(urlBuilder.build())
.method("DELETE",null)
.addHeader("Content-Type","application/json")
.build();
Responseresponse=client.newCall(request).execute();
Nodejs
varaxios=require('axios');
varconfig={
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
importrequests
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::删除.new(uri,"Content-Type":"application/json")
response=Net::HTTP.start uri.hostname,uri.port,use_ssl:truedo|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"
}
]
}