Engineering

How to GET and create issues with the Jira API (with code snippets!)

Max Gong, Aaron Lu

July 12, 2022

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!

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.

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.

{{SUB-DOMAIN}} is your end-user subdomain for their JIRA account, you can generally find this post login, where the url will look like {{SUB-DOMAIN}}.jira.com.

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.

  • projectType=software: 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. 
  • updatedDate>=2022-05-26: 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.
  • Pagination uses startAt=0, which indicates the 0th issue, and maxResults=50, which indicates how many results to return (At Merge, we use pagination to batch faster API calls to avoid overload as well.)
  • expand=renderedFields: 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. 

  1. Summary - The summary is actually the name of the Ticket
  2. Status.name - This field is the status of the Jira issue (complete, backlog etc.)
  3. Issuetype - Issuetype denotes the type of issue in Jira, whether that be a bug, story, epic, task, or subtask
  4. Duedate - The Due date for the ticket
  5. renderedFields.description - This field would be the HTML version of the description of the Jira Ticket

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 dict, we can use json.loads

That’s it! Jira is noticeably easier to integrate with than a few of our other systems as it is REST-based.

If you’re interested in not only integrating with Jira but also other ticketing and task management tools to provide integrations for your customers, Merge allows you to integrate with one Unified API to integrate with any ticketing or task management systems your customers may have.

Explore all the ticketing integrations Merge offers here, or explore our technical Get Started to see what it means to build with Merge!

And if you have any questions - feel free to reach out on Intercom!

Email Updates

Subscribe to the Merge Blog

Get stories from Merge straight to your inbox

Subscribe to Blog