Connecter SMOC avec l’API REST

Guide simple montrant comment se connecter à l’API REST de SMOC depuis votre propre code, des synchronisations de jobs ou des pipelines CRM. Les clés client sont limitées à l’entreprise et sont en lecture seule par défaut. Les clés avec écriture activée peuvent effectuer certaines écritures limitées, y compris l’envoi depuis la boîte de réception ; elles ne peuvent pas modifier les graphes de parcours, publier des parcours, ou lancer des campagnes de prospection LinkedIn. Les clés super-utilisateur peuvent enregistrer des brouillons de parcours et de thèmes sur les mêmes appels POST /api/v2/{toolName} ; la publication nécessite toujours une intervention humaine dans Studio ou Console. Les outils de domaine sont disponibles sur REST v2 sous POST /api/v2/{toolName} (mêmes gestionnaires que MCP). Liste complète des appels : Référence API REST v2. GET /api/company/mongocontact reste pour Zapier.

Obtenir votre clé API

1. Allez dans Paramètres → Intégrations → API dans SMOC Console.
2. Donnez éventuellement un nom et une date d’expiration à la clé (7, 30 ou 90 jours). Laissez l’expiration sur Aucune expiration si vous ne souhaitez pas qu’elle expire.
3. Générez la clé et copiez-la immédiatement — elle n’est affichée qu’une seule fois, stockez-la donc en lieu sûr.

Votre clé est liée à votre entreprise. Chaque requête effectuée avec elle est automatiquement limitée à vos données. Générer une nouvelle clé ne révoque pas les clés existantes. Les clés émises sont listées sur la même page — révoquez les clés inutilisées à cet endroit. La page MCP utilise les mêmes contrôles — voir la capture d’écran dans le guide MCP.

URL de base

URL de base : https://api.smoc.ai

Point de terminaison complet pour les contacts :

GET https://api.smoc.ai/api/company/mongocontact

Authentification

Contacts hérités : envoyez la clé dans un en-tête HTTP personnalisé nommé token. REST v2 accepte Authorization: Bearer ou token.

GET /api/company/mongocontact HTTP/1.1
Host: api.smoc.ai
token: YOUR_SMOC_API_KEY

N’utilisez pas les clés secrètes Clerk (sk_…) ni les clés publiables (pk_…).

Quelles fonctions existent

REST v2 — POST /api/v2/{toolName}

Reprend les outils de domaine MCP (contacts_search, cpcs_overview, inbox_threads_list, etc.). OpenAPI : GET /api/v2 ou GET /api/v2/openapi.json. Voir la référence REST v2.

Lister les contacts de l’entreprise — GET /api/company/mongocontact (Zapier / compat)

Retourne une page de contacts pour l’entreprise liée à la clé, ainsi que des totaux agrégés.

Ce que cela retourne

• Fiches contact : nom, email, téléphone, statut, adresse, date de dernière conversation, historique de visites/UTM, réponses aux enquêtes, champs texte personnalisés, données de parrainage et de promotion si collectées. Les leads intelligents positifs issus d’un parcours de messages sont des leads standards (status: "1") et incluent aussi leadSentiment, leadCapturedAt et tags si présents.
• leadsCount — contacts avec le statut lead (y compris non défini)
• customerCount — contacts avec le statut client

Les totaux couvrent tous les contacts de l’entreprise, pas seulement la page courante.

Paramètres de requête

Paramètre	Par défaut	Description
limit	100	Nombre maximum de contacts à retourner (1–500)
sortByField	(aucun)	Tri décroissant par createdAt, updatedAt, lastConversationDate ou leadCapturedAt
status	(aucun)	Filtrer par statut du contact. status=1 est le sondage standard de leads et inclut les leads intelligents positifs issus d’un parcours de messages

Valeurs de statut du contact : "1" lead, "2" client, "3" perdu, "4" converti.

Les clés client ne peuvent pas créer, mettre à jour ou supprimer des contacts. Il n’y a pas de pagination par curseur sur mongocontact — utilisez limit et suivez les IDs vus côté client, ou utilisez le polling Zapier. La recherche avancée se fait via POST /api/v2/contacts_search.

La structure détaillée des réponses est dans la référence API Contacts Publique.

Exemple de requête

curl -s \
  -H "token: YOUR_SMOC_API_KEY" \
  "https://api.smoc.ai/api/company/mongocontact?status=1&limit=25&sortByField=leadCapturedAt"

Ce qui n’est pas disponible sur l’API client

Les clés avec écriture activée ne peuvent toujours pas publier un parcours, activer/désactiver en direct (flowcharts_set_active), supprimer des enregistrements, ou lancer une campagne de prospection LinkedIn. L’envoi depuis la boîte de réception (send) est en option sur une clé avec écriture activée (inbox_threads_send, texte uniquement, nécessite idempotencyKey). Utilisez SMOC MCP depuis Claude, Cursor ou VS Code pour les mêmes outils via MCP.

Notes de sécurité

• La clé n’est affichée qu’une seule fois à la création — stockez-la dans un gestionnaire de mots de passe ou une variable d’environnement.
• Ne jamais commettre la clé dans un dépôt Git.
• Les clés client sont limitées aux données de votre entreprise. Les clés par défaut sont en lecture seule ; les écritures, y compris l’envoi depuis la boîte de réception, sont en option.
• Révoquez les clés inutilisées depuis la liste des clés émises dans Paramètres → Intégrations → API.

Dépannage

• 401 En-tête de jeton manquant : envoyez token: <key>, pas Authorization: Bearer.
• 401 Jeton invalide ou révoqué : vérifiez que la clé est correcte et n’a pas été révoquée.
• 422 la limite ne doit pas dépasser 500 : réduisez le paramètre de requête limit.
• 422 Valeur de statut invalide : utilisez 1, 2, 3 ou 4.

Voir aussi

• Référence API REST v2 — chaque appel POST /api/v2/{toolName}
• Connecter SMOC avec l’API REST
• API Contacts Publique
• MCP pour Claude, Cursor et VS Code