JIRA Integration Links (V2)

JIRA Links represent the association between a Zendesk ticket and a Jira issue. When a link is created, updates to the linked Jira issue can be synced to the Zendesk ticket and vice versa.

Note: Zendesk will be delisting the Jira Integration V2 and re-listing the original version. Customers already on V2 should remain on V2 and will be supported by Zendesk for now. Zendesk will reach out to V2 customers with next steps.

Overview

• A Zendesk ticket can be linked to multiple Jira issues
• A Jira issue can be linked to multiple Zendesk tickets
• Links are bidirectional and enable data synchronization between the two systems

JSON format

JIRA Integration Links (V2) are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
issue_id	string	false	true	The ID of the Jira issue
issue_key	string	false	true	The key of the Jira issue (e.g., "PROJ-123")
ticket_id	string	false	true	The ID of the Zendesk ticket

Represents a link between a Zendesk ticket and a Jira issue.

Properties

Property	Type	Description
ticket_id	string	The id of the Zendesk ticket
issue_id	string	The id of the Jira issue
issue_key	string	The key for the Jira issue (e.g., "PROJ-123")
external_id	string	The external identifier for the link. To get this value, go to the Zendesk Admin Center, then select Apps and integrations > Integrations > Jira > Edit.

List Links

• GET /api/v2/integrations/jira/{external_id}/links

Lists the links for the specified Jira integration.

Allowed For

• Admins

Pagination

Use cursor-based pagination with page[after] or page[before] parameters. Page size defaults to 100 and can be customized with page[size].

Parameters

Name	Type	In	Required	Description
issue_id	string	Query	false	Filter links by Jira issue ID
page[after]	string	Query	false	Cursor for forward pagination
page[before]	string	Query	false	Cursor for backward pagination
page[size]	integer	Query	false	Number of results per page (max 100)
ticket_id	string	Query	false	Filter links by Zendesk ticket ID
external_id	string	Path	true	The external ID of the Jira integration. To get this value, go to the Zendesk Admin Center, then select Apps and integrations > Integrations > Jira > Edit.

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/integrations/jira/{external_id}/links \
  -u {email_address}/token:{api_token}

