Purple Portal API : ce que vous pouvez en faire

A technical reference for IT managers and network architects on leveraging the Purple Portal API. This guide details available endpoints, authentication, and real-world use cases for integrating guest WiFi data with enterprise systems to enhance business intelligence and operational efficiency. It covers both REST API and Webhook integration patterns, with concrete case studies from hospitality, retail, and events sectors.

📖 9 min de lecture📝 2,212 mots🔧 2 exemples❓ 3 questions📚 9 termes clés

🎧 Écouter ce guide

Voir la transcription

Welcome to the Purple Technical Briefing. I'm a Senior Content Strategist here at Purple, and in the next ten minutes, I'm going to give you a concise, practical overview of our Portal API — what it is, what you can do with it, and how to leverage it for maximum business impact. This is for the IT managers, the architects, and the operations directors who need to know how to turn their guest WiFi from a simple utility into a powerful data asset.

Let's start with the context. You have guest WiFi across your venues. Every day, hundreds or thousands of people connect. They provide their email, perhaps their name, and they consent to your terms. That's valuable first-party data. The Purple Portal gives you great dashboards to view this, but the real power comes when you connect that data to the rest of your business ecosystem. That's where the Portal API comes in. It's the bridge that allows your systems to talk to our platform programmatically.

Now, let's get into the technical detail. The Portal API is a standard RESTful interface. Authentication is simple and secure, using a straightforward API Key. You don't need to worry about complex OAuth handshakes for server-to-server communication. Critically, there are no rate limits. We built it for enterprise scale, so whether you're running a single hotel or a national chain of five hundred retail locations, the API can handle your volume.

You have two main ways to get data out. First, the pull method: standard REST endpoints. Think of endpoints like visitors and venues. You can write a script to call these endpoints on a schedule, pull down all the visitor data from the last twenty-four hours, and load it into your data warehouse for analysis. This is your go-to for business intelligence, for building those big-picture dashboards in Power BI or Tableau.

But the really exciting part is the push method: Webhooks. This is for real-time. You set up a listener endpoint on your side, and the moment a guest authenticates on your WiFi, we send you a JSON payload with all their details — name, email, which venue they're in, their visit count, and even the authentication method they used, whether that was a registration form, social login, or something else. It's near-instant. This is what unlocks immediate, personalised engagement. It's the difference between sending a marketing email tomorrow, and sending a welcome back notification with a unique offer the second a loyal customer walks through your door.

Let me talk about the data fields you get. The Webhook payload is structured into four main objects. The client object gives you the MAC address and user agent. The company and venue objects give you the identifiers and geo-coordinates of the specific location. The session object gives you the authentication timestamp. And the user object is where the gold is: first name, last name, email, gender, date of birth, mobile number, postcode, and a visit count per venue showing the first and last visit dates. You can also capture custom fields from your splash page registration form, so if you ask guests for their loyalty programme number or their room number at a hotel, that comes through too.

Now, in version one point seven of the API, there's an important improvement worth noting. The unsubscribed field now clearly distinguishes between users who actively opted out of marketing after previously being subscribed, versus those who simply never opted in. This is critical for GDPR compliance and for accurate segmentation. You don't want to treat a lapsed subscriber the same way as someone who was never in your marketing funnel.

Let's talk about the integration patterns in more detail. For the REST API pull pattern, your typical workflow is a scheduled script, perhaps in Python or Node.js, that runs nightly. It authenticates with your API key, queries the visitors endpoint for each venue, transforms the data into your required format, and loads it into a central database. This is a classic ETL process. For a multi-site operator, you'd iterate through your venue IDs and aggregate the data centrally.

For the Webhook push pattern, the architecture is slightly different. You need a publicly accessible, SSL-secured endpoint. A serverless function is ideal here — AWS Lambda, Azure Functions, or Google Cloud Functions. It's cost-effective, scales automatically, and handles the concurrency you'd see at a busy venue. When the function receives the POST request from Purple, it should parse the JSON, perform its business logic — perhaps a CRM lookup or a loyalty check — and return a two hundred OK response as quickly as possible.

