Jira Integration API

The official Jira integration service by Zendesk provides streamlined collaboration experience for your support and engineering teams by bringing Zendesk Support and Jira together. The integration service consists of a Zendesk Support app, a Jira app, and a middleware that provides backend functionalities and data storage for apps. This article focuses on the API endpoints that we expose from the middleware backend to allow further customization of the integration to fit your particular requirements.

Authentication

The Jira Integration API is part of the Zendesk API. It allows an authenticated admin user to view and create links between your Jira and Zendesk instances. Authentication works as described in the main Zendesk API documentation.

Links

Users can create, list and delete links, which are the connections between a Jira issue and a Zendesk ticket.

JSON Format

Links have the following keys:

Name Type Read-only Mandatory Comment
id integer yes no Automatically assigned when the link is created
ticket_id integer no yes The id of the Zendesk ticket
issue_id integer no yes The id of the Jira issue
issue_key string no yes The key for the Jira issue
created_at timestamp yes no The time at which the link was created
updated_at timestamp yes no The time at which the link was last updated

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
{
  "id":         1234,
  "ticket_id":  5000,
  "issue_id":   5460,
  "issue_key":  "TEST-5460",
  "created_at": "2017-01-01T09:30:00Z",
  "updated_at": "2017-01-01T09:30:00Z"
}

List Links

GET /api/services/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 since_id and limit param:

Name Default
since_id 0
limit 1000
Using curl
curl -u {email_address}:{password} \
  https://{subdomain}.zendesk.com/api/services/jira/links
Example Response
Status: 200 OK

{
  "links": [
    {
      "id":         1234,
      "ticket_id":  5000,
      "issue_id":   5460,
      "issue_key":  "TEST-5460",
      "created_at": "2017-01-01T09:30:00Z",
      "updated_at": "2017-01-01T09:30:00Z"
    },
    ...
  ]
}

GET /api/services/jira/links?ticket_id=5000

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_address}:{password} \
  https://{subdomain}.zendesk.com/api/services/jira/links?ticket_id=5000
Example Response
Status: 200 OK

{
  "links": [
    {
      "id":         1234,
      "ticket_id":  5000,
      "issue_id":   5460,
      "issue_key":  "TEST-5460",
      "created_at": "2017-01-01T09:30:00Z",
      "updated_at": "2017-01-01T09:30:00Z"
    },
    ...
  ]
}

Show Link

GET /api/services/jira/links/{id}

Retrieves a single link.

Using curl
curl -u {email_address}:{password} \
  https://{subdomain}.zendesk.com/api/services/jira/links/{id}
Example Response
Status: 200 OK

{
  "link": {
    "id":         1234,
    "ticket_id":  5000,
    "issue_id":   5460,
    "issue_key":  "TEST-5460",
    "created_at": "2017-01-01T09:30:00Z",
    "updated_at": "2017-01-01T09:30:00Z"
  }
}

Create Link

POST /api/services/jira/links

Creates a link.

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
Location: https://{subdomain}.zendesk.com/api/services/jira/links/{id}

{
  "link": {
    "id":         1235,
    "ticket_id":  5001,
    "issue_id":   5461,
    "issue_key":  "TEST-5461",
    "created_at": "2017-01-01T12:30:00Z",
    "updated_at": "2017-01-01T12:30:00Z"
  }
}

Delete Link

DELETE /api/services/jira/links/{id}

Removes the given link.

curl -X DELETE \
-u {email_address}:{password} \
https://{subdomain}.zendesk.com/api/services/jira/links/{id}
Example Response
Status: 204 No Content