This tutorial is part of a series on building product integrations.
You can think of ClickUp as a digital command center. It's a unified hub where teams can easily track and manage tasks, projects, and workflows. ClickUp’s API allows you to pull tasks and analyze task details for a range of use cases. In this article, we'll walk through how to use Python to connect to the ClickUp API, including:
- How to get your ClickUp API authentication up and running
- How to pull data from ClickUp in a normalized format, including how to make get requests for retrieving tasks
- How a single API endpoint can be your gateway to hundreds of different third-party ticketing systems
{{blog-cta-100+}}
Initial setup
To access tasks from the ClickUp API, you need to make a GET request. The endpoint for accessing tasks is `https://api.clickup.com/api/v2/list/{list_id}/task`, where {list_id} is the id of the list from which you want to pull tasks.Â
Here is a sample Python code snippet for making the GET request:
import requests
url = 'https://api.clickup.com/api/v2/list/{list_id}/task'
headers = {
'Authorization': 'ACCESS_TOKEN',
'Content-Type': 'application/json'
}
response = requests.get(url, headers=headers)
tasks = response.json()
Replace 'ACCESS_TOKEN' with your actual access token and {list_id} with the id of the list from which you want to retrieve tasks. The response from the API will be in JSON format, which you can then parse to access the tasks.
Note: The ClickUp API uses rate limiting to protect the service from being overloaded with requests. The rate limits are 100 requests per second per workspace, and 1000 requests per 15 minutes per IP address. If you exceed these limits, the API will respond with a 429 Too Many Requests status code. Make sure to implement proper error handling in your code to manage these situations.
Firstly, we require the <code class='blog_inline-code'>requests</code> and <code class='blog_inline-code'>json</code> libraries. If they are not already installed, you can add them using pip:
pip install requests
pip install json
Accessing tasks from the ClickUp API
Next, let’s actually get tickets from the ClickUp API. We’ll need to first obtain the access token:
import requests
import json
# Client ID and secret provided by ClickUp
client_id = 'your_client_id'
client_secret = 'your_client_secret'
# URL to get the access token
token_url = 'https://api.clickup.com/api/v2/oauth/token'
# Request body parameters
params = {
"client_id": client_id,
"client_secret": client_secret,
"grant_type": "authorization_code",
"redirect_uri": "your_redirect_url",
"code": "authorization_code_from_redirect_uri"
}
# Request the access token
response = requests.post(token_url, data=params)
# Parse the JSON response
json_response = json.loads(response.text)
# Extract the access token
access_token = json_response['access_token']
The access token is then used in the header of every request to the API in the format
Authorization: {ACCESS-TOKEN}:
headers = {
"Authorization": access_token
}
Next, we get the teams:
# URL to get the teams
teams_url = 'https://api.clickup.com/api/v2/team'
# Request the teams
response = requests.get(teams_url, headers=headers)
# Parse the JSON response
json_response = json.loads(response.text)
# Extract the teams
teams = json_response['teams']
Finally, for each team, we retrieve its tasks. The code below will give you access to all tasks for all teams. Remember to replace <code class='blog_inline_code'>your_client_id</code>, <code class='blog_inline_code'>your_client_secret</code>, <code class='blog_inline_code'>your_redirect_url</code>, and <code class='blog_inline_code'>authorization_code_from_redirect_uri</code> with your actual ClickUp credentials.
# Loop over the teams
for team in teams:
# URL to get the tasks
tasks_url = f'https://api.clickup.com/api/v2/team/{team["id"]}/task'
# Request the tasks
response = requests.get(tasks_url, headers=headers, params={
"order_by": "updated",
"subtasks": True,
"include_closed": True
})
# Parse the JSON response
json_response = json.loads(response.text)
# Extract the tasks
tasks = json_response['tasks']
# Process the tasks
for task in tasks:
# Add your code here
This is an example of an individual item returned by this API Endpoint:
{
"id": "task1",
"url": "https://taskurl.com",
"list": {
"id": "list1",
"name": "Task List",
"access": true
},
"name": "New Task",
"tags": [
{
"name": "urgent",
"tag_bg": "#FF0000",
"tag_fg": "#FFFFFF",
"creator": 12345
}
],
"space": {
"id": "space1"
},
"folder": {
"id": "folder1",
"name": "Task Folder",
"access": true,
"hidden": false
},
"parent": "parent1",
"status": {
"type": "InProgress",
"color": "#FFFF00",
"status": "active",
"orderindex": 1
},
"creator": {
"id": 12345,
"color": "#0000FF",
"email": "creator@email.com",
"username": "creatorusername",
"profilePicture": "https://profilepicture.com"
},
"project": {
"id": "project1",
"name": "Project Name",
"access": true,
"hidden": false
},
"team_id": "team1",
"archived": false,
"due_date": "2022-12-30",
"priority": {
"id": "priority1",
"color": "#FF0000",
"priority": "high",
"orderindex": "1"
},
"watchers": [],
"assignees": [
{
"id": 12345,
"color": "#0000FF",
"email": "assignee@email.com",
"initials": "AS",
"username": "assigneeusername"
}
],
"checklists": [],
"orderindex": "1",
"time_spent": 120,
"date_closed": "2022-12-31",
"description": "Task description",
"date_created": "2022-01-01",
"date_updated": "2022-01-02",
"dependencies": [],
"linked_tasks": [],
"text_content": "Task text content",
"custom_fields": [
{
"id": "custom1",
"name": "Custom Field",
"type": "text",
"required": false,
"type_config": {
"default": 1,
"options": [
{
"id": "option1",
"name": "Option 1",
"orderindex": 1
}
]
},
"date_created": "2022-01-01",
"hide_from_guests": false
}
],
"permission_level": "admin"
}
Use a unified ticketing API to integrate at scale
In this article, we walked through the process of getting Tasks from ClickUp using Python. But what if your clients use a variety of ticketing systems?
You can integrate your product with all of your clients' ticketing solutions to sync tasks—among other types of data—by leveraging Merge, the leading Unified API solution.
Simply build to Merge's Ticketing and Project Management Unified API to offer 30+ ticketing integrations. You'll also be able to access Merge's robust Integrations Management features to identify and troubleshoot issues quickly and successfully.
You can learn more about Merge by scheduling a demo with one of our integration experts.
.svg){kind=small}
