SMOC Public Contacts API — Guide d'intégration

Guide de l’API Contacts Publiques SMOC — un endpoint REST en lecture seule pour lister les contacts et obtenir des totaux agrégés pour votre entreprise. Utilisez-le dans des intégrations personnalisées, des tâches de synchronisation ou avec l’application Zapier.

Vue d’ensemble

L’API Publique SMOC permet à des systèmes tiers de lire les contacts pour une seule entreprise. Elle est hébergée sur Cloudflare Workers et automatiquement limitée à l’entreprise liée à votre clé API.

Ce que l’API permet aujourd’hui :

• Lister les contacts de votre entreprise (jusqu’à 500 par requête)
• Retourner les totaux agrégés de leads et de clients
• Limiter automatiquement les données à l’entreprise liée à votre clé API

Ce que l’API ne permet pas :

• Créer, modifier ou supprimer des contacts
• Paginer avec des curseurs ou offsets (seulement une limite limit)
• Interroger plusieurs entreprises avec une seule clé

Ce contrat compatible Zapier reste inchangé. L’unique endpoint contacts pour ce contrat est :

GET /api/company/mongocontact

Une recherche de contacts plus riche est additive : POST /api/v2/contacts_search. Ne migrez pas Zapier hors de mongocontact.

Pour la configuration dans la Console, l’authentification et un aperçu des fonctions, commencez par le guide de connexion à l’API REST.

Obtenir votre clé API

Toutes les intégrations de données SMOC utilisent le même modèle de jeton Console que Zapier et MCP :

1. Connectez-vous à la Console SMOC.
2. Allez dans Paramètres → Intégrations → API (utilisez Intégrations → Zapier pour la configuration spécifique à Zapier).
3. Nommez éventuellement la clé et définissez une date d’expiration, puis cliquez sur Générer une nouvelle clé API.
4. Copiez la clé immédiatement — elle n’est affichée qu’une seule fois et ne pourra pas être récupérée plus tard.

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 ici lorsque vous devez faire une rotation des identifiants.

Chaque clé est liée à une seule entreprise. La clé porte une revendication operatorId égale à l’ID de cette entreprise. L’API utilise cela pour limiter toutes les données de contact — vous ne pouvez pas transmettre un autre ID d’entreprise dans la requête.

URLs de base

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

Exemple d’endpoint complet :

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

Authentification

Envoyez votre clé API dans un en-tête HTTP personnalisé nommé token :

GET /api/company/mongocontact HTTP/1.1
Host: api.smoc.ai
token: <your-api-key>
Content-Type: application/json

L’API vérifie la clé et lit la revendication operatorId pour déterminer les contacts de quelle entreprise retourner. Vous ne transmettez pas d’ID d’entreprise dans l’URL ou la chaîne de requête.

À ne pas utiliser :

• Authorization: Bearer … — cet en-tête n’est pas accepté par cet endpoint (même si la page "Accès API" de la Console peut actuellement l’indiquer). Utilisez l’en-tête token dans les intégrations jusqu’à ce que la prise en charge du Bearer soit ajoutée.
• Les clés secrètes Clerk (sk_…) ou les clés publiables (pk_…) — elles sont rejetées avec 401 Invalid token type.

Requête

Méthode : uniquement GET. Les autres méthodes (ex. POST) retournent 404 Not Found.

Paramètres de requête

Paramètre	Type	Obligatoire	Défaut	Description
limit	entier	Non	100	Nombre maximum de contacts à retourner. Doit être entre 1 et 500.
sortByField	chaîne	Non	(aucun)	Trier les contacts par ce champ en ordre décroissant.
status	chaîne	Non	(aucun)	Filtrer par statut du contact. status=1 est le sondage standard des leads, incluant les smart leads positifs issus d’un parcours de messages.

Valeurs sortByField autorisées :

Valeur	Trie par
createdAt	Date de création du contact. Lorsque ce tri est demandé (et que status est omis ou 1), les smart leads récents issus d’un parcours de messages des 14 derniers jours sont fusionnés et la page est retriée par max(createdAt, leadCapturedAt) pour qu’ils apparaissent sans déplacer les nouveaux contacts web.
updatedAt	Date de dernière mise à jour
lastConversationDate	Date de dernière conversation
leadCapturedAt	Date à laquelle le contact est devenu un smart lead (retombe sur updatedAt pour les lignes historiques)
companyUsers.lastConversationDate	Alias hérité pour lastConversationDate (compatibilité Zapier)

