API Attio : guide complet pour les développeurs

Ce que permet l’API Attio

Attio fournit une API REST publique qui échange du JSON sur HTTPS. Les endpoints actuels sont exposés sous /v2/ et permettent notamment de :

• lire et modifier les objets du workspace ;

• créer, rechercher et mettre à jour des records ;

• gérer les entrées de listes et les pipelines ;

• manipuler les attributs, notes, tâches et commentaires ;

• créer des webhooks ;

• connecter une application avec OAuth 2.0.

La particularité d’Attio est que l’API ne se limite pas aux personnes, entreprises et deals. Un objet personnalisé créé dans le workspace peut être interrogé et modifié avec les mêmes patterns que les objets standards.

La documentation officielle reste la source de vérité pour les endpoints et les schémas. Attio publie également une spécification OpenAPI pour explorer l’API ou générer une partie des types et clients nécessaires à une intégration.

Access token ou OAuth 2.0 ?

Le premier choix ne concerne pas le langage, mais le mode d’authentification.

Pour un seul workspace, un administrateur peut créer un access token depuis les paramètres développeur. Pour une application multi-workspaces, Attio recommande OAuth 2.0 afin que chaque client autorise son propre espace.

Dans les deux cas, le token est envoyé dans le header Authorization :

Les tokens utilisent des scopes. Une intégration qui ne fait que lire des records ne doit pas disposer d’un droit d’écriture.

Quelques règles simples :

• créez un token par intégration et par environnement ;

• donnez-lui un nom explicite ;

• stockez-le dans un gestionnaire de secrets ;

• ne l’exposez jamais dans un navigateur ou un dépôt Git ;

• révoquez-le dès qu’il n’est plus utile.

Comprendre le modèle de données Attio

La difficulté principale n’est généralement pas l’appel HTTP. Elle consiste à comprendre ce que vous manipulez.

Objects et records

Un object définit un type d’entité : People, Companies, Deals ou un objet personnalisé comme Contracts ou Subscriptions.

Un record est une instance de cet objet. Jeanne Dupont est un record de People ; Acme SAS est un record de Companies.

Lists et entries

Une list représente un processus ou un regroupement : pipeline commercial, portefeuille de renouvellements ou suivi de partenaires.

Lorsqu’un record est ajouté à une liste, Attio crée une entry. Le record porte les données durables de l’entité ; l’entrée porte les données propres au processus.

Par exemple :

• le domaine et le secteur appartiennent au record Company ;

• l’étape, le montant ou la date de closing peuvent appartenir à son entrée dans un pipeline.

Un même record peut donc participer à plusieurs processus sans être dupliqué.

Attributes

Les attributes sont les champs des objets et des listes. Attio prend en charge différents types : texte, nombre, date, statut, sélection, e-mail, téléphone, relation vers un autre record et autres formats structurés.

Le format du payload dépend du type d’attribut. Il faut donc éviter de supposer qu’une valeur complexe peut toujours être envoyée comme une simple chaîne.

Notes et tasks

L’API expose également les notes et les tâches. Une intégration peut créer un compte rendu sur le bon compte, générer une relance ou rattacher une tâche à plusieurs records.

Retrouvez le fonctionnement général du produit dans notre guide des fonctionnalités Attio.

Créer ou mettre à jour un record

Créer une personne

La création utilise POST /v2/objects/{object}/records.

curl --request PUT \
  --url "https://api.attio.com/v2/objects/people/records?matching_attribute=email_addresses" \
  --header "Authorization: Bearer $ATTIO_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "data": {
      "values": {
        "email_addresses": ["jeanne@exemple.fr"],
        "name": [
          {
            "first_name": "Jeanne",
            "last_name": "Dupont",
            "full_name": "Jeanne Dupont"
          }
        ]
      }
    }
  }'

curl --request PUT \
  --url "https://api.attio.com/v2/objects/people/records?matching_attribute=email_addresses" \
  --header "Authorization: Bearer $ATTIO_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "data": {
      "values": {
        "email_addresses": ["jeanne@exemple.fr"],
        "name": [
          {
            "first_name": "Jeanne",
            "last_name": "Dupont",
            "full_name": "Jeanne Dupont"
          }
        ]
      }
    }
  }'

curl --request PUT \
  --url "https://api.attio.com/v2/objects/people/records?matching_attribute=email_addresses" \
  --header "Authorization: Bearer $ATTIO_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "data": {
      "values": {
        "email_addresses": ["jeanne@exemple.fr"],
        "name": [
          {
            "first_name": "Jeanne",
            "last_name": "Dupont",
            "full_name": "Jeanne Dupont"
          }
        ]
      }
    }
  }'

Si un attribut marqué comme unique entre en conflit avec un record existant, la création échoue. Pour une synchronisation, utilisez plutôt un upsert.

Utiliser l’upsert pour éviter les doublons

L’upsert crée le record s’il n’existe pas et le met à jour s’il existe déjà. Il utilise un attribut unique indiqué par le paramètre matching_attribute. Pour People, l’adresse e-mail constitue le choix naturel.