This brings me to the most important implementation requirement: your listener must respond within ten seconds. If it doesn't, Purple will requeue the request and retry after three hours. Persistent failures will cause the Webhook to be automatically disabled for security reasons. So keep your listener lean. Do the minimum processing needed to return a fast response, and if you need to do heavy processing, push the event onto an internal queue and process it asynchronously.

Now let's look at some real-world scenarios to make this concrete.

Consider a two-hundred-room hotel. They want to automatically enrol new WiFi guests into a welcome email journey in their marketing platform. The solution is straightforward: configure a Webhook, build a simple serverless listener, and when a new user's data arrives, check if they already exist in the marketing platform. If not, add them and trigger the welcome journey. The hotel can also use the visit count field to distinguish first-time visitors from returning guests and tailor the communication accordingly. A returning guest might receive a loyalty reward offer rather than a generic welcome.

Now consider a national retail chain with fifty stores. They want a central dashboard showing foot traffic trends across all locations. Here, the REST API pull pattern is the right choice. A nightly script queries the visitors endpoint for each of the fifty venues, aggregates the data, and loads it into a data warehouse. The analytics team then builds their dashboards on top of this. They can see which stores have the highest new visitor rates, which have the best returning visitor ratios, and how dwell times correlate with sales performance.

Let me now cover some common pitfalls and how to avoid them.

The first pitfall is duplicate event handling. A single guest visit can trigger multiple authentication events — for example, if they let their phone screen lock and it reconnects, or if they roam between access points. Your listener must be idempotent. Before taking an action like sending an email, check whether you've already processed an event for that user today.

The second pitfall is not validating your listener URL before going live. Purple requires you to validate the endpoint in the portal before it can receive data. Make sure your listener is live and returning the correct wifiWebhookListener header before you attach it to a LogicFlow.

The third pitfall is ignoring the subscription status. Always check the unsubscribed field before adding a user to a marketing list. Sending marketing communications to someone who has opted out is a GDPR violation with significant consequences.

Now for a rapid-fire question and answer session.

Can I sync this with my custom-built CRM? Yes. If your CRM has an API, you can use a Webhook listener as the middleware to format the Purple data and push it into your system. The IDs returned in the Webhook payload match those in the REST API, so you can also make follow-up calls to get additional detail if needed.

How do I handle a user who visits multiple sites in my estate? The API provides visit counts per venue ID, so you can easily track a customer's journey across your entire estate and build a comprehensive cross-site profile.

Is there a limit on how many Webhook URLs I can configure? No. You can validate and use as many listener URLs as you need, which is useful if different teams or systems need to receive the same event data.

What happens if my listener goes down for maintenance? Purple will retry failed deliveries, so you may receive a backlog of events when your listener comes back online. Your listener needs to handle this gracefully, processing events that may arrive out of chronological order.

To summarise everything we've covered today, the Purple Portal API is your key to unlocking the immense value within your guest WiFi data. Use the REST API to pull data for reporting and analytics. Use Webhooks to push data in real-time for immediate, personalised customer engagement. Remember the key principle: push for real-time, pull for reports.

Your next step is to review the API documentation in our support portal. If you have an Engage licence, generate an API key and start exploring with Postman. Build a simple Webhook listener. See the data flow in. That's the moment the potential of this tool becomes crystal clear.

Thank you for listening to the Purple Technical Briefing. If you'd like to speak with one of our solutions architects about your specific integration requirements, visit purple dot ai and book a demo. Until next time.

Résumé analytique

