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.
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) |
Show Links
GET /api/services/zis/links/{integration}?link_type={link_type}
Queries links by object name. At least one of the left object name or right object name must be provided.
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
left_object_name | string | Query | false | Left object name to filter by. Accepts an asterisk (* ) as a wildcard to match multiple scopes |
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. Accepts an asterisk (* ) as a wildcard to match multiple scopes |
integration | string | Path | true | Name of the integration that the link belongs to |
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}"
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"
}
}
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
}
}
}'
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"
}
}
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
}
}
}'
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 |
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
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"
}
]
}