🛠️ API - Qualifications (Fichier CSV / Excel)

Qu'est-ce que l'importation au format CSV/Excel via API des prospects/leads/contacts ?

Vous pouvez envoyer votre fichier CSV/Excel via notre API.
Les prospects seront immédiatement importés dans Pinpo.
Veuillez noter que la limite quotidienne de prospects activés définie sur la plateforme reste applicable.

Comment réaliser l'importation au format CSV/Excel via API des prospects/leads/contacts ?

ℹ️ Voici le lien de la documentation technique (Swagger) ⇒

https://api.pinpo.com/api#/Leads/ImportQualificationsFileController_execute

Étape 1 : Récupérer les informations pour l’appel HTTPS

Pour ce faire il vous suffit de cliquer sur le bouton Accéder dans la carte Connexion via API KEY.

La section Accès API affiche les trois informations nécessaires pour envoyer des contacts à Pinpo depuis votre système :

Champ	Description
API Key de production	Votre clé d'authentification. Elle est masquée par défaut. Cliquez sur l'icône œil (👁) pour la révéler, ou sur l'icône copier (📋) pour la copier dans le presse-papier.
URL d'import	L'endpoint vers lequel envoyer vos requêtes. L'URL inclut l'identifiant de l'agent sélectionné (par exemple : `https://api.pinpo.com/agents/{id_agent}/qualifications`).
ID de l'agent	L'identifiant unique de l'agent sélectionné.

IMPORTANT : Votre API Key est une clé secrète. Ne la partagez jamais dans du code côté client, dans une URL publique ou dans un email. Traitez-la comme un mot de passe.

Étape 2 : Récupérer le fichier template et/ou le fichier d’exemple

Se rendre sur la section “Intégrations" (bandeau latéral gauche).
Sélectionner la section “CSV” , puis cliquer sur le bouton “Accéder” .
Récupérer le fichier d’exemple et / ou le fichier template.

Étape 3 : Remplir votre fichier avec les informations de chaque qualification

Remplissez le fichier en faisant bien attention aux différentes spécificités de chaque colonne.

💡Conseil : N’oubliez pas de bien préciser si ceci sont des qualifications de tests ou non (true ou false)

Agent

Colonne	Description	Obligatoire	Format	Exemple
`agent.id`	Identifiant unique de l'agent IA auquel le lead sera assigné	✅ Oui	UUID	`123e4567-e89b-12d3-a456-426614174001`

La liste des {{agentId}} est présente sur la plateforme PINPO (Intégrations>Connexion via API KEY > ID de l’agent).

Contact

Colonne	Description	Obligatoire	Format	Exemple
`contact.firstname`	Prénom du contact	Non	Texte libre	`John`
`contact.lastname`	Nom de famille du contact	Non	Texte libre	`Doe`
`contact.phone`	Numéro de téléphone mobile du contact	⚠️ Oui*	Format international avec indicatif pays	`+33606060606`
`contact.whatsAppUserId`	Identifiant WhatsApp du contact	⚠️ Oui*	Identifiant WhatsApp	`user.9373795779eb6441c8adb2eaee5b848e7dd174ddd302d7db62142f4722d574b6`
`contact.mail`	Adresse e-mail du contact	Non	E-mail valide	`[email protected]`
`contact.externalId`	Identifiant du contact dans votre CRM (si différent de l'ID du lead)	Non	Texte libre	`contact-789`
`contact.gender`	Genre du contact	Non	`male`, `female`, `other` ou `unknown`	`male`

⚠️ Au moins un des deux champs contact.phone ou contact.whatsAppUserId est requis pour chaque ligne. Si aucun des deux n'est renseigné, la ligne sera rejetée à l'import.

Commercial (Salesperson)

Colonne	Description	Obligatoire	Format	Exemple
`salesperson.firstname`	Prénom du commercial assigné au lead	Non	Texte libre	`Michelle`
`salesperson.lastname`	Nom du commercial assigné au lead	Non	Texte libre	`Scott`
`salesperson.phone`	Numéro de téléphone du commercial	Non	Format international avec indicatif pays	`+33707070707`
`salesperson.mail`	Adresse e-mail du commercial	Non	E-mail valide	`[email protected]`
`salesperson.externalId`	Identifiant du commercial dans votre CRM	Non	Texte libre	`sales-456`
`salesperson.gender`	Genre du commercial	Non	`male`, `female`, `other` ou `unknown`	`female`
`salesperson.iCalUrl`	URL iCal du calendrier du commercial (utilisée pour vérifier ses disponibilités lors de la prise de rendez-vous)	Non	URL iCal valide	`https://michelle.scott.dundermifflin.ical.fr`

Qualification

Colonne	Description	Obligatoire	Format	Exemple
`qualification.externalId`	Identifiant externe du lead dans votre CRM ou système source	Non	Texte libre	`ext-123456`
`qualification.source`	Source d'origine du lead (canal ou campagne d'acquisition)	Non	Texte libre	`Facebook leads`
`qualification.test`	Marquer le lead comme lead de test (ne sera pas traité dans le flux normal de qualification)	Non	`true` ou `false`	`true`