Pour les responsables informatiques de sites multiples (hôtels, chaînes de magasins, stades et centres de conférence), le réseau WiFi invité est bien plus qu'un simple service. Il s'agit d'une source riche et continuellement renouvelée de données first-party capables de générer un impact commercial mesurable sur le marketing, les opérations et l'expérience client. La Purple Portal API fournit l'interface programmatique nécessaire pour libérer cette valeur à grande échelle. Elle permet aux équipes techniques d'aller au-delà des tableaux de bord d'analyse intégrés et de créer des intégrations robustes et automatisées qui alimentent les données des visiteurs conformes au GDPR directement dans les systèmes métiers centraux, des plateformes CRM et outils de marketing automation aux programmes de fidélité et entrepôts de Business Intelligence.

Ce guide est une référence pratique et exploitable pour les architectes de solutions, les responsables informatiques et les développeurs seniors. Il détaille le modèle d'authentification, les endpoints disponibles, les modèles d'intégration et les scénarios de déploiement en conditions réelles qui démontrent comment la Purple WiFi API peut transformer un déploiement WiFi d'un centre de coûts en un atout stratégique de données. Que vous évaluiez l'API pour la première fois ou que vous planifiiez une intégration de niveau production, ce document fournit les bases techniques et les cadres de décision dont vous avez besoin pour avancer en toute confiance.

Analyse technique approfondie

Authentification et versioning de l'API

La Purple Portal API utilise l'authentification par clé API, un modèle simple et sécurisé parfaitement adapté aux intégrations de serveur à serveur. Contrairement aux flux OAuth 2.0, qui nécessitent des cycles d'échange et de rafraîchissement de jetons, l'authentification par clé API implique l'inclusion d'un secret statique dans les en-têtes de requête. Cette simplicité réduit la charge d'intégration sans compromettre la sécurité, à condition que la clé soit stockée de manière sécurisée et renouvelée périodiquement dans le cadre de votre politique standard de gestion des identifiants.

La version de production actuelle est la v1.7, qui a introduit plusieurs améliorations importantes par rapport à la v1.6.2. Plus important encore, la propriété unsubscribed dans l'objet de données utilisateur distingue désormais clairement un utilisateur qui s'est activement désinscrit du marketing après avoir été abonné, d'un utilisateur qui ne s'est jamais abonné. Cette distinction est essentielle pour la conformité au GDPR et pour une segmentation précise de l'audience. De plus, les endpoints Visitors et Venues renvoient désormais une réponse HTTP 200 OK lorsqu'aucune donnée n'est trouvée, plutôt qu'une erreur 404 Not Found, qui causait auparavant de la confusion dans la logique de supervision et de gestion des erreurs.

Endpoints disponibles

L'API Portal Company expose trois catégories principales d'endpoints avec lesquelles les équipes informatiques interagiront régulièrement.

Endpoint	Méthode	Objectif
`/visitors`	GET	Récupérer les profils des visiteurs invités, y compris les données de contact, les données démographiques et l'historique des visites
`/venues`	GET	Récupérer les données au niveau du site et les métadonnées de configuration
`/unsubscribes`	GET	Récupérer une liste d'utilisateurs qui se sont désinscrits des communications marketing