Le tri est toujours décroissant (du plus récent/haut en premier). Si omis, l’ordre naturel de MongoDB est utilisé.

Réponse

Succès (200 OK)

{
  "data": [ /* array of contact objects */ ],
  "leadsCount": 42,
  "customerCount": 18
}

Champ	Type	Description
data	tableau	Enregistrements de contacts pour votre entreprise
leadsCount	nombre	Contacts avec le statut "1" ou null
customerCount	nombre	Contacts avec le statut "2"

leadsCount et customerCount reflètent tous les contacts de l’entreprise, pas seulement la page courante.

Champs de l’objet contact

Chaque élément de data inclut uniquement les champs ci-dessous (les champs sensibles/internes sont exclus) :

Champ	Description
id	Identifiant de sondage Zapier. Généralement le _id Mongo. Les smart leads convertis tardivement (leadCapturedAt au moins 1h après createdAt, et à partir du 11/09/2026) utilisent {mongoId}__sl pour que New Contact puisse se déclencher. Utilisez contactId pour l’id Mongo stable.
contactId	_id Mongo stable. Ne change pas lorsque id est réécrit pour un smart lead tardif.
linkedinUrl	URL du profil LinkedIn si présent (linkedinUrl de premier niveau ou le premier linkedinProfiles[].url).
userId	Identifiant utilisateur
email	Adresse e-mail
firstName	Prénom
lastName	Nom
msisdn	Numéro de téléphone
company	Nom de l’entreprise (employeur du contact, si capturé)
city, state, street, zip	Champs d’adresse
status	Statut du cycle de vie du contact (voir ci-dessous). Les smart leads positifs issus d’un parcours de messages utilisent "1" comme les leads issus de formulaire web.
leadSentiment	"positive" ou "negative" lorsqu’une réponse à un parcours de messages a été classifiée ; sinon omis
leadCapturedAt	Date ISO-8601 à laquelle le contact est devenu un smart lead positif (retombe sur updatedAt si absent)
tags	Tags de contact résolus { id, name, systemKind? }[] (inclut Auto : Lead positif / Auto : Lead négatif)
brandId	Identifiant de la marque
operatorId	Identifiant de l’entreprise/opérateur
createdAt	Horodatage de création ISO-8601
updatedAt	Horodatage de dernière mise à jour ISO-8601
lastConversationDate	Date ISO-8601 de la dernière conversation
acceptedCommunication	Si le contact a accepté la communication
acceptedPrivacy	Si le contact a accepté les conditions de confidentialité
inviterUser	Qui a référé ce contact (objet)
rewardFlows	Parcours où des récompenses ont été gagnées
promosPresented	Promotions affichées au contact
promosRedeemed	Promotions utilisées
answeredSurveyQuestions	Réponses aux enquêtes
usersReferred	Utilisateurs référés par ce contact
referralLinks	Détails du lien de parrainage
visitList	Historique des visites/sessions (appareil, UTM, géo, etc.)
textFields	Champs texte personnalisés capturés dans les parcours

Les champs peuvent être null ou absents s’ils ne sont pas collectés pour ce contact.

Valeurs de statut du contact

Statut	Signification
"1"	Lead (inclut les smart leads positifs issus d’un parcours de messages)
"2"	Client
"3"	Perdu
"4"	Converti
null	Compté comme Lead dans les totaux

Structures d’objets imbriqués

inviterUser

{
  "id": 123,
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]"
}

rewardFlows / promos

{ "id": "...", "title": "Summer promo" }

referralLinks

{
  "key": "...",
  "campaignId": 1,
  "campaignName": "...",
  "flowVariantId": 1,
  "url": "https://...",
  "share": true
}

visitList — inclut browser, os, deviceType, country, region, city, champs UTM (utmSource, utmMedium, utmCampaign, etc.), referrer, landingPage, userAgent, ip.

answeredSurveyQuestions — inclut texte question/réponse, traductions, infos récompense et horodatages.

textFields — champs personnalisés de parcours : flowId, flowName, variantId, variantName, key, value.

Réponses d’erreur

Toutes les erreurs retournent du JSON avec un champ error. Certaines incluent un hint.

