Quelques généralités sur l’API

L’API Campaign expose l’ensemble des fonctionnalités de la plateforme Campaign via une interface de programmation normalisée.

Plateforme Campaign by Dolist

Campaign est une suite complète d’outils de communication SaaS, comprenant le messaging par courrier électronique, les SMS et le marketing automation.

L’API Campaign est une API RESTful qui s’appuie sur le standard OpenAPI (Swagger RESTful API).

La documentation détaillée de l’API et l’interface de Swagger sont 2 outils qui vont vous permettre de tester l’intégralité des possibilités proposées par l’API Campaign.

Points de terminaison

L’accès à l’API s’effectue en adressant des requêtes HTTPS à une url de point de terminaison spécifique, dans laquelle les méthodes GET, POST, PUT et DELETE pilotent la manière dont vous interagissez avec les objets disponibles.

L’API est accessible uniquement via un protocole sécurisé HTTPS (certificat TLS).

Point de terminaison de l’API : https://apiv9.dolist.net/v1/

Authentification à l’API

Pour accéder à l’API vous aurez besoin d’une clé d’authentification et d’un numéro de compte (AccountID dans l’API).

Requêtes

Les demandes doivent être envoyées via HTTPS avec les paramètres formatés en JSON (application/json). Toutes les requêtes doivent inclure les en-têtes accept: application/json et X-API-Key : xxxxxxx.

Exemple d’appel en curl :

Curl -X GET "https://apiv9.dolist.net/v1/applications"
-H "accept: application/json"
-H "X-API-Key: votre_clé_API"

