Utiliser l'API ClickUp : endpoints, applications & plus

Introduction à l'API de ClickUp

ClickUp est un outil de gestion de projet qui dispose de fonctionnalités complètes : workflow personnalisés, tâches, documents, objectifs, rappels, et plus encore. Utilisez cet outil pour centraliser les activités de votre équipe. Pour tirer parti de cette application, vous pouvez intégrer d'autres outils.

C'est là que l'API de ClickUp intervient. Dans cet article, nous allons explorer les capacités de l'API ClickUp et comment l'utiliser efficacement.

Pourquoi utiliser l'API de ClickUp ?

Voici les principales raisons d'utiliser l'API de ClickUp :

Aperçu des capacités de l'API de ClickUp

L'API vous donne accès à tout le potentiel de ClickUp. Vous pouvez :

• Gérer les projets, listes, tâches, etc.
• Automatiser les workflows et logiques business
• Créer des rapports et analyses personnalisés
• Intégrer d'autres outils que votre équipe utilise
• Utiliser l'outil selon vos workflows et besoins spécifiques

Automatisation de processus

Vous pouvez l'utiliser pour automatiser votre activité. Par exemple, vous pouvez créer une intégration Zapier pour ajouter automatiquement des tâches à partir des formulaires. Utilisez webhooks pour déclencher des actions dans ClickUp lorsque le statut d'une tâche change.

Synchronisation de données

Synchronisez les données entre ClickUp et les outils que vous utilisez. Créez des tâches à partir de Slack, ou préremplissez les champs personnalisés depuis votre CRM. Gardez vos données à jours.

Amélioration des fonctionnalités

Ajoutez des fonctionnalités qui n'existent pas encore à ClickUp. Créez des extensions web, des rapports personnalisés, et de nouvelles apps grâce aux capacités de l'API.

Centralisation des informations

Importez des tâches à partir de Jira, Trello, Asana, etc. avec l'API et centralisez vos données dans ClickUp.

Intégrations personnalisées

Créez de nouvelles intégrations. Par exemple, connectez ClickUp à une app de discussion pour que les membres puissent créer des tâches durant leur conversation. Vous pouvez aussi afficher le statuts des tâches sur un écran numérique.

L'API offre beaucoup de possibilités de personnalisation, élargissant le potentiel de ClickUp.

Débuter avec l'API de ClickUp

L'API de ClickUp, qu'est-ce que c'est ?

Le terme "API" semble intimidant si vous n'avez pas de background code. Ne vous en faites pas, les API sont simples à comprendre. Il permet aux applications de se communiquer et de se partager des informations. Par exemple, vous pouvez recevoir des notifications ClickUp dans Slack ou voir les dates d'échéances de vos tâches dans votre app de calendrier.

Connectez ClickUp à d'autres applications avec l'API. Il permet aux développeurs (ou aux non-développeurs avec des outils no-code) d'accéder aux données de ClickUp et créer des intégrations, des automatisations, et des fonctionnalités personnalisées.

Utilisation de l'API ClickUp

Voici les étapes à suivre pour commencer à l'utiliser :

Étape 1 – Obtenir la documentation de l'API

Tout d'abord, vous aurez besoin de la documentation API :

1. Naviguez dans la section "API ClickUp" dans vos paramètres d'environnement de travail
2. Cliquez sur "Créer une application"
3. Saisissez le nom de l'application et cliquez sur "Créer une application"
4. Sauvegardez l'identifiant du client et le secret client

Pour les apps personnels, vous pouvez aussi utiliser les jetons API de votre profil ClickUp

Étape 2 – Consulter la documentation

Ensuite, référez-vous à la documentation sur les API de ClickUp pour avoir un aperçu des endpoints disponibles. Vous allez pouvoir explorer ses capacités.

Étape 3 – Effectuer des appels API de test