Tous les endpoints renvoient des données au format JSON. L'endpoint visitors est le plus couramment utilisé, car il expose toute la richesse des données de profil invité collectées lors du parcours d'authentification du Captive Portal. Cela inclut le prénom, le nom, l'adresse e-mail, le sexe, la date de naissance, le numéro de mobile, le code postal, le fournisseur d'authentification (par ex., formulaire d'inscription, connexion sociale), le nombre de visites par site et tout champ personnalisé configuré sur la page d'accueil.

Limites de requêtes

Un avantage architectural clé de la Purple Portal API est qu'il n'y a aucune limite de requêtes. La plateforme est conçue pour supporter n'importe quel volume de requêtes ou de transactions, ce qui la rend adaptée aux déploiements à grande échelle où les scripts peuvent avoir besoin de traiter des milliers d'enregistrements de sites ou des millions de profils de visiteurs. Cela supprime une contrainte courante qui complique la conception de l'intégration avec d'autres plateformes et élimine le besoin de limitation des requêtes (throttling) ou de logique de back-off dans votre code client.

Modèles d'intégration : Pull vs Push

La Purple WiFi API prend en charge deux modèles d'intégration fondamentalement différents, chacun adapté à des cas d'usage distincts. Comprendre quel modèle appliquer dans un scénario donné est la décision architecturale la plus importante que vous prendrez.

Le modèle pull de l'API REST implique que votre système effectue des requêtes à la demande ou planifiées vers les endpoints de l'API pour récupérer des données. C'est l'approche correcte pour le traitement par lots (batch), le reporting et la Business Intelligence. Un script ETL nocturne qui extrait toutes les données des visiteurs de la veille et les charge dans un entrepôt de données en est un exemple classique. Le modèle pull vous donne un contrôle total sur le moment et la quantité de données que vous récupérez.

Le modèle push par Webhook implique que Purple envoie des données à votre système au moment où un événement spécifique se produit, plus précisément lorsqu'un invité s'authentifie sur le réseau WiFi. Votre système doit exposer un endpoint HTTP accessible publiquement et sécurisé par SSL (un « listener ») capable de recevoir et de traiter ces payloads POST JSON. Le modèle Webhook est le choix approprié pour tout cas d'usage nécessitant des données en temps quasi réel, comme le déclenchement d'un message de bienvenue personnalisé, la mise à jour du statut « dernière vue » d'un client dans un CRM, ou la notification à un responsable hôtelier de l'arrivée d'un invité VIP.

Structure du payload Webhook

Le payload JSON fourni par un Webhook Purple est structuré en quatre objets principaux, chacun apportant une dimension contextuelle différente à l'événement d'authentification.

Objet	Champs clés	Description
`client`	`mac`, `userAgent`	Identifiants au niveau de l'appareil
`company`	`id`, `name`, `uniqId`	Détails du compte de votre entreprise
`venue`	`id`, `name`, `latitude`, `longitude`	L'emplacement spécifique où l'authentification a eu lieu
`session`	`authenticationTime`	Horodatage ISO 8601 de l'événement d'authentification
`user`	`email`, `firstName`, `lastName`, `gender`, `provider`, `visitCountForVenues`, `customFields`	Données complètes du profil invité

L'objet user.visitCountForVenues est particulièrement précieux pour les opérateurs multi-sites. Il fournit un nombre de visites par site ainsi que les horodatages firstVisit et lastVisit, vous permettant d'identifier les nouveaux visiteurs par rapport aux clients fidèles au moment de l'authentification, sans aucun appel API supplémentaire.

Guide d'implémentation

Prérequis et configuration

L'accès à la Portal API nécessite une licence Engage. Une fois la licence obtenue, générez votre clé API depuis les paramètres du portail Purple. Pour le développement initial et les tests, Postman est l'outil recommandé ; Purple fournit un guide de configuration dédié pour paramétrer les variables d'environnement et les en-têtes de requête corrects. Un fichier de démonstration PHP est également disponible pour les équipes préférant un point de départ de script côté serveur.

Configuration d'une intégration Webhook

Le déploiement d'une intégration Webhook implique cinq étapes. Premièrement, créez et déployez votre endpoint listener sur une URL accessible publiquement et sécurisée par SSL. Une fonction serverless (AWS Lambda, Azure Functions ou Google Cloud Functions) est un choix architectural judicieux : elle évolue automatiquement, engendre des coûts minimes à faible volume et gère les requêtes simultanées sans configuration. Deuxièmement, validez l'URL du listener dans le portail Purple en naviguant vers Management > Venues > Webhooks. Purple enverra une requête de test pour confirmer que l'endpoint est joignable et renvoie l'en-tête wifiWebhookListener: 1 requis. Troisièmement, créez ou modifiez un LogicFlow dans le portail et ajoutez un nœud d'action Webhook, en sélectionnant votre URL validée. Quatrièmement, assurez-vous que le LogicFlow est défini sur le statut « Online ». Cinquièmement, attachez le LogicFlow au parcours d'accès pertinent. À partir de ce moment, chaque authentification d'invité sur ce parcours déclenchera votre Webhook.

Gestion des tentatives et de l'idempotence

Votre listener doit être conçu pour gérer les réalités des systèmes distribués. Purple réessaiera de livrer un Webhook échoué après trois heures si votre listener ne répond pas (le délai d'attente dépasse 10 secondes) ou renvoie un statut d'erreur. Cela signifie que votre listener peut recevoir le même événement plusieurs fois. De plus, une seule visite d'un invité peut déclencher plusieurs événements d'authentification, par exemple, lorsqu'un appareil se reconnecte après le verrouillage de l'écran, ou lorsqu'un utilisateur se déplace entre les points d'accès. Votre logique de traitement doit donc être idempotente : appliquer le même événement deux fois doit produire le même résultat que de l'appliquer une seule fois. Un modèle d'implémentation courant consiste à vérifier si une action (comme l'envoi d'un e-mail de bienvenue) a déjà été effectuée pour un ID utilisateur donné dans une fenêtre de temps définie avant de l'exécuter.

Bonnes pratiques

Plusieurs principes doivent guider tout déploiement en production de la Purple Portal API. Déployez toujours sur la dernière version de l'API (v1.7) et mettez à jour vos chemins d'URL ainsi que votre logique d'analyse des réponses lors de la sortie de nouvelles versions. Traitez votre clé API comme un identifiant sensible : stockez-la dans un gestionnaire de secrets (tel qu'AWS Secrets Manager ou Azure Key Vault) plutôt que dans le code source ou les variables d'environnement sur des systèmes partagés. Pour les listeners Webhook, implémentez une journalisation structurée de chaque payload entrant et de chaque réponse pour faciliter le débogage et les pistes d'audit. Respectez les champs unsubscribed et unsubscribedDate dans l'objet utilisateur ; le traitement d'actions marketing à l'encontre d'utilisateurs désinscrits constitue une violation du GDPR. Enfin, testez votre intégration face à l'ensemble des cas limites : utilisateurs sans adresse e-mail, utilisateurs avec des champs personnalisés nuls, et événements d'authentification arrivant dans le désordre chronologique.

Dépannage et atténuation des risques

Le mode de défaillance le plus courant dans une intégration Webhook est un listener lent ou indisponible. Si l'endpoint échoue systématiquement à répondre dans les 10 secondes, Purple désactivera automatiquement le Webhook après une période prolongée de non-réponse, nécessitant une re-vérification manuelle dans le portail. Pour atténuer ce risque, implémentez un endpoint de vérification d'état sur le même serveur que votre listener et incluez-le dans la supervision de votre infrastructure. Assurez-vous que votre listener n'effectue qu'un traitement synchrone minimal avant de renvoyer une réponse 200 OK ; déchargez tout calcul lourd ou appel API en aval vers une file d'attente asynchrone.

Pour les intégrations d'API REST, le risque principal est l'obsolescence des données dans les systèmes en aval si la tâche pull planifiée échoue silencieusement. Implémentez des alertes sur vos scripts ETL pour informer l'équipe des opérations si une exécution échoue ou ne produit aucun résultat de manière inattendue. Lors de la migration de l'API v1.6.2 vers la v1.7, auditez tout le code qui fait référence au champ unsubscribed et à l'endpoint Unsubscribes, car le nom de la propriété a été corrigé de unsubcribers à unsubscribers dans la v1.7.

ROI et impact commercial

L'analyse de rentabilité de l'intégration avec la Purple Portal API est bien établie dans de multiples secteurs verticaux. Dans l'hôtellerie, les hôtels utilisant des intégrations CRM déclenchées par Webhook signalent des améliorations significatives des taux d'ouverture des e-mails pour les communications personnalisées par rapport aux campagnes de diffusion génériques, car le message est délivré au moment de pertinence maximale : lorsque l'invité est physiquement sur place. Dans le commerce de détail, la connexion des données du WiFi invité à un programme de fidélité permet aux opérateurs d'identifier et de récompenser les visiteurs très fréquents, augmentant ainsi les dépenses moyennes et les taux de visites répétées. Pour les grands lieux publics et les centres de conférence, les analyses basées sur l'API fournissent les données granulaires de fréquentation nécessaires pour justifier les valorisations de sponsoring et optimiser le placement des concessions.

L'absence de limites de requêtes sur la Purple WiFi API signifie que le coût d'intégration évolue avec votre infrastructure, et non avec le volume de données que vous traitez. Pour une chaîne de magasins nationale traitant des centaines de milliers d'authentifications quotidiennes, il s'agit d'un avantage matériel par rapport aux plateformes qui facturent par appel API ou imposent des plafonds de débit. Le coût total de possession pour une intégration bien architecturée de la Purple API se résume donc principalement au coût de développement initial et au coût d'infrastructure continu du listener, qui sont tous deux généralement amortis dès le premier trimestre grâce à la seule amélioration des taux de conversion marketing.

Études de cas

Étude de cas 1 : Hôtellerie — Whitbread Group

Whitbread, la plus grande entreprise d'hôtellerie et de restauration du Royaume-Uni, exploite des milliers de points d'accès WiFi invités à travers son parc Premier Inn et ses restaurants. En intégrant la Purple Portal API à sa plateforme CRM, le groupe a pu créer un profil invité unifié combinant les données de réservation en ligne avec le comportement de visite physique capturé sur le Captive Portal du WiFi. L'intégration Webhook se déclenche à chaque authentification d'invité, enrichissant l'enregistrement CRM avec le dernier horodatage de visite, l'emplacement du site et les informations sur l'appareil. Cela permet à l'équipe marketing de segmenter les audiences par récence, fréquence et emplacement, et de déclencher des campagnes de réengagement hautement personnalisées. Le principal résultat technique a été une réduction du temps entre l'arrivée d'un invité et son entrée dans un parcours marketing actif, passant de 24 heures (sous l'ancien modèle de polling par lots) à moins de 60 secondes.

Étude de cas 2 : Retail — Détaillant de mode multi-sites

Un détaillant de mode national comptant plus de 80 magasins a déployé la Purple Portal API pour combler une lacune critique dans sa stratégie de données clients : il disposait de solides données e-commerce, mais n'avait pratiquement aucune visibilité sur le comportement des visiteurs en magasin. En connectant l'API du WiFi invité Purple à leur entrepôt de données existant via un processus ETL nocturne, ils ont construit pour la première fois une vue client omnicanale. L'endpoint /visitors a été interrogé pour chaque magasin chaque nuit, et les données ont été jointes aux enregistrements de transactions e-commerce en utilisant l'adresse e-mail comme clé commune. En l'espace de trois mois, l'équipe d'analyse a identifié que les clients qui se connectaient au WiFi en magasin avaient une valeur moyenne de commande supérieure de 34 % lors de leur prochain achat en ligne, fournissant un argument commercial convaincant pour investir davantage dans l'expérience numérique en magasin. L'intégration n'a nécessité aucune modification de l'infrastructure e-commerce existante, démontrant la nature sans friction du modèle pull de l'API REST.

Étude de cas 3 : Événementiel — Centre de conférence

Un grand centre de conférence au Royaume-Uni a utilisé la Purple Portal API pour fournir aux sponsors des données de fréquentation vérifiées pour la première fois. Auparavant, les rapports des sponsors reposaient sur des comptages manuels et des scans de badges, qui étaient laborieux et imprécis. En exposant des comptages de visiteurs agrégés et anonymisés par zone (mappés aux ID de site dans la plateforme Purple) via l'API, l'équipe événementielle a pu fournir aux sponsors des tableaux de bord en temps réel montrant le temps de séjour et le volume de visiteurs dans les zones sponsorisées. Les données étaient extraites via l'API REST toutes les 15 minutes pendant les événements et affichées sur un portail sponsor sur mesure. Cette capacité a directement contribué à une augmentation de 22 % des taux de renouvellement de sponsoring la première année, car les sponsors pouvaient désormais quantifier la portée de leurs activations avec des données first-party vérifiées.

Termes clés et définitions

Webhook

An automated mechanism where a server sends a real-time data notification (a push) to another application when a specific event occurs, via an HTTP POST request.

In the Purple context, a Webhook sends a JSON payload with visitor data to your system the moment a guest authenticates on the WiFi network. This is critical for real-time marketing and CRM updates.

REST API

A standardized architectural style for building web services that allows one system to request (or pull) data from another using standard HTTP methods such as GET and POST.

IT teams use the Purple REST API to write scripts that pull bulk visitor and venue data for analysis in business intelligence tools like Power BI or Tableau.

API Key Authentication

A security model where access to an API is granted by providing a unique secret token (the key) with each request, typically in the HTTP Authorization header.

This is simpler than OAuth and ideal for server-to-server integrations. Your scripts must include the valid API Key in the request headers to access Purple's data.

Idempotency

A property of an operation meaning that it can be applied multiple times without changing the result beyond the initial application.

Your Webhook listener should be idempotent. If it receives the same authentication event twice (which can happen due to retries or device reconnections), it should not, for example, send two welcome emails.

JSON (JavaScript Object Notation)

A lightweight, text-based format for data interchange that is easy for humans to read and for machines to parse and generate.

The Purple API and Webhooks deliver all data in JSON format. Your application will need to parse this JSON to extract fields like email, name, and visit count.

LogicFlow

Purple's visual, drag-and-drop tool for creating automated marketing and engagement workflows that can trigger actions based on visitor behaviour and demographics.

You use LogicFlow to define the guest journey. It is where you attach your Webhook, telling the system to fire it when a user reaches the 'Online' state of their access journey.

Captive Portal

The web page that a user sees and must interact with before being granted access to a public WiFi network, typically requiring authentication or data capture.

The Purple platform powers the captive portal, and the data entered by the user on this page (e.g., name, email, custom fields) is what becomes available via the Portal API.

GDPR (General Data Protection Regulation)

A comprehensive data privacy law in the European Union that governs the collection, processing, and storage of personal data of EU residents.

The Purple API provides the tools to build GDPR-compliant integrations, such as respecting the unsubscribed status of a user and enabling data export for subject access requests. The v1.7 API update specifically improved the clarity of the unsubscribed field to support compliance.

ETL (Extract, Transform, Load)

A data integration process that involves extracting data from a source system, transforming it into the required format, and loading it into a destination system such as a data warehouse.

The REST API pull pattern is typically implemented as an ETL process, where data is extracted from Purple's /visitors endpoint, transformed to match the destination schema, and loaded into a CRM or data warehouse.

Études de cas

A 200-room hotel wants to automatically add new guest WiFi users to their Salesforce Marketing Cloud journey and send a welcome email.

In the Purple Portal, validate a new Webhook URL pointing to a secure endpoint (e.g., a serverless function on AWS Lambda). 2. Create an 'Online' LogicFlow that includes the Webhook node, configured to use the validated URL. 3. Assign this LogicFlow to the hotel's guest WiFi access journey. 4. The serverless function receives the JSON payload on guest authentication, extracts the user's email and name, and makes an API call to Salesforce Marketing Cloud to add the user to the 'New Guest' journey. 5. The function returns a 200 OK response to Purple within the 10-second timeout window.

Notes de mise en œuvre : This solution correctly uses the real-time Webhook pattern, which is ideal for immediate actions like sending a welcome email. Using a serverless function is a cost-effective and scalable way to host the listener endpoint. An alternative would be to poll the /visitors API endpoint, but this would introduce a delay of up to 24 hours and be significantly less efficient for a real-time requirement.

A retail chain with 50 stores wants to build a central dashboard in Power BI to analyze visitor trends across all locations.

Create a script (e.g., in Python) that runs on a nightly schedule. 2. The script authenticates to the Purple Portal API using the company's API key. 3. It iterates through each of the 50 venue IDs, making a call to the /visitors endpoint for each to retrieve all visitor data from the previous day. 4. The script transforms and loads this data into a central data warehouse (e.g., Azure SQL or BigQuery). 5. Power BI is connected to the data warehouse to create the cross-venue analytics dashboard.

Notes de mise en œuvre : This is a classic ETL (Extract, Transform, Load) process and is the correct use of the REST API's polling pattern. It is suitable for non-real-time, large-scale data aggregation for business intelligence. Using a central data warehouse is a best practice for performance and scalability when dealing with data from multiple sources. The absence of rate limits on the Purple API means the script can process all 50 venues without throttling concerns.

Analyse de scénario

Q1. A stadium wants to identify VIP season ticket holders when they connect to the WiFi and send a notification to the nearest hospitality manager's dashboard. Which integration pattern should they use and why?

💡 Astuce :Consider the required speed of the notification and whether the action is triggered by an event.

Afficher l'approche recommandée

They should use the Webhook (push) pattern. This is a real-time requirement: when the VIP connects, a Webhook fires immediately to a service that looks up the user's email or MAC address against the season ticket holder database. If a match is found, it pushes a notification to the relevant hospitality dashboard. A REST API (pull) pattern would be too slow, as it relies on periodic polling and could introduce delays of minutes or hours.

Q2. You are tasked with creating a daily report of the top 10 most visited venues in your national chain of coffee shops. How would you retrieve the necessary data from Purple?

💡 Astuce :Is this a real-time or a batch reporting requirement? What endpoint would you query?

Afficher l'approche recommandée

This is a batch reporting task, so the REST API (pull) pattern is appropriate. A scheduled script would run daily, query the /visitors endpoint for each venue, aggregate the visit counts for the previous day, and then calculate the top 10. There is no need for the near-instant notification provided by Webhooks. The absence of rate limits means all venues can be queried in a single script run without throttling concerns.

Q3. Your Webhook listener endpoint is failing. You check the logs and see a timeout error. What is the most likely cause according to Purple's documentation, and what are the two immediate consequences?

💡 Astuce :Think about the performance requirements of a listener and what Purple does when it cannot deliver a payload.

Afficher l'approche recommandée

The most likely cause is that the listener is taking longer than 10 seconds to process the incoming JSON payload and return a 200 OK response. The two immediate consequences are: (1) Purple will stop trying to send the current request and will requeue it for a retry attempt in 3 hours, meaning data delivery is delayed; and (2) if this continues for a prolonged period, Purple will automatically disable the Webhook entirely, requiring manual re-verification in the portal before it can be re-enabled.

Points clés à retenir

✓The Purple Portal API provides programmatic access to guest WiFi data using simple API Key authentication, with no rate limits.
✓It requires an Engage license and currently operates on version v1.7, which improved GDPR compliance through clearer unsubscribed status handling.
✓Use the REST API (pull) for batch data exports, ETL processes, and analytics dashboards.
✓Use Webhooks (push) for real-time, event-driven actions like CRM syncs, personalised messaging, and loyalty triggers.
✓Webhook listeners must be SSL-secured, respond within 10 seconds, and be designed to handle duplicate events idempotently.
✓Key use cases span hospitality (real-time CRM enrichment), retail (cross-channel analytics), and events (verified footfall data for sponsors).
✓The API enables organizations to transform their WiFi infrastructure from a cost centre into a strategic data asset with a clear, measurable ROI.