Links
Users can create, list and delete links, which are the connections between a Jira issue and a Zendesk ticket.
JSON Format
Links are represented as JSON objects with the following properties:
Name | Type | Read-only | Mandatory | Description |
---|---|---|---|---|
created_at | string | true | false | The time at which the link was created |
id | integer | true | false | Automatically assigned when the link is created |
issue_id | string | false | true | The id of the Jira issue |
issue_key | string | false | true | The key for the Jira issue |
ticket_id | integer | false | true | The id of the Zendesk ticket |
updated_at | string | true | false | The time at which the link was last updated |
url | string | false | false | An url to get the link details |
The Jira integration uses issue_id
to identify an issue. issue_id
is used over issue_key
because issue_id
is immutable. An issue_key
might change after an issue is moved to a different project.
You can get an issue's ID using the instructions here or via the Jira REST API: Cloud, Server.
issue_key
is also mandatory because it is used to support syncing issue keys to tickets. You can read more about the field sync feature here.
Example
{
"created_at": "2017-01-01T09:30:00Z",
"id": 1234,
"issue_id": "5460",
"issue_key": "TEST-5460",
"ticket_id": 5000,
"updated_at": "2017-01-01T09:30:00Z"
}
List Links
GET /api/v2/jira/links
Lists the links for the current account, ordered by ID.
Pagination
By default, this endpoint retrieves 1000 links per page. You can walk through
the available links and customize the page size with a combination of a
page[after]
and page[size]
param:
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
filter[ticket_id] | integer | Query | false | List links for a specific Zendesk Ticket or Jira issue by providing ticket_id and/or issue_id param. We currently do not support issue_key param. |
page[after] | integer | Query | false | when page[after] is provided, the returned paginated data MUST have as its first item the item that is immediately after the cursor in the results list. (An exception is that, if there are no items in the results list that fall after the cursor, the returned paginated data MUST be an empty array.) |
page[size] | integer | Query | false | The number of entries that will be returned |
Using cURL
curl -u {email}:{password} -X GET \
https://{subdomain}.zendesk.com/api/v2/jira/links
# filter links by ticket
curl -u {email_address}:{password} \
https://{subdomain}.zendesk.com/api/v2/jira/links?filter[ticket_id]=5000
Example Response
Status 200 OK
{
"links": [
{
"created_at": "2017-01-01T09:30:00Z",
"id": 1234,
"issue_id": "5460",
"issue_key": "TEST-5460",
"ticket_id": 5000,
"updated_at": "2017-01-01T09:30:00Z"
}
],
"meta": {
"after_cursor": "https://{subdomain}.zendesk.com/api/v2/jira/links?page[after]=5000",
"has_more": true
}
}
Show Link
GET /api/services/jira/links/{link_id}
Retrieves a single link.
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
link_id | integer | Path | true | The ID of the link |
Using cURL
curl -u {email}:{password} -X GET \
https://{subdomain}.zendesk.com/api/services/jira/links/{id}
Example Response
Status 200 OK
{
"link": {
"created_at": "2017-01-01T09:30:00Z",
"id": 1234,
"issue_id": "5460",
"issue_key": "TEST-5460",
"ticket_id": 5000,
"updated_at": "2017-01-01T09:30:00Z",
"url": "https://subdomain.zendesk.com/api/services/jira/links/1234"
}
}
Create Link
POST /api/services/jira/links
Creates a link.
Example Body
{
"link": {
"issue_id": "5461",
"issue_key": "TEST-5461",
"ticket_id": 5001
}
}
Using cURL
curl -X POST \
-H "Content-Type: application/json" \
-u {email_address}:{password} \
-d '{"link": {"ticket_id": 5001, "issue_id": "5461", "issue_key": "TEST-5461"}}' \
https://{subdomain}.zendesk.com/api/services/jira/links
Example Response
Status 201 Created
{
"link": {
"created_at": "2017-01-01T09:30:00Z",
"id": 1234,
"issue_id": "5460",
"issue_key": "TEST-5460",
"ticket_id": 5000,
"updated_at": "2017-01-01T09:30:00Z",
"url": "https://subdomain.zendesk.com/api/services/jira/links/1234"
}
}
Delete Link
DELETE /api/services/jira/links/{link_id}
Removes the given link.
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
link_id | integer | Path | true | The ID of the link |
Using cURL
curl -X DELETE \
-u {email_address}:{password} \
https://{subdomain}.zendesk.com/api/services/jira/links/{id}
Example Response
Status 204 No Content
List Links (deprecated)
GET /api/services/jira/links
Note: This endpoint is deprecated. Use the new List Links endpoint (GET /api/v2/jira/links
) instead.
Lists the links for the current account, ordered by ID.
Pagination
By default, this endpoint retrieves 1000 links per page. You can walk through
the available links and customize the page size with a combination of a
since_id
and limit
param:
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
limit | integer | Query | false | The number of entries that will be returned |
since_id | integer | Query | false | The start ID of the collection |
ticket_id | integer | Query | false | List links for a specific Zendesk Ticket or Jira issue by providing ticket_id and/or issue_id param. We currently do not support issue_key param. |
Using cURL
curl -u {email}:{password} -X GET \
https://{subdomain}.zendesk.com/api/services/jira/links
# filter links by ticket
curl -u {email_address}:{password} \
https://{subdomain}.zendesk.com/api/services/jira/links?ticket_id=5000
Example Response
Status 200 OK
{
"links": [
{
"created_at": "2017-01-01T09:30:00Z",
"id": 1234,
"issue_id": "5460",
"issue_key": "TEST-5460",
"ticket_id": 5000,
"updated_at": "2017-01-01T09:30:00Z"
}
]
}