Statut HTTP	Condition	Exemple de corps
401	En-tête token manquant	{ "error": "Missing token header" }
401	Clé invalide/révoquée, ou clé sk_/pk_ utilisée	{ "error": "Invalid or revoked token", "hint": "You can create a valid token from the Integration Dashboard." }
403	Clé valide mais sans revendication operatorId	{ "error": "Unauthorized" }
422	limit > 500	{ "error": "limit must not exceed 500" }
422	sortByField invalide	{ "error": "Invalid sortByField value" }
422	status invalide	{ "error": "Invalid status value" }
404	Mauvais chemin ou méthode	Not Found (texte brut)

Exemples de requêtes

Basique — récupérer jusqu’à 100 contacts :

curl -s \
  -H "token: YOUR_API_KEY" \
  "https://api.smoc.ai/api/company/mongocontact"

Récupérer 25 contacts, triés par dernière conversation :

curl -s \
  -H "token: YOUR_API_KEY" \
  "https://api.smoc.ai/api/company/mongocontact?limit=25&sortByField=lastConversationDate"

Récupérer les leads standards (formulaire web et smart leads positifs issus d’un parcours de messages) :

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

Exemple de réponse tronquée :

{
  "data": [
    {
      "id": "665a1b2c3d4e5f6789012345",
      "email": "[email protected]",
      "firstName": "Alex",
      "lastName": "Smith",
      "msisdn": "+4712345678",
      "status": "2",
      "operatorId": "10",
      "createdAt": "2025-03-15T10:22:00.000Z",
      "lastConversationDate": "2025-06-01T14:30:00.000Z",
      "visitList": [
        {
          "deviceType": "mobile",
          "browser": "Chrome",
          "country": "NO",
          "utmSource": "google"
        }
      ]
    }
  ],
  "leadsCount": 120,
  "customerCount": 45
}

Intégration Zapier

SMOC propose une application Zapier qui utilise ce même endpoint. Parcours typique :

1. Obtenez l’accès via le lien d’invitation Zapier (depuis Console → Paramètres → Intégrations → Zapier).
2. Générez une clé API dans la Console.
3. Dans Zapier : Mes applications → Intégrations personnalisées → Ajouter une connexion et collez la clé lorsque le jeton est demandé.
4. Créez un Zap avec le déclencheur SMOC → Nouveau contact.

Le déclencheur Zapier interroge cet endpoint et considère les contacts retournés comme nouveaux à leur apparition. Nouveau contact se base sur id. Les smart leads convertis tardivement (prospects importés qui reçoivent plus tard leadCapturedAt) reçoivent désormais un id {contactId}__sl stable pour que le Zap existant Nouveau contact puisse se déclencher une fois. contactId reste l’id Mongo pour le mapping CRM. Ceci s’applique à chaque entreprise ; seules les captures à partir du 11/09/2026 sont réécrites (temporaire jusqu’à l’existence d’un déclencheur dédié Nouveau smart lead). Privilégiez HubSpot Créer ou mettre à jour un contact sur l’email pour éviter les doublons si le prospect a déjà été synchronisé. Voir le eGuide Zapier pour une configuration pas à pas.

Limitations et notes de conception

• Les clés client sont en lecture seule — mongocontact n’écrit pas. Les outils REST v2 de modification sont réservés aux super-admins.
• Pas de pagination offset/curseur — utilisez limit (max 500). Pour synchroniser tous les contacts, triez de façon cohérente et suivez les IDs vus côté client, ou utilisez le modèle d’interrogation de Zapier.
• Limitation automatique — la clé API détermine l’entreprise ; il n’y a pas de paramètre de substitution multi-tenant.
• Champs limités par projection — seuls les champs listés ci-dessus sont retournés ; les champs internes de la base sont supprimés.
• Compatibilité héritée — le chemin de l’endpoint et l’alias de tri companyUsers.lastConversationDate existent pour la compatibilité avec l’API d’origine et l’application Zapier.

Connexe : MCP (clients IA)

Le même worker API expose aussi MCP sur https://api.smoc.ai/mcp et REST v2 sur POST /api/v2/{toolName} avec des outils contacts plus riches (contacts_search, contacts_get, contacts_get_stats, etc.). Voir le eGuide MCP et la référence REST v2.

Pour une vue d’ensemble produit de tous les parcours d’intégration, voir smoc.ai/integrations.

Référence rapide

Élément	Valeur
Endpoint	GET /api/company/mongocontact
En-tête d’auth	token: <api-key>
Type de contenu	application/json
Taille de page max	500
Taille de page par défaut	100
Limitation à l’entreprise	Depuis la clé API (revendication operatorId)
Création de clé	Console → Paramètres → Intégrations → API

Voir aussi

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