curl --request PUT \
  --url "https://api.attio.com/v2/objects/people/records?matching_attribute=email_addresses" \
  --header "Authorization: Bearer $ATTIO_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "data": {
      "values": {
        "email_addresses": ["jeanne@exemple.fr"],
        "name": [
          {
            "first_name": "Jeanne",
            "last_name": "Dupont",
            "full_name": "Jeanne Dupont"
          }
        ]
      }
    }
  }'

curl --request PUT \
  --url "https://api.attio.com/v2/objects/people/records?matching_attribute=email_addresses" \
  --header "Authorization: Bearer $ATTIO_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "data": {
      "values": {
        "email_addresses": ["jeanne@exemple.fr"],
        "name": [
          {
            "first_name": "Jeanne",
            "last_name": "Dupont",
            "full_name": "Jeanne Dupont"
          }
        ]
      }
    }
  }'

curl --request PUT \
  --url "https://api.attio.com/v2/objects/people/records?matching_attribute=email_addresses" \
  --header "Authorization: Bearer $ATTIO_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "data": {
      "values": {
        "email_addresses": ["jeanne@exemple.fr"],
        "name": [
          {
            "first_name": "Jeanne",
            "last_name": "Dupont",
            "full_name": "Jeanne Dupont"
          }
        ]
      }
    }
  }'

Pour un objet personnalisé, définissez d’abord un attribut unique adapté : identifiant client, référence de contrat ou identifiant provenant du système source.

Mettre à jour avec PATCH

PATCH /v2/objects/{object}/records/{record_id} modifie les valeurs fournies.

Attention aux attributs multiselect : une mise à jour PATCH ajoute les nouvelles valeurs aux valeurs existantes. Utilisez PUT si vous devez remplacer complètement la collection.

Rechercher et paginer les records

Les records se filtrent avec un POST sur l’endpoint /query :

curl --request POST \
  --url "https://api.attio.com/v2/objects/companies/records/query" \
  --header "Authorization: Bearer $ATTIO_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "filter": {
      "name": "Acme"
    },
    "limit": 50,
    "offset": 0
  }'

curl --request POST \
  --url "https://api.attio.com/v2/objects/companies/records/query" \
  --header "Authorization: Bearer $ATTIO_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "filter": {
      "name": "Acme"
    },
    "limit": 50,
    "offset": 0
  }'

curl --request POST \
  --url "https://api.attio.com/v2/objects/companies/records/query" \
  --header "Authorization: Bearer $ATTIO_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "filter": {
      "name": "Acme"
    },
    "limit": 50,
    "offset": 0
  }'

Les syntaxes disponibles dépendent du type d’attribut. Testez les filtres avec la référence officielle plutôt que de recopier une syntaxe conçue pour un autre champ.

Quelques réflexes :

• filtrez côté serveur ;

• ne supposez jamais qu’une réponse contient tous les résultats ;

• respectez le système de pagination de l’endpoint ;

• utilisez les slugs stables ou les UUID plutôt que les libellés visibles ;

• journalisez les identifiants Attio et ceux du système source.

Attio utilise selon les ressources une pagination par limit et offset ou par curseur. Une couche d’accès générique doit donc prendre en charge les deux mécanismes.

Configurer des webhooks fiables

Les webhooks permettent de réagir à une modification sans interroger régulièrement l’API. Ils conviennent par exemple pour :

• lancer un onboarding lorsqu’un deal est gagné ;

• synchroniser une correction effectuée par un commercial ;

• notifier Slack lors d’un changement d’étape ;

• alimenter un data warehouse au fil de l’eau.

Attio signe chaque webhook avec un HMAC SHA-256 du corps brut. La signature est transmise dans Attio-Signature, également dupliquée dans X-Attio-Signature. Vérifiez-la avec le secret du webhook avant de traiter le payload.

Autres comportements à prévoir :

• l’URL cible doit utiliser HTTPS ;

• la livraison est garantie au moins une fois ;

• Idempotency-Key permet de dédupliquer les tentatives ;

• le serveur doit répondre en moins de cinq secondes ;

• toute réponse hors 200–299 déclenche des retries ;

• Attio peut réessayer jusqu’à dix fois sur environ trois jours ;

• la livraison est limitée par défaut à 25 requêtes par seconde et par URL.

Le bon pattern consiste à vérifier la signature, enregistrer l’événement, répondre immédiatement en 202, puis effectuer le traitement dans une queue.

Rate limits et gestion des erreurs

Attio applique actuellement une limite globale de :

• 100 requêtes par seconde en lecture ;

• 25 requêtes par seconde en écriture.

Une réponse 429 Too Many Requests contient un header Retry-After. Attendez cette échéance avant de réessayer.

Les endpoints de listing des records et des entries appliquent aussi une limite fondée sur la complexité des filtres, des tris et du volume de données. Une seule requête trop complexe peut donc être refusée même si votre débit reste faible.

En production :

• mettez les traitements volumineux en file ;

• limitez le nombre de workers concurrents ;

• respectez Retry-After ;