# filter links by ticket
curl "https://{subdomain}.zendesk.com/api/v2/integrations/jira/{external_id}/links?ticket_id=5001" \
  -u {email_address}/token:{api_token}

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://support.zendesk.com/api/v2/integrations/jira/abc123/links?issue_id=10001&page[after]=&page[before]=&page[size]=&ticket_id=5001"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/integrations/jira/abc123/links")
		.newBuilder()
		.addQueryParameter("issue_id", "10001")
		.addQueryParameter("page[after]", "")
		.addQueryParameter("page[before]", "")
		.addQueryParameter("page[size]", "")
		.addQueryParameter("ticket_id", "5001");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://support.zendesk.com/api/v2/integrations/jira/abc123/links',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
  params: {
    'issue_id': '10001',
    'page[after]': '',
    'page[before]': '',
    'page[size]': '',
    'ticket_id': '5001',
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests
from requests.auth import HTTPBasicAuth

url = "https://support.zendesk.com/api/v2/integrations/jira/abc123/links?issue_id=10001&page[after]=&page[before]=&page[size]=&ticket_id=5001"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"GET",
	url,
	auth=auth,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://support.zendesk.com/api/v2/integrations/jira/abc123/links")
uri.query = URI.encode_www_form("issue_id": "10001", "page[after]": "", "page[before]": "", "page[size]": "", "ticket_id": "5001")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// Status 200 OK

{
  "count": 2,
  "links": [
    {
      "issue_id": "10001",
      "issue_key": "PROJ-123",
      "ticket_id": "5001"
    },
    {
      "issue_id": "10002",
      "issue_key": "PROJ-124",
      "ticket_id": "5002"
    }
  ],
  "meta": {
    "after": "eyJpZCI6MTAwMX0",
    "before": "",
    "has_more": true
  }
}

400 Bad Request

// Status 400 Bad Request

{
  "errors": [
    {
      "code": "BadRequest",
      "title": "Cannot use both page[after] and page[before] parameters"
    }
  ]
}

403 Forbidden

// Status 403 Forbidden

{
  "errors": [
    {
      "code": "Forbidden",
      "title": "Link automation is not allowed for this integration"
    }
  ]
}

Create Link

• POST /api/v2/integrations/jira/{external_id}/links

Creates a link between a Zendesk ticket and a Jira issue.

Allowed For

• Admins

Parameters

Name	Type	In	Required	Description
external_id	string	Path	true	The external ID of the Jira integration. To get this value, go to the Zendesk Admin Center, then select Apps and integrations > Integrations > Jira > Edit.

Example body

{
  "link": {
    "issue_id": "10001",
    "issue_key": "PROJ-123",
    "ticket_id": "5001"
  }
}

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/integrations/jira/{external_id}/links \
  -d '{"link": {"ticket_id": "5001", "issue_id": "10001", "issue_key": "PROJ-123"}}' \
  -H "Content-Type: application/json" \
  -u {email_address}/token:{api_token} -X POST

Go

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://support.zendesk.com/api/v2/integrations/jira/abc123/links"
	method := "POST"
	payload := strings.NewReader(`{
  "link": {
    "issue_id": "10001",
    "issue_key": "PROJ-123",
    "ticket_id": "5001"
  }
}`)
	req, err := http.NewRequest(method, url, payload)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/integrations/jira/abc123/links")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"link\": {
    \"issue_id\": \"10001\",
    \"issue_key\": \"PROJ-123\",
    \"ticket_id\": \"5001\"
  }
}""");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("POST", body)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');
var data = JSON.stringify({
  "link": {
    "issue_id": "10001",
    "issue_key": "PROJ-123",
    "ticket_id": "5001"
  }
});

var config = {
  method: 'POST',
  url: 'https://support.zendesk.com/api/v2/integrations/jira/abc123/links',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
  data : data,
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests
import json
from requests.auth import HTTPBasicAuth

url = "https://support.zendesk.com/api/v2/integrations/jira/abc123/links"

payload = json.loads("""{
  "link": {
    "issue_id": "10001",
    "issue_key": "PROJ-123",
    "ticket_id": "5001"
  }
}""")
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"POST",
	url,
	auth=auth,
	headers=headers,
	json=payload
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://support.zendesk.com/api/v2/integrations/jira/abc123/links")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
request.body = %q({
  "link": {
    "issue_id": "10001",
    "issue_key": "PROJ-123",
    "ticket_id": "5001"
  }
})
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

201 Created

// Status 201 Created

{
  "link": {
    "issue_id": "10001",
    "issue_key": "PROJ-123",
    "ticket_id": "5001"
  }
}

400 Bad Request

// Status 400 Bad Request

{
  "errors": [
    {
      "code": "BadRequest",
      "title": "Invalid request body"
    }
  ]
}

403 Forbidden

// Status 403 Forbidden

{
  "errors": [
    {
      "code": "Forbidden",
      "title": "Link automation is not allowed for this integration"
    }
  ]
}

409 Conflict

// Status 409 Conflict

{
  "errors": [
    {
      "code": "LinkAlreadyExists",
      "title": "Issue is already linked to ticket 5001"
    }
  ]
}

Get Link

• GET /api/v2/integrations/jira/{external_id}/links/ticket/{ticket_id}/issue/{issue_id}

Retrieves a specific link between a Zendesk ticket and a Jira issue.

Allowed For

• Admins

Parameters

Name	Type	In	Required	Description
external_id	string	Path	true	The external ID of the Jira integration. To get this value, go to the Zendesk Admin Center, then select Apps and integrations > Integrations > Jira > Edit.
issue_id	string	Path	true	The Jira issue ID
ticket_id	string	Path	true	The Zendesk ticket ID

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/integrations/jira/{external_id}/links/ticket/{ticket_id}/issue/{issue_id} \
  -u {email_address}/token:{api_token}

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://support.zendesk.com/api/v2/integrations/jira/abc123/links/ticket/5001/issue/10001"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/integrations/jira/abc123/links/ticket/5001/issue/10001")
		.newBuilder();
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://support.zendesk.com/api/v2/integrations/jira/abc123/links/ticket/5001/issue/10001',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests
from requests.auth import HTTPBasicAuth

url = "https://support.zendesk.com/api/v2/integrations/jira/abc123/links/ticket/5001/issue/10001"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"GET",
	url,
	auth=auth,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://support.zendesk.com/api/v2/integrations/jira/abc123/links/ticket/5001/issue/10001")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// Status 200 OK

{
  "link": {
    "issue_id": "10001",
    "issue_key": "PROJ-123",
    "ticket_id": "5001"
  }
}

403 Forbidden

// Status 403 Forbidden

{
  "errors": [
    {
      "code": "Forbidden",
      "title": "Link automation is not allowed for this integration"
    }
  ]
}

404 Not Found

// Status 404 Not Found

{
  "errors": [
    {
      "code": "NotFound",
      "title": "Link not found"
    }
  ]
}

Delete Link

• DELETE /api/v2/integrations/jira/{external_id}/links/ticket/{ticket_id}/issue/{issue_id}

Removes the link between a Zendesk ticket and a Jira issue.

Allowed For

• Admins

Parameters

Name	Type	In	Required	Description
external_id	string	Path	true	The external ID of the Jira integration. To get this value, go to the Zendesk Admin Center, then select Apps and integrations > Integrations > Jira > Edit.
issue_id	string	Path	true	The Jira issue ID
ticket_id	string	Path	true	The Zendesk ticket ID

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/integrations/jira/{external_id}/links/ticket/{ticket_id}/issue/{issue_id} \
  -u {email_address}/token:{api_token} -X DELETE

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://support.zendesk.com/api/v2/integrations/jira/abc123/links/ticket/5001/issue/10001"
	method := "DELETE"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/integrations/jira/abc123/links/ticket/5001/issue/10001")
		.newBuilder();
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("DELETE", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'DELETE',
  url: 'https://support.zendesk.com/api/v2/integrations/jira/abc123/links/ticket/5001/issue/10001',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests
from requests.auth import HTTPBasicAuth

url = "https://support.zendesk.com/api/v2/integrations/jira/abc123/links/ticket/5001/issue/10001"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"DELETE",
	url,
	auth=auth,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://support.zendesk.com/api/v2/integrations/jira/abc123/links/ticket/5001/issue/10001")
request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |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": "BadRequest",
      "title": "Invalid request body"
    }
  ]
}

403 Forbidden

// Status 403 Forbidden

{
  "errors": [
    {
      "code": "Forbidden",
      "title": "Link automation is not allowed for this integration"
    }
  ]
}