Effectuez quelques appels de test en utilisant un client comme Postman ou Insomnia. Référez-vous aux documents pour récupérer une tâche, créer un commentaire, ou mettre à jour un champ personnalisé pour vous familiariser avec les formats de requêtes et les structures de réponses.

Voici quelques appels de test :

Créer une tâche - POST /task

Mettre à jour le nom de la tâche - PUT /task/{id}

Obtenir les détails de l'utilisateur - GET /user

Comprendre la structure de l'API de ClickUp

Comment fonctionne l'API REST de ClickUp

L'API ClickUp est un API REST qui utilise des URLs prévisibles et des codes de réponse HTTP. Elle renvoie des données au format JSON.

Comment ça marche ?

Authentification

Il existe deux authentifications avec l'API ClickUp 2.0 :

1. Jeton personnel : vous pouvez générer un jeton personnel sur votre profil ClickUp. Ce jeton devrait être inclus sur l'entête d'autorisation de vos requêtes API.
2. OAuth2 Flow : pour des cas d'usages avancés comme la création d'application, il est fortement recommandé de créer une app OAuth et l'authentifier avec le flux OAuth2. Cet outil vous fournira un jeton d'accès, inclus sur l'entête d'autorisation de vos requêtes API.

Important : si vous créez une app pour de multiples utilisateurs, utilisez l'authentification OAuth2.

Pour appeler les endpoints API ClickUp, vous aurez besoin d'un jeton d'accès. Incluez ce jeton à l'entête d'autorisation de vos requêtes API.

Ressources

L'API présente des "ressources" que vous pouvez créer, lire, mettre à jour, et supprimer (CRUD).

Exemple de ressources :

• Tâches
• Listes
• Dossiers
• Équipes
• Objectifs
• Commentaires

Vous pouvez effectuer des opérations CRUD sur ces ressources avec les méthodes HTTP comme GET, POST, PUT, et DELETE.

Endpoints

Les endpoints de l'API suivent des modèles de type :

GET /task/{task_id} - Get a taskPUT /task/{task_id} - Update a taskPOST /list/{list_id}/task - Create a task in a list

Grâce à la structure de l'URL, il est facile de comprendre l'objetif de l'endpoint.

Webhooks