• réessayez seulement les erreurs temporaires ;

• préférez les webhooks au polling ;

• simplifiez les requêtes qui reçoivent une erreur de complexité.

Faut-il vraiment utiliser l’API pour personnaliser Attio ?

Pas toujours. Attio propose plusieurs niveaux d’extension avant de devoir héberger une intégration complète.

Workflow natif

Utilisez un Workflow lorsque le déclencheur et les actions restent dans Attio ou dans une application déjà connectée : attribuer un lead, créer une tâche, mettre à jour un statut ou lancer une séquence.

Send HTTP request

Le bloc Send HTTP request permet d’appeler un service externe en GET, POST, PATCH, PUT, DELETE ou HEAD. Il retourne le statut et le corps de la réponse, qui peut ensuite être analysé avec Parse JSON.

C’est suffisant pour appeler un webhook, envoyer un payload simple ou récupérer une donnée depuis une API. Le timeout actuel du bloc est de deux minutes.

Execute code

Le bloc Execute code exécute une fonction JavaScript dans un Workflow. Elle reçoit les variables configurées et retourne une valeur utilisable dans les étapes suivantes. Son timeout actuel est de 100 secondes.

Pour les utilisateurs venant d’Airtable, son rôle se rapproche de l’action de script d’une automatisation. La logique de décision est également similaire à celle présentée dans notre guide de l’API Airtable : le code embarqué convient aux transformations locales, tandis que l’API directe devient préférable lorsque l’intégration doit être indépendante, volumineuse ou profondément liée à un produit.

Record command et List entry command

Ces triggers ajoutent une commande manuelle sur un record ou une entrée de liste. Un utilisateur peut ainsi déclencher un Workflow depuis Attio : générer un document, lancer un enrichissement ou envoyer une information vers un autre système.

App SDK

L’App SDK va plus loin. Il permet d’ajouter dans Attio :

• des actions et boutons sur les records ;

• des widgets et interfaces personnalisées ;

• des fonctions serveur exécutées dans l’infrastructure Attio ;

• des blocs de Workflow personnalisés ;

• des webhooks entrants ;

• des connexions sécurisées vers des services externes.

L’API REST reste préférable lorsqu’un système externe doit synchroniser des données avec Attio. L’App SDK devient pertinent lorsque l’expérience doit vivre directement dans l’interface du CRM.

API, Workflow, SDK ou no-code : comment choisir ?

No-code et API ne sont pas opposés. Une architecture pragmatique peut réserver l’API au flux critique et utiliser Make ou n8n pour les automatismes périphériques.

Notre guide des intégrations Attio présente les principales options selon votre stack.

Trois intégrations concrètes

Connecter Attio à un produit SaaS

Lorsqu’un workspace est créé dans votre produit, l’intégration crée ou met à jour l’entreprise, les utilisateurs et le compte correspondant dans Attio. Les événements d’activation, d’upgrade ou de churn alimentent ensuite des attributs CRM.

L’upsert et les identifiants externes sont essentiels pour éviter les doublons.

Déclencher l’onboarding après la vente

Lorsqu’un deal passe à « gagné », un webhook lance la création du projet d’onboarding, des tâches et des notifications. Le Workflow Attio peut couvrir les actions internes ; l’API ou n8n prend le relais si plusieurs systèmes métier sont impliqués.

Synchroniser facturation et renouvellements

Une intégration peut rattacher les abonnements, factures ou échéances provenant de Stripe, Pennylane ou d’un ERP à l’entreprise concernée. Le CRM peut ensuite créer une tâche avant un renouvellement ou signaler un impayé.

Construire une intégration Attio fiable

Une démonstration réussie n’est pas encore une intégration de production.

Avant le déploiement :

1. définissez le système maître pour chaque donnée ;

2. conservez un identifiant externe stable ;

3. utilisez l’upsert plutôt qu’une création aveugle ;

4. rendez les traitements de webhook idempotents ;

5. séparez staging et production ;

6. journalisez les requêtes, erreurs et identifiants ;

7. ajoutez une queue pour les opérations longues ;

8. prévoyez une réconciliation périodique ;

9. surveillez les webhooks dégradés et les erreurs 429 ;

10. documentez la procédure de reprise.

Le modèle flexible d’Attio ne dispense pas de définir des règles de synchronisation claires. Une donnée modifiable dans plusieurs systèmes sans arbitrage finit presque toujours par diverger.

Besoin d’aide pour intégrer Attio à votre stack ?

HyperOps accompagne les entreprises B2B dans la conception et le développement d’intégrations Attio : modèle de données, API, webhooks, Workflows, n8n, Make et App SDK.

Nous commençons par identifier les données maîtres, les volumes et les erreurs à gérer avant de choisir le niveau technique adapté. L’objectif n’est pas de développer du code pour le principe, mais de construire une intégration simple à superviser et fiable dans la durée.

Découvrez notre accompagnement sur la page Agence Attio, notre expertise en automatisation et IA ou présentez-nous votre projet.

Questions fréquentes sur l’API Attio