Purple Portal API: O Que Pode Fazer Com Ela

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 read📝 2,212 words🔧 2 examples❓ 3 questions📚 9 key terms

🎧 Listen to this Guide

View Transcript

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.

Resumo Executivo

Para os líderes de TI em locais com múltiplos espaços — hotéis, cadeias de retalho, estádios e centros de conferências — a rede WiFi para convidados é mais do que uma simples comodidade. É uma fonte rica e continuamente reabastecida de dados primários (first-party data) que pode impulsionar um impacto comercial mensurável no marketing, nas operações e na experiência do cliente. A Purple Portal API fornece a interface programática necessária para desbloquear este valor à escala. Permite que as equipas técnicas vão além dos painéis de análise integrados e construam integrações robustas e automatizadas que alimentam dados de visitantes em conformidade com o GDPR diretamente nos principais sistemas de negócios, desde plataformas de CRM e ferramentas de automação de marketing até programas de fidelização e armazéns de dados de business intelligence.

Este guia é uma referência prática e acionável para arquitetos de soluções, gestores de TI e programadores seniores. Detalha o modelo de autenticação, os endpoints disponíveis, os padrões de integração e os cenários de implementação no mundo real que demonstram como a Purple WiFi API pode transformar uma implementação de WiFi de um centro de custos num ativo de dados estratégico. Quer esteja a avaliar a API pela primeira vez ou a planear uma integração de nível de produção, este documento fornece a base técnica e as estruturas de decisão de que necessita para avançar com confiança.

Análise Técnica Aprofundada

Autenticação e Versionamento da API

A Purple Portal API utiliza a autenticação por API Key, um modelo simples e seguro, muito adequado para integrações servidor-a-servidor. Ao contrário dos fluxos OAuth 2.0, que exigem a troca de tokens e ciclos de atualização, a autenticação por API Key envolve a inclusão de um segredo estático nos cabeçalhos do pedido. Esta simplicidade reduz a sobrecarga de integração sem comprometer a segurança, desde que a chave seja armazenada de forma segura e rodada periodicamente como parte da sua política padrão de gestão de credenciais.

A versão de produção atual é a v1.7, que introduziu várias melhorias importantes em relação à v1.6.2. Mais significativamente, a propriedade unsubscribed no objeto de dados do utilizador distingue agora claramente entre um utilizador que optou ativamente por não receber marketing após ter subscrito anteriormente, e um utilizador que nunca subscreveu. Esta distinção é fundamental para a conformidade com o GDPR e para uma segmentação precisa do público. Além disso, os endpoints Visitors e Venues devolvem agora uma resposta HTTP 200 OK quando não são encontrados dados, em vez de um 404 Not Found, o que anteriormente causava confusão na lógica de monitorização e tratamento de erros.

Endpoints Disponíveis

A API da Portal Company expõe três categorias principais de endpoints com as quais as equipas de TI irão interagir regularmente.

Endpoint	Método	Objetivo
`/visitors`	GET	Obter perfis de visitantes convidados, incluindo dados de contacto, dados demográficos e histórico de visitas
`/venues`	GET	Obter dados ao nível do local e metadados de configuração
`/unsubscribes`	GET	Obter uma lista de utilizadores que optaram por não receber comunicações de marketing

Todos os endpoints devolvem dados no formato JSON. O endpoint visitors é o mais utilizado, uma vez que expõe toda a riqueza dos dados de perfil do convidado recolhidos durante a jornada de autenticação no Captive Portal. Isto inclui o primeiro nome, apelido, endereço de e-mail, género, data de nascimento, número de telemóvel, código postal, fornecedor de autenticação (por exemplo, formulário de registo, login social), contagem de visitas por local e quaisquer campos personalizados configurados na splash page.

Limites de Taxa

Uma das principais vantagens arquitetónicas da Purple Portal API é que não existem limites de taxa (rate limits). A plataforma foi concebida para suportar qualquer volume de pedidos ou transações, tornando-a adequada para implementações em grande escala, onde os scripts podem necessitar de processar milhares de registos de locais ou milhões de perfis de visitantes. Isto remove uma restrição comum que complica o design de integração com outras plataformas e elimina a necessidade de limitação de pedidos (throttling) ou lógica de recuo (back-off) no código do seu cliente.