Cette documentation vous propose des exemples de codes pour chaque méthode de l’API dans de nombreux languages (Shell, Go, Java, Javascript, Node; Obj-C, php, Python, PowerShell, Ruby, Swift, C#, C, etc…).

Langues de l’API

L’en-tête Accept-Language de la requête indique dans quelles langues sont attendues les données en entrée et en sortie de l’API. L’API permet de dialoguer en 3 langues (français, anglais et espagnol).

La langue par défaut de l’API est l’anglais (si l’en-tête Accept-Language de la requête n’est pas précisée).

Par exemple une requête avec en entête Http :

  • Accept-Language: fr-FR,fr;q=0.9,en-US;q=0.8,en;q=0.7 retournera des réponses en français
  • Accept-Language: en-US,en;q=0.9,fr-FR;q=0.8,fr;q=0.7 retournera des réponses en anglais
  • Accept-Language: es-ES,es;q=0.9,fr-FR;q=0.8,fr;q=0.7 retournera des réponses en espagnol

Format des dates / heures

  • Tous les paramètres de date de l’API sont des dates / heures qui s’appuient sur le format ISO-8601
  • L’API accepte tous les fuseaux horaires
  • Toutes les dates / heures sont stockées et retournées par l’API dans le fuseau horaire UTC (Temps Universel Coordonné)
  • Il est recommandé de ne pas utiliser le temps (heures, minutes, secondes, nanosecondes, décalage horaire, fuseau horaire) si vous n’en avez pas besoin. Renseigner alors les dates avec un format simple YYYY-MM-DD que l’API interprètera automatiquement comme YYYY-MM-DDT00:00:00.0000000.

L’API retourne uniquement des dates / heures aux 2 formats suivants (dans toutes les langues) :

  • Avec le fuseau horaire au format YYYY-MM-DDTHH:MM:ss.nnnnnnn+hh:mm pour toutes les dates / heures du système et les évènements. Exemple : 2021-03-22T05:06:07.0000000+01:00
  • Sans le fuseau horaire au format YYYY-MM-DDTHH:MM:ss.nnnnnnn pour toutes les dates / heures stockées dans les champs de contacts. Exemple : 2021-03-22T05:06:07.0000000.

L’API accepte en entrée tous les formats de dates / heures suivants :

  • En paramètre de la requête (selon les standards http et URI) pour toutes les langues :

    • YYYY-MM-DD ou YYYY/MM/DD ou YYYYMMDD : dates simples sans horaires (sans les heures, minutes, secondes et nanosecondes) l’API enregistrera YYYY-MM-DDT00:00:00.0000000
    • YYYY-MM-DDTHH:MM:ss ou YYYY/MM/DDTHH:MM:ss ou YYYYMMDDTHH:MM:ss : avec le temps mais sans les nanosecondes
    • YYYY-MM-DDTHH:MM:ss.nnnnnnn ou YYYY/MM/DDTHH:MM:ss.nnnnnnn ouYYYYMMDDTHH:MM:ss.nnnnnnn : en spécifiant les nanosecondes mais sans le fuseau horaire (par défaut UTC)
    • YYYY-MM-DDTHH:MM:ss.nnnnnnnZ ou YYYY/MM/DDTHH:MM:ss.nnnnnnnZ ou YYYYMMDDTHH:MM:ss.nnnnnnnZ : en heure UTC
    • YYYY-MM-DDTHH:MM:ss.nnnnnnn+hh:mm ou YYYY/MM/DDTHH:MM:ss.nnnnnnn+hh:mm ou YYYYMMDDTHH:MM:ss.nnnnnnn+hh:mm : en précisant le décalage horaire UTC avec + ou - et le fuseau horaire avec hh:mm
  • Dans le corps de la requête (selon les standards JSON) tous les formats de dates / heures précédents ainsi que toutes les dates / heures en langues régionales au format ISO-8601 en fonction de la valeur spécifiée en entête dans Accept-Language (liste non exhaustive ci-dessous).

Locale en-US : anglais, États-Unis

Modèles de dates et d'heures Exemple
MMMM d yyyy March 22 2021
yyyy-MM-ddXXX 2021-03-22+01:00
MM/dd/yyyy 03/22/2021
yyyy/M/d 2021/3/22
MM/dd/yy h:mm a 03/22/21 5:06 AM
MM-dd-yy h:mm a 03-22-21 5:06 AM
M-d-yy h:mm a 3-22-21 5:06 AM
MMM d, yyyy h:mm:ss a Mar 22, 2021 5:06:07 AM
MM-dd-yyyy h:mm:ss a 03-22-2021 5:06:07 AM
yyyy-MM-dd h:mm:ss a 2021-03-22 5:06:07 AM
yyyy-MM-dd HH:mm:ss.S 2021-03-22 05:06:07.0
MM/dd/yyyy h:mm:ss a 03/22/2021 5:06:07 AM
MM/dd/yy h:mm:ss a 03/22/21 5:06:07 AM
MM/dd/yy H:mm:ss 03/22/21 5:06:07
MM/dd/yyyy h:mm a 03/22/2021 5:06 AM
MM-dd-yy h:mm:ss a 03-22-21 5:06:07 AM
MM-dd-yyyy h:mm a 03-22-2021 5:06 AM
yyyy-MM-dd h:mm a 2021-03-22 5:06 AM
MMM.dd.yyyy Mar.22.2021

Locale fr-FR : français, France

Modèles de dates et d'heures Exemple
dd/MM/yyyy 22/03/2021
dd/MM/yy 22/03/21
d MMM yyyy 22 mars 2021
EEEE d MMMM yyyy lundi 22 mars 2021
dd/MM/yyyy HH:mm:ss 22/03/2021 05:06:07
d/M/yyyy HH:mm:ss 22/3/2021 05:06:07
dd/MM/yyyy HH:mm:ss+hh:mm 22/03/2021 05:06:07+02:00
d/M/yyyy HH:mm:ss+hh:mm 22/3/2021 05:06:07+02:00
EEEE d MMMM yyyy HH' h 'mm z lundi 22 mars 2021 05 h 06 CET
dd/MM/yyyy HH:mm 22/03/2021 05:06
d/M/yyyy HH:mm 22/3/2021 05:06
dd-MM-yyyy 22-03-2021
dd-MM-yy 22/03/21
dd-MM-yyyy HH:mm:ss 22-03-2021 05:06:07
d-M-yyyy HH:mm:ss 2-3-2021 05:06:07
dd-MM-yyyy HH:mm:ss 22-03-2021 05:06:07
d-M-yyyy HH:mm:ss 22-3-2021 05:06:07
dd-MM-yyyy HH:mm:ss+hh:mm 22-03-2021 05:06:07+02:00
d/M/yyyy HH:mm:ss+hh:mm 22-3-2021 05:06:07+02:00

Locale es-ES : espagnol, Espagne

Modèles de dates et d'heures Exemple
dd/MM/yy 22/03/21
d MMM yyyy 22 de marzo de 2021
EEEE d MMMM yyyy Lunes 22 de marzo de 2021
dd/MM/yyyy HH:mm:ss 22/03/2021 05:06:07
d/M/yyyy HH:mm:ss 22/3/2021 05:06:07
EEEE d MMMM yyyy HH' h 'mm z Lunes 22 de marzo de 2021 05 h 06 CET
dd/MM/yyyy HH:mm 22/03/2021 05:06
d/M/yyyy HH:mm 22/3/2021 05:06

Locale en-GB : anglais, Grande Bretagne

Modèles de dates et d'heures Exemple
dd/M/yyyy 22/3/2021
dd-M-yyyy 22-3-2021
dd-MM-yyyyTHH:mm:ss 22-03-2021T08:00:00
dd-MM-yy 22/03/21
dd-MM-yyyy HH:mm:ss 22-03-2021 05:06:07
dd/M/yyyy HH:mm:ss 22/3/2021 05:06:07
dd/MM/yyyy HH:mm:ss+hh:mm 22/03/2021 05:06:07+02:00
d/M/yyyy HH:mm:ss+hh:mm 22/3/2021 05:06:07+02:00

Pour implémenter d’autres valeurs Accept-language, consulter les formats de dates standards par pays.

Réponses

L’API renverra pour chaque requête un code de statut qui s’appuie sur la norme RFC 2616 :

  • 200 et 201 et 204 : Succès de la requête.
  • 403 : Droit insuffisant pour effectuer cette tâche ou accès refusé.
  • 404 : Erreur fonctionnelle lors de l’opération (POST et PUT).
  • 500 et 503 : Une exception inattendue est survenue. Veuillez contacter le support.

Attention, si vous obtenez le code erreur 403 et la réponse suivante de l’API :

{
  "ResponseStatus": {
    "ErrorCode": "Forbidden",
    "Message": "Unauthorized request blocked."
  }
}

merci de vous assurer que :

  • Le numéro de compte AccountID saisi est correct.
  • La clé d’authentification X-API-Key saisie est bien liée au compte et correcte.
  • L’adresse IP utilisée par la machine qui réalise l’appel est bien renseignée dans le portail Client Dolist par l’administrateur de votre compte.

L’API peut renvoyer en fonction de la requête 3 types de réponses :

  1. Une réponse vide (par exemple dans le cas d’une mise à jour de données réalisée avec succès lors d’un POST ou un PUT).
  2. Un objet JSON correspondant aux résultats de la requête jouée avec succès.
  3. En cas d’erreur, l’objet JSON contiendra un code et une description de l’erreur.

Pagination

Nom Type Description
limit entier Le nombre de résultats retournés par la requête
offset entier L’index du résultat retourné par la requête

L’API n’a pas de limite dans le nombre de résultats qu’elle retourne (excepté pour la méthode qui permet de rechercher des contacts POST/contacts/search qui retournera au maximum 50 résultats).

Il est pour autant possible de paginer les résultats en utilisant les paramétres de requête offset et limit.

Toutes les réponses qui comportent plusieurs résultats débuteront par :

{
  "Count": 20,   // Nombre de résultats renvoyés dans la réponse actuelle
  "Total": 62,  // Nombre total de résultats de la requête
  "ItemList": [
    { .......

Afin de récupérer 20 résultats à chaque appel pour des raisons d’affichage par exemple, on réalisera :

  • Un premier appel pour récupérer les 20 premiers résultats en passant offset à 0 et limit à 20
  • Un deuxième appel pour récupérer les 20 résultats suivants en passant offset à 20 et limit à 20
  • Un troisième appel pour récupérer les 20 résultats suivants en passant offset à 40 et limit à 20
  • Un dernier appel pour récupérer les 2 derniers résultats en passant offset à 60 et limit à 20

Pour implémenter d’autres valeurs Accept-language, consulter les formats de dates standards par pays.

Il est recommandé de ne pas utiliser le temps (heures, minutes, secondes, nanosecondes, décalage horaire, fuseau horaire) si vous n’en avez pas besoin. Renseigner alors les dates avec un format simple YYYY-MM-DD que l’API interprètera automatiquement comme YYYY-MM-DDT00:00:00.0000000.

Réponses

L’API renverra pour chaque requête un code de statut qui s’appuie sur la norme RFC 2616 :

  • 200 et 201 et 204 : Succès de la requête.
  • 403 : Droit insuffisant pour effectuer cette tâche ou accès refusé.
  • 404 : Erreur fonctionnelle lors de l’opération (POST et PUT).
  • 500 et 503 : Une exception inattendue est survenue. Veuillez contacter le support.

Attention, si vous obtenez le code erreur 403 et la réponse suivante de l’API :

{
  "ResponseStatus": {
    "ErrorCode": "Forbidden",
    "Message": "Unauthorized request blocked."
  }
}

merci de vous assurer que :

  • Le numéro de compte AccountID saisi est correct.
  • La clé d’authentification X-API-Key saisie est bien liée au compte et correcte.
  • L’adresse IP utilisée par la machine qui réalise l’appel est bien renseignée dans le portail Client Dolist par l’administrateur de votre compte.

L’API peut renvoyer en fonction de la requête 3 types de réponses :

  1. Une réponse vide (par exemple dans le cas d’une mise à jour de données réalisée avec succès lors d’un POST ou un PUT).
  2. Un objet JSON correspondant aux résultats de la requête jouée avec succès.
  3. En cas d’erreur, l’objet JSON contiendra un code et une description de l’erreur.

Pagination

Nom Type Description
limit entier Le nombre de résultats retournés par la requête
offset entier L’index du résultat retourné par la requête

L’API n’a pas de limite dans le nombre de résultats qu’elle retourne (excepté pour la méthode qui permet de rechercher des contacts POST/contacts/search qui retournera au maximum 50 résultats).

Il est pour autant possible de paginer les résultats en utilisant les paramétres de requête offset et limit.

Toutes les réponses qui comportent plusieurs résultats débuteront par :

{
  "Count": 20,   // Nombre de résultats renvoyés dans la réponse actuelle
  "Total": 62,  // Nombre total de résultats de la requête
  "ItemList": [
    { .......

Afin de récupérer 20 résultats à chaque appel pour des raisons d’affichage par exemple, on réalisera :

  • Un premier appel pour récupérer les 20 premiers résultats en passant offset à 0 et limit à 20
  • Un deuxième appel pour récupérer les 20 résultats suivants en passant offset à 20 et limit à 20
  • Un troisième appel pour récupérer les 20 résultats suivants en passant offset à 40 et limit à 20
  • Un dernier appel pour récupérer les 2 derniers résultats en passant offset à 60 et limit à 20