Champs personnalisés (Custom Fields)

Les champs personnalisés permettent d'enrichir vos leads avec des données propres à votre activité. Ajoutez autant de colonnes que nécessaire en utilisant le préfixe qualification.customFields. suivi du nom exact du champ configuré dans votre espace Pinpo.

Colonne	Description	Obligatoire	Format	Exemple
`qualification.customFields.city`	Ville du lead	Non	Texte libre	`Paris`
`qualification.customFields.country`	Pays du lead	Non	Texte libre	`France`
`qualification.customFields.budget`	Budget du lead	Non	Texte libre ou numérique	`500000`
`qualification.customFields.[votre champ]`	Tout autre champ personnalisé de votre choix	Non	Texte libre	—

💡 Important : les noms de champs personnalisés sont sensibles à la casse. qualification.customFields.City et qualification.customFields.city sont considérés comme deux champs différents.
=> Vérifiez l'orthographe exacte de vos clés.

Enregistrez votre fichier.

ℹ️ En cas d’erreur, vous retrouvez ligne par ligne la raison pour laquelle la qualification n’a pas été importée.

Étape 4 : Envoyer le fichier via une requête HTTPS

Vous avez désormais tous les éléments nécessaire à l’envoi de votre fichier via requête HTTP POST.
Consultez le schema dans la documentation technique afin de comprendre ce qui attendu pour l’appel HTTP

⚠️ ATTENTION :
- N'oubliez pas d'indiquer votre authorization dans l'en-tête.

- N'oubliez pas d'indiquer le content-type approprié dans l'en-tête.

- Respectez l'encodage approprié pour votre fichier.

- Vous devez respecter la structure standardisée du modèle de fichier

- Assurez-vous que les données que vous souhaitez voir apparaître dans la sortie des qualifications soient bien présentes dans votre fichier.

- Chaque fichier doit avoir une taille maximale de 5 Mo.

ℹ️ Au sujet de la réconciliation LES LEADS AVEC VOS IDs (ExternalId)

Pour retrouver le qualification.externalId dans le webhook (SORTIE), il doit être présent au bon endroit lorsque vous utilisez la route API /agents/{agentId}/qualifications (ENTRÉE).
Vous devez donc le transmettre dans la clé qualification.externalId afin qu'il apparaisse comme un qualification.externalId lorsque le lead vous revient via le Webhook.
Plus généralement, si vous souhaitez qu'une valeur ou une clé soit visible en sortie (SORTIE), vous devez la transmettre en tant que customFields dans la bonne colonne (ENTRÉE).

💡 Conseil : Commencez toujours par envoyer un fichier de test via l'API avant de connecter votre flux de production. Vérifiez qu'il apparaît bien dans les Qualifications de test de l'agent, puis lancez une conversation de test pour vous assurer que les données sont correctement transmises.

Étape 5 : Traiter le retour HTTPS

Lorsque vous utilisez la route API /agents/{agentId}/qualifications pour importer des leads dans Pinpo, le qualificationId vous sera communiqué dans la réponse de votre requête POST comme mentionné dans la documentation technique : https://api.pinpo.com/api#/Qualifications/ImportQualificationController_execute

Il est PRIMORDIAL de traiter les différents code et retour HTTP afin de s’assurer qu’en cas de rejet par l’API PINPO de votre tentative, votre workflow “sait comment gérer” les cas et vous alerte si besoin.

💡 RAPPEL : Règle #1 : Lorsque vous confiez un lead/prospect/contact à votre agent PINPO, le lead est importé immédiatement et le 1ᵉʳ message est envoyé immédiatement*.

Il vous incombe d'envoyer le prospect au moment opportun.
*Par défaut, pour les prospects reçus par PINPO tard dans la nuit ou tôt le matin, le premier message est reporté au lendemain matin (ce comportement peut être personnalisé).