Padrões de Integração: Pull vs. Push

A Purple WiFi API suporta dois padrões de integração fundamentalmente diferentes, cada um adequado a diferentes casos de uso. Compreender qual o padrão a aplicar num determinado cenário é a decisão arquitetónica mais importante que irá tomar.

O padrão pull da REST API envolve o seu sistema a fazer pedidos a pedido ou programados aos endpoints da API para obter dados. Esta é a abordagem correta para processamento em lote (batch), relatórios e business intelligence. Um script ETL noturno que extrai todos os dados de visitantes do dia anterior e os carrega num data warehouse é um exemplo canónico. O padrão pull dá-lhe controlo total sobre quando e a quantidade de dados que obtém.

O padrão push de Webhook envolve a Purple a enviar dados para o seu sistema no momento em que ocorre um evento específico — concretamente, quando um convidado se autentica na rede WiFi. O seu sistema deve expor um endpoint HTTP publicamente acessível e protegido por SSL (um 'listener') que possa receber e processar estes payloads JSON POST. O padrão Webhook é a escolha correta para qualquer caso de uso que exija dados quase em tempo real, como acionar uma mensagem de boas-vindas personalizada, atualizar o estado da 'última vez visto' de um cliente num CRM ou notificar um gestor de hospitalidade de que um convidado VIP chegou.

Estrutura do Payload do Webhook

O payload JSON entregue por um Webhook da Purple está estruturado em quatro objetos principais, cada um fornecendo uma dimensão diferente de contexto para o evento de autenticação.

Objeto	Campos Principais	Descrição
`client`	`mac`, `userAgent`	Identificadores ao nível do dispositivo
`company`	`id`, `name`, `uniqId`	Detalhes da conta da sua empresa
`venue`	`id`, `name`, `latitude`, `longitude`	O local específico onde a autenticação ocorreu
`session`	`authenticationTime`	Timestamp ISO 8601 do evento de autenticação
`user`	`email`, `firstName`, `lastName`, `gender`, `provider`, `visitCountForVenues`, `customFields`	Dados completos do perfil do convidado

O objeto user.visitCountForVenues é particularmente valioso para operadores com múltiplos locais. Fornece uma contagem de visitas por local, juntamente com os timestamps firstVisit e lastVisit, permitindo-lhe identificar visitantes pela primeira vez em oposição a clientes fiéis que regressam no momento da autenticação — sem quaisquer chamadas adicionais à API.

Guia de Implementação

Pré-requisitos e Configuração

O acesso à Portal API requer uma licença Engage. Uma vez licenciado, gere a sua API Key a partir das definições do portal da Purple. Para desenvolvimento e testes iniciais, o Postman é a ferramenta recomendada; a Purple fornece um guia de configuração dedicado para configurar as variáveis de ambiente e os cabeçalhos de pedido corretos. Está também disponível um ficheiro de demonstração em PHP para as equipas que preferem um ponto de partida de scripting do lado do servidor.

Configurar uma Integração de Webhook

A implementação de uma integração de Webhook envolve cinco passos. Primeiro, construa e implemente o seu endpoint listener num URL publicamente acessível e protegido por SSL. Uma função serverless (AWS Lambda, Azure Functions ou Google Cloud Functions) é uma escolha arquitetónica sólida: escala automaticamente, incorre num custo mínimo em volumes baixos e lida com pedidos simultâneos sem configuração. Segundo, valide o URL do listener no portal da Purple navegando para Management > Venues > Webhooks. A Purple enviará um pedido de teste para confirmar que o endpoint está acessível e devolve o cabeçalho wifiWebhookListener: 1 exigido. Terceiro, crie ou edite um LogicFlow no portal e adicione um Webhook Action Node, selecionando o seu URL validado. Quarto, certifique-se de que o LogicFlow está definido para o estado 'Online'. Quinto, anexe o LogicFlow à Access Journey relevante. A partir deste ponto, cada autenticação de convidado nessa jornada irá acionar o seu Webhook.

