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
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
uuid string true false The UUID of the link (deprecated)
  • 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

Using 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}"

Using 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}"

Using 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

Status 200 OK
{  "count": 1,  "links": [    {      "account_id": 1,      "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"        }      },      "uuid": "ea6ec94a-c92f-c506-3ee7-ab4c09964785"    }  ]}
  • 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"  }}

Using 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

Status 201 Created
{  "link": {    "account_id": 1,    "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"      }    },    "uuid": "ea6ec94a-c92f-c506-3ee7-ab4c09964785"  }}
  • 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"  }}

Using 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

Status 200 OK
{  "link": {    "account_id": 1,    "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"      }    },    "uuid": "ea6ec94a-c92f-c506-3ee7-ab4c09964785"  }}
  • 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

Using 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

Status 204 No Content