La plupart des intégrations utilisent l'API pour synchroniser les contacts : ajouter de nouveaux contacts à des groupes, mettre à jour leurs informations et leur statut, et les retirer. Ce guide présente les appels de base. Pour tous les paramètres, consultez API reference: contacts et API reference: groups.

Avant de commencer, vérifiez que vous savez faire des appels API de base. Consultez Premiers pas avec l'API ActiveTrail.

Trouver un contact

Les contacts sont identifiés par leur ID de contact. Pour trouver un contact par son adresse e-mail ou son numéro de mobile, recherchez-le dans la liste des contacts :

GET https://webapi.mymarketing.co.il/api/contacts?SearchTerm=dana@example.com

Prenez l'id dans la réponse, puis récupérez toutes les informations du contact :

GET https://webapi.mymarketing.co.il/api/contacts/{id}

Une réponse 404 signifie que le contact n'existe pas dans votre compte. La recherche d'adresses e-mail qui contiennent un signe plus (+) n'est pas prise en charge ; consultez Le paramètre de recherche de l'API et le signe plus (+).

Pour obtenir en un seul appel le statut e-mail et le statut SMS d'un contact, faites la recherche avec GET https://webapi.mymarketing.co.il/api/contacts/GetWithSmsState?SearchTerm=dana@example.com. Chaque contact est renvoyé avec state (le statut e-mail) et sms_state. Si rien ne correspond, la réponse est une liste vide.

Ajouter un contact à un groupe

Pour ajouter un contact et le placer dans un groupe en un seul appel, envoyez une requête POST au point de terminaison des membres du groupe. Vous pouvez aussi définir le statut e-mail et le statut SMS du contact :

POST https://webapi.mymarketing.co.il/api/groups/{id}/members

{
  "email": "dana@example.com",
  "sms": "0501234567",
  "first_name": "Dana",
  "last_name": "Levi",
  "status": "Subscribed",
  "sms_status": "Subscribed"
}

Les valeurs de statut sont Subscribed, Unsubscribed et Pending. Un contact inactif dans ActiveTrail ne peut pas être ajouté avec le statut Subscribed.

POST /api/contacts crée aussi un contact, mais ne l'ajoute à aucun groupe : vous ne pouvez pas lui envoyer d'e-mail ni de SMS tant qu'il n'est pas dans un groupe. Pour ajouter un nouveau contact à qui vous voulez écrire, utilisez le point de terminaison des membres du groupe ci-dessus.

Pour ajouter de nombreux contacts à la fois, utilisez POST /api/contacts/Import, jusqu'à 1 000 contacts par appel.

Mettre à jour un contact

Envoyez une requête PUT avec uniquement les champs à modifier. Par exemple, pour désinscrire un contact des e-mails :

PUT https://webapi.mymarketing.co.il/api/contacts/{id}

{
  "status": "Unsubscribed"
}

Retirer un contact d'un groupe

DELETE https://webapi.mymarketing.co.il/api/groups/{id}/members/{memberId}

Le contact est retiré du groupe seulement. Il reste dans votre compte.

Supprimer un contact

Supprimer un contact supprime aussi ses statistiques : mieux vaut désinscrire les contacts. Si vous devez vraiment en supprimer un :

DELETE https://webapi.mymarketing.co.il/api/contacts/{id}

Créer ou mettre à jour lors d'une synchronisation

Pour les tâches qui synchronisent régulièrement des contacts depuis un autre système :

  • Si vos données changent lentement, essayez d'abord de mettre à jour le contact, et ne le créez que si la mise à jour échoue.
  • Pour les imports volumineux, créez d'abord les contacts, et ne mettez à jour que ceux qui existent déjà.