Tratamento de Repetições e Idempotência

O seu listener deve ser concebido para lidar com as realidades dos sistemas distribuídos. A Purple tentará novamente uma entrega de Webhook falhada após três horas se o seu listener não responder (o tempo limite excede 10 segundos) ou devolver um estado de erro. Isto significa que o seu listener pode receber o mesmo evento várias vezes. Além disso, uma única visita de um convidado pode acionar vários eventos de autenticação — por exemplo, quando um dispositivo se volta a ligar após o bloqueio do ecrã, ou quando um utilizador se desloca (roaming) entre pontos de acesso. A sua lógica de processamento deve, portanto, ser idempotente: aplicar o mesmo evento duas vezes deve produzir o mesmo resultado que aplicá-lo uma vez. Um padrão de implementação comum é verificar se uma ação (como enviar um e-mail de boas-vindas) já foi executada para um determinado ID de utilizador dentro de uma janela de tempo definida antes de a executar.

Melhores Práticas

Vários princípios devem orientar qualquer implementação de produção da Purple Portal API. Implemente sempre com base na versão mais recente da API (v1.7) e atualize os caminhos do seu URL e a lógica de análise de respostas quando forem lançadas novas versões. Trate a sua API Key como uma credencial sensível: armazene-a num gestor de segredos (como o AWS Secrets Manager ou o Azure Key Vault) em vez de no código-fonte ou em variáveis de ambiente em sistemas partilhados. Para os listeners de Webhook, implemente o registo estruturado (logging) de cada payload recebido e resposta para facilitar a depuração e as pistas de auditoria. Respeite os campos unsubscribed e unsubscribedDate no objeto do utilizador; o processamento de ações de marketing em utilizadores que optaram por não participar constitui uma violação do GDPR. Por fim, teste a sua integração em toda a gama de casos extremos (edge cases): utilizadores sem endereço de e-mail, utilizadores com campos personalizados nulos e eventos de autenticação que chegam fora da ordem cronológica.

Resolução de Problemas e Mitigação de Riscos

O modo de falha mais comum numa integração de Webhook é um listener lento ou indisponível. Se o endpoint falhar consistentemente em responder dentro de 10 segundos, a Purple desativará automaticamente o Webhook após um período prolongado de falta de resposta, exigindo uma nova verificação manual no portal. Para mitigar este risco, implemente um endpoint de verificação de estado (health check) no mesmo servidor que o seu listener e inclua-o na monitorização da sua infraestrutura. Certifique-se de que o seu listener executa apenas o processamento síncrono mínimo antes de devolver uma resposta 200 OK; descarregue qualquer computação pesada ou chamadas de API a jusante para uma fila assíncrona.

Para integrações de REST API, o risco principal é a desatualização de dados em sistemas a jusante se a tarefa de pull programada falhar silenciosamente. Implemente alertas nos seus scripts ETL para notificar a equipa de operações se uma execução falhar ou não produzir resultados inesperadamente. Ao migrar da API v1.6.2 para a v1.7, audite todo o código que faz referência ao campo unsubscribed e ao endpoint Unsubscribes, uma vez que o nome da propriedade foi corrigido de unsubcribers para unsubscribers na v1.7.

ROI e Impacto no Negócio

O business case para a integração com a Purple Portal API está bem estabelecido em vários setores verticais. Na hospitalidade, os hotéis que utilizam integrações de CRM acionadas por Webhook relatam melhorias significativas nas taxas de abertura de e-mails para comunicações personalizadas em comparação com campanhas de transmissão genéricas, porque a mensagem é entregue no momento de máxima relevância — quando o convidado está fisicamente no local. No retalho, a ligação dos dados de WiFi dos convidados a um programa de fidelização permite aos operadores identificar e recompensar visitantes de alta frequência, aumentando a despesa média e as taxas de repetição de visitas. Para grandes locais públicos e centros de conferências, as análises baseadas em API fornecem os dados granulares de tráfego de pessoas (footfall) necessários para justificar as avaliações de patrocínios e otimizar a colocação de concessões.

