Jira is one of the most popular Ticketing and Task Management API platforms developers integrate with. If you deal at all in the realm of project management or ticketing integrations, then you're probably creating an issue with the Jira API.

In this article, we’ll cover how to handle authentication, building a GET request, and building a POST request - in short, everything you’ll need to successfully call the Jira API!

{{blog-cta-100+}}

Understanding Jira’s API

As far as enterprise APIs go, Jira’s is relatively simple. It's a REST API that returns responses in JSON. The biggest hurdles people face when integrating with Jira, however, is handling authentication. 

Authenticating with the JIRA API

Jira uses basic auth, which is a method for HTTP user agents to provide credentials to validate requests to the API.

Jira’s basic auth requires three values:

1. Sub-domain of the end-user’s account.
2. Email Address of the end-user’s account. However, to ensure the user has permissions necessary to access the required API endpoint, it is preferred that the end-user’s role be an administrator. To assign roles to individual users, view the Jira help docs here.
3. API Token - the end-user can create and access the standard API Token from their profile here.

Related: The steps for fetching comments from the Jira API (via Python)

Building the GET request for Jira issues

To search for issues with Jira’s API, you can hit this endpoint:

For Jira's documentation, look here.

There are a few parts of this request to note, you’ll need to replace certain fields to fit your use cases.

<code class="blog_inline-code">SUB-DOMAIN</code> is your end-user subdomain for their JIRA account, you can generally find this post login, where the url will look like <code class="blog_inline-code">SUB-DOMAIN.jira.com</code>.

JQL (Jira Query Language) is a query parameter that’s unique to Jira and allows for advanced search for anything that the standard endpoints do not offer (learn more here). For issues, there are a few specific query parameters we’ll want to add.

<code class="blog_inline-code">projectType=software</code> is a must-have query parameter - Jira has multiple products, and to filter issues from only Jira Software and not Service Management, we need to include this. 

<code class="blog_inline-code">updatedDate>=2022-05-26</code> pulls the issues modified on or after 2022-05-26. In general, we want to keep the time range small to avoid overloading the response.

<code class="blog_inline-code">Pagination uses startAt=0</code> which indicates the 0th issue, and <code class="blog_inline-code">maxResults=50</code>, which indicates how many results to return (At Merge, we use pagination to batch faster API calls to avoid overload as well.)

<code class="blog_inline-code">expand=renderedFields</code> is needed to pull the issue details in HTML form. Otherwise, you’ll have to deal with Atlassian Document Format, which is... a little difficult to deal with. HTML is easy to normalize and display for your integration. (link here to learn more about Atlassian document format)

Example of GET response: 

We’ve shortened the API response, but there are several things that should be noted about the ticket pulled. There are several notable common fields that you’ll likely need if you’re looking to GET tickets. 

<code class="blog_inline-code">summary</code> - The summary is actually the name of the Ticket

<code class="blog_inline-code">status.name</code> - This field is the status of the Jira issue (complete, backlog etc.)

<code class="blog_inline-code">issuetype</code> - Denotes the type of issue in Jira, whether that be a bug, story, epic, task, or subtask

<code class="blog_inline-code">duedate</code> - The due date for the ticket

<code class="blog_inline-code">renderedFields.description</code> - This field would be the HTML version of the description of the Jira Ticket

Related: A guide to getting attachments from the Jira API

Python Example for calling the Jira API

There are a few ways to call the Jira API using python. JIRA has a python package that you’re able to use to call the API - https://pypi.org/project/jira/.

As this package is well documented, we’ll show an alternative way that we use that’s more similar to our other tutorials using the requests and JSON packages.

You should get a JSON response here. To load it as a <code class="blog_inline-code">dict</code>, we can use <code class="blog_inline-code">json.loads</code>.

That’s it! If you’re interested in not only integrating with Jira but also Asana, Linear, and Azure DevOps to provide integrations for your customers, Merge allows you to integrate with one Ticketing Unified API to integrate with any ticketing or task management systems your customers may have. Explore our technical Get Started to see what it means to build with Merge. You can also schedule a demo with one of our integration experts to learn more.