Vous pouvez également utiliser les webhooks de ClickUp pour recevoir des notifications en temps réel lorsque certains évènements se produisent (ex : le statut d'une tâche change). Vous allez pouvoir créer des intégrations réactives.

Jetons d'API ClickUp

L'API ClickUp propose 3 mécanismes d'authentifications :

• Les jetons API ClickUp fournissent un accès personnalisé aux ressources ClickUp de cet utilisateur.
• Chaque utilisateur peut générer un jeton à partir des paramètres de leur profil ClickUp.
• Après, les requêtes API sont authentifiées en passant le jeton à l'entête.

Authorization: pk_123456789_ABCD1234ABCD1234ABCD1234

Comment utiliser OAuth2 Flow de ClickUp

Pour les applications à multiples utilisateurs, il est recommandé d'utiliser l'authentification OAuth 2.0. Ce Flow comprend :

• Création d'une App OAuth - Naviguez dans les paramètres d'équipe > "API ClickUp" > Créez une nouvelle application avec le nom et l'URL de redirection. Sauvegardez le client_id, et le client_secret
• Code d'autorisation - Redirigez l'utilisateur au https://app.clickup.com/api?client_id={client_id}&redirect_uri={redirect_uri}. L'utilisateur accepte/rejette et sera redirigé à redirect_uri avec le code.
• Jeton d'accès - Utilisez POST /api/v2/oauth/token avec le client_id, client_secret, et le code pour obtenir le jeton d'accès. Utilisez-le dans l'entête d'autorisation.
• Jetons d'équipes - L'utilisateur sélectionne les équipes à autoriser (Environnement de travail). Vérifiez les autorisations avec GET /api/v2/team. Redirigez une nouvelle fois l'utilisateur pour autoriser d'autres équipes.

Sélection des environnements de travail

Lors du processus d'autorisation OAuth, les utilisateurs peuvent choisir les environnements de travail qui peuvent accéder à votre application. Ils pourront en sélectionner un ou plusieurs.

Vous pouvez vérifier l'environnement de travail qu'un utilisateur a autorisé pour votre application en utilisant l'endpoint Get Authorized Teams.

Clé API ClickUp personnel

Lorsque vous utilisez une clé API ClickUp personnel, évitez de l'utiliser dans des applications de production d'autres utilisateurs. Si votre clé est compromise, vous risquerez de perdre l'accès. OAuth 2.0 est recommandé pour les applications multi-utilisateurs.

Principales capacités de l'API

Maintenant que vous comprenez les bases, nous allons explorer les capacités de base de l'API ClickUp :

Gestion des tâches

Les tâches ClickUp sont organisées dans les listes. L'API fournit un accès CRUD complet (Create, Read, Update, Delete) aux tâches et listes, incluant :

• Création de tâches
• Mise à jour des détails de tâche comme le nom, la description, le statut, la priorité, etc.
• Ajout des tâches aux listes
• Changement de l'ordre et de l'indentation d'une tâche
• Marquer les tâches achevées
• Suppression des tâches
• Et plus encore !

Gestion des listes

Les listes ClickUp représentent les listes de tâches et les tableaux Kanban. L'API propose des capacités comme :

• Création, mise à jour, et suppression de listes
• Obtention de toutes les tâches dans une liste
• Ajout/retrait de tâches dans une liste

Vous pouvez intégrer la structure des listes et l'organisation de tâche à partir d'autres outils dans ClickUp.

Utilisateurs et équipes

L'API vous permet de gérer les utilisateurs et les permissions ClickUp avec la programmation :

• Inviter, mettre à jour, ou retirer les utilisateurs
• Créer et modifier des rôles personnalisés
• Mettre à jour les permissions et accès utilisateurs

Par exemple, vous pouvez ajouter ou retirer automatiquement les utilisateurs selon les données de votre système RH.

Commentaires

Les commentaires API vous permettent d'ajouter, de mettre à jour, et de récupérer les commentaires dans les tâches, listes, et discussions dans ClickUp. Synchronisez les commentaires avec les outils comme Slack, GitHub, Jira, et plus encore.

Champs personnalisés

Vous pouvez créer des champs personnalisés en complément d'informations pour vos tâches ClickUp. L'API donne accès à ces champs, alors vous pouvez :

• Obtenir les valeurs des champs personnalisés
• Les mettre à jour
• Créer et supprimer des champs personnalisés (pour les développeurs qui utilisent ClickUp)

Relations et dépendances

L'API fourni un accès aux relations entre les tâches comme :

• Les sous-tâches - Gérez les relations de tâches parent enfant.
• Les dépendances - Liez les tâches avec leurs dépendances.

Suivi du temps

ClickUp propose un suivi du temps complet. L'API permet de :

• Enregistrer le temps passé sur les tâches
• Générer des rapports de temps suivi
• Modifier le temps suivi
• Gérer les minuteurs

Vous allez pouvoir créer des suivis du temps et rapports personnalisés.

Pièces jointes

Vous pouvez également attacher des fichiers aux tâches grâce à l'API. Attachez des fichiers à partir de vos stockages cloud comme Google Drive ou DropBox.

Recherches et filtrages

Les capacités de recherche et de filtrage vous permettent de trouver facilement vos tâches. Vous pourrez synchroniser ces filtres dans d'autres applications.

Et plus encore !

Les capacités de l'API sont larges, incluant :

• Webhooks pour les intégrations évènements-actions
• Gestion des dossiers, espaces, et hiérarchie
• Objetifs et Résultats Clés (OKR en anglais)
• Checklists et items de Checklist
• Dates d'échéances, rappels, et planification
• Notifications d'email
• Gestion des étiquettes
• Dépendances entre les tâches
• Contacts et données de compte
• Équipes, groupes, et permissions
• Et bien plus encore !

Comme vous pouvez le constater, l'API ClickUp offre des capacités extensives pour manipuler et extraire les données sur ClickUp.

Stratégies pour une intégration réussie de l'API de ClickUp

Planifier l'intégration

Une fois les bases établies, réfléchissez maintenant à l'intégration que vous souhaitez créer. Inspirez-vous des exemples dans ce post. Explorez les capacités de l'API de ClickUp !

Commencer petit

Vous souhaitez certainement réaliser de grandes choses mais n'oubliez pas, Rome n'a pas été construite en un jour. Alors commencez petit ! Débutez avec une intégration simple, ne serait-ce que la création d'une tâche à partir d'une requête GET. Visez d'abord le "proof of concept", puis itérez pour plus de personnalisation.

Utilisez curl ou un outil comme Postman pour tester les requêtes API. Par exemple :

curl -H "Authorization: pk_123456789" https://api.clickup.com/api/v2/user

Vous allez recevoir des infos sur différents endpoints comme l'utilisateur, l'équipe, le dossier, la tâche, etc.

Utiliser Webhooks

Utilisez les webhooks de ClickUp pour un suivi en temps réel des évènements, surtout pour les intégrations dynamiques. Vous allez gagner du temps.

Créer des applications avec l'API de ClickUp

Créer une application ClickUp

Si vous pensez à créer une app ClickUp, il est recommandé d'utiliser l'authentification OAuth 2.0.

Aperçu de l'authentification OAuth 2.0 :

• Elle utilise l'Authorization Code Grant Flow.
• Tout d'abord, enregistrez votre app dans ClickUp pour obtenir l'ID et le secret client.
• Lorsqu'un utilisateur se connecte, vous allez le rediriger vers l'URL OAuth de ClickUp avec votre ID client.
• Il devra approuver l'accès à son compte ClickUp.
• ClickUp le redirige avec un code d'autorisation dans l'URL de rappel.
• Vous échangez ce code d'autorisation pour un jeton d'accès via API.
• Vous allez utiliser le jeton d'accès pour faire des appels API pour son compte.

L'avantage de l'OAuth 2.0 est que chaque utilisateur obtient leur jeton, alors vous n'accèderez pas aux données des autres. De plus, il peut retirer l'accès à tout moment.

Une fois prêt, vous pouvez commencer à créer vos scripts et apps pour utiliser l'API :

• Automatiser les processus répétitifs
• Développer les intégrations
• Créer des rapports
• Synchroniser les données
• Et plus encore !

Les possibilités sont infinies une fois que vous commencez à exploiter les capacités de ClickUp.

Documentation sur l'API ClickUp | Article, support, centre d'aide etc.

Consulter les exemples d'apps

Visitez la galerie d'App de ClickUp pour voir des exemples d'applications à implémenter. Ils ont même des échantillons de code open-source sur GitHub en langage Node, Python, et C# que vous pouvez consulter. Idéal pour bien débuter.

Essayer l'API dans votre navigateur Web

La référence de l'API ClickUp vous permet de tester et d'expérimenter avec l'API unifié directement dans votre navigateur web – tout au même endroit. Chaque endpoint de page dispose d'une option "Try It", facilitant la modification et les merge requests sans naviguer entre outils et plateformes.

Vous pouvez utiliser votre clé API pour visualiser vos données et vos espaces de travail, ou explorer des infos génériques avec le mock server – simplifiant la communication avec un gain de temps.

Étape 1 – Saisir la clé API

1. Allez à n'importe quel endpoint de page.
2. Cliquez sur "Try It" en haut à droite.
3. Développer la section "Security".
4. Saisissez (ou collez) votre clé API.

Conseil : avec le Mock server, vous pouvez utiliser n'importe quelle valeur en tant que clé d'autorisation.

Étape 2 – Entrer les paramètres et le Request Body

1. Développer la section "Body" pour ajouter des informations à votre requête.
2. Développer les sections "Parameters" pour ajouter les détails de paramètres à votre requête.

Conseil : avec le Mock server, vous pouvez utiliser n'importe quelle valeur dans les champs requis et optionnels.

Étape 3 – Sélectionner le serveur cible

Sélectionnez entre ces serveurs cibles :

1. https://api.clickup.com/v2 – ClickUp
2. https://{mock-server-id}.remockly.com – Mock Server

Cette fonctionnalité vous permet de tester et d'expérimenter l'API ClickUp sans mettre en place un environnement de développement ou écrire une ligne de code. Vous allez gagner du temps, tout en permettant l'édition et le merging collaboratifs.

Limites d'utilisation

Pour améliorer la performance, ClickUp applique des limites d'utilisation de requête par jeton. Ces limites s'appliquent aux jetons personnels et OAuth.

Elles varient selon votre forfait :

• Forfaits Free Forever, Unlimited et Business : 100 requêtes par minute par jeton.
• Forfait Business Plus : 1 000 requêtes par minute par jeton.
• Forfait Enterprise : 10 000 requêtes par minute par jeton.

L'API de ClickUp en tant que solution robuste

Maintenant que vous avez une idée de ce qui est possible avec l'API, voici quelques exemples concrets d'utilisation :

Synchroniser les tâches assignées à Google Calendar

Utilisez un script simple qui récupère toutes les tâches assignées à un utilisateur et crée les évènements correspondants dans Google Calendar. Lorsque vous mettez à jour les détails de tâche dans ClickUp, le calendrier sera mis à jour automatiquement.

Créer des problèmes GitHub à partir des tâches ClickUp

Lorsqu'une tâche passe à "En cours" dans ClickUp, utilisez l'API pour créer automatiquement un nouveau problème dans GitHub pour les développeurs. Une fois que le statut passe à "Achevé", le problème sera fermé.

Générer des factures à partir des temps enregistrés

Récupérez le temps enregistré sur les tâches grâce à l'API, et générez directement des factures à partir du temps suivi facturable. Vous pouvez soit envoyer les factures par email aux clients, soit synchroniser avec un logiciel de comptabilité.

Chatbot de ClickUp

En utilisant des outils comme Dialogflow, créez des Chatbots qui génèrent des tâches avec des requêtes de type : "planifie une réunion pour vendredi à 14:00".

Assignation automatique des leads

Créez des règles/conditions qui suivent les nouvelles tâches dans certaines listes pour qu'elles soient assignées automatiquement aux commerciaux – facilitant la distribution des leads.

Processus de réinitialisation de mot-de-passe

Lorsqu'un utilisateur oublie son mot-de-passe ClickUp, vous pouvez collecter son adresse mail à partir d'un formulaire. Utilisez l'API pour lui envoyer un lien de réinitialisation de mot-de-passe.

Rapports personnalisés

Utilisez les données de ClickUp dans un outil de business intelligence pour générer des rapports personnalisés. Créez des graphiques, des vues de répartition de ressources, et plus encore.

Avis sur les applications tierces

Affichez les avis sur les app du Marketplace de ClickUp dans votre site web avec l'API. Assurez-vous que les utilisateurs soient à jour sur les nouvelles apps disponibles.

Soumettre les relevés de temps aux applications de paie

Les développeurs peuvent créer une intégration qui envoie le temps suivi dans ClickUp vers des applications de paie comme Gusto à chaque période de paie.

Les possibilités sont infinies lorsque vous avez accès à une plateforme robuste comme ClickUp grâce à l'accès API.

Conclusion

L'API ClickUp présente des opportunités pour automatiser vos workflows, créer des outils personnalisés, et centraliser vos informations. Que vous souhaitiez simplifier les tâches répétitives ou créer une nouvelle application de productivité, l'API vous offre les capacités dont vous avez besoin.

Alors, préparez-vous à utiliser l'API dans son plein potentiel, et atteignez vos objectifs de productivité en un rien de temps !

‍