A ausência de limites de taxa na Purple WiFi API significa que o custo da integração escala com a sua infraestrutura, e não com o volume de dados que processa. Para uma cadeia de retalho nacional que processa centenas de milhares de autenticações diárias, esta é uma vantagem material sobre as plataformas que cobram por chamada de API ou impõem limites de taxa de transferência (throughput). O custo total de propriedade para uma integração da Purple API bem arquitetada é, portanto, principalmente o custo de desenvolvimento único e o custo contínuo de infraestrutura do listener, ambos tipicamente recuperados no primeiro trimestre apenas através da melhoria das taxas de conversão de marketing.

Casos de Estudo

Caso de Estudo 1: Hospitalidade — Whitbread Group

A Whitbread, a maior empresa de hotéis e restaurantes do Reino Unido, opera milhares de pontos de acesso WiFi para convidados em toda a sua propriedade Premier Inn e restaurantes. Ao integrar a Purple Portal API com a sua plataforma de CRM, o grupo conseguiu construir um perfil de convidado unificado que combinava dados de reservas online com o comportamento de visitas físicas capturado no Captive Portal do WiFi. A integração do Webhook é acionada em cada autenticação de convidado, enriquecendo o registo do CRM com o timestamp da visita mais recente, a localização do espaço e as informações do dispositivo. Isto permite à equipa de marketing segmentar os públicos por recência, frequência e localização, e acionar campanhas de re-envolvimento altamente personalizadas. O principal resultado técnico foi uma redução no tempo entre a chegada de um convidado e a sua entrada numa jornada de marketing ativa de 24 horas (sob o modelo anterior de batch-polling) para menos de 60 segundos.

Caso de Estudo 2: Retalho — Retalhista de Moda com Múltiplos Locais

Um retalhista de moda nacional com mais de 80 lojas implementou a Purple Portal API para colmatar uma lacuna crítica na sua estratégia de dados de clientes: tinham dados de e-commerce fortes, mas praticamente nenhuma perceção sobre o comportamento dos visitantes nas lojas. Ao ligar a Purple WiFi API para convidados ao seu data warehouse existente através de um processo ETL noturno, construíram pela primeira vez uma visão do cliente cross-channel. O endpoint /visitors foi consultado para cada loja todas as noites, e os dados foram associados aos registos de transações de e-commerce utilizando o endereço de e-mail como chave comum. Em três meses, a equipa de análise identificou que os clientes que se ligavam ao WiFi na loja tinham um valor médio de encomenda 34% superior na sua próxima compra online, fornecendo um business case convincente para um maior investimento na experiência digital na loja. A integração não exigiu alterações à infraestrutura de e-commerce existente, demonstrando a natureza de baixo atrito do padrão pull da REST API.

Caso de Estudo 3: Eventos — Centro de Conferências

Um grande centro de conferências no Reino Unido utilizou a Purple Portal API para fornecer aos patrocinadores dados verificados de tráfego de pessoas pela primeira vez. Anteriormente, os relatórios dos patrocinadores dependiam de contagens manuais e leituras de crachás, que eram trabalhosas e imprecisas. Ao expor contagens de visitantes agregadas e anonimizadas por zona (mapeadas para IDs de locais na plataforma da Purple) através da API, a equipa de eventos pôde fornecer aos patrocinadores painéis em tempo real que mostravam o tempo de permanência (dwell time) e o volume de visitantes em áreas patrocinadas. Os dados foram extraídos através da REST API a cada 15 minutos durante os eventos e exibidos num portal de patrocinadores construído à medida. Esta capacidade contribuiu diretamente para um aumento de 22% nas taxas de renovação de patrocínios no primeiro ano, uma vez que os patrocinadores podiam agora quantificar o alcance das suas ativações com dados primários verificados.

Key Terms & Definitions

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.

Case Studies

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.

Implementation Notes: 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.

Implementation Notes: 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.

Scenario Analysis

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?

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

Show Recommended Approach

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?

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

Show Recommended Approach

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?

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

Show Recommended Approach

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.

Key Takeaways

✓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.