UC-023 — Segmentazione Contatti Avanzata

Campo	Valore
ID	UC-023
Obiettivo	Segmentare contatti con filtri avanzati per creare liste mirate
Canale	Tutti
Complessità	⭐⭐⭐ Avanzato
Tempo stimato	30 minuti
API coinvolte	`GET /api/partner-gateway/v1/contacts`, `POST /contacts`, `PUT /contacts/{id}`, `POST /contacts/list`, `POST /contacts/list/contacts`, `DELETE /contacts/list/contacts`

Scenari reali

TurismoVeneto — Segmentare per regione: Filtra i 20.000 contatti per regione di residenza e crea liste separate per Lombardia, Veneto ed Emilia-Romagna per promozioni geolocalizzate.
LuxuryStore — Lista VIP: Identifica i clienti con spesa totale superiore a 5.000 EUR e crea una lista VIP per anteprime esclusive e inviti a eventi privati.
FreshMarket — Filtrare per ultimo acquisto: Seleziona i clienti che non acquistano da oltre 90 giorni per una campagna di re-engagement con coupon sconto.

Flusso di segmentazione

Il diagramma mostra il flusso: dalla lista completa si applicano filtri multipli (regione, attributi, data) per creare liste segmentate pronte per le campagne.

Prerequisiti

API Key attiva con permessi gestione contatti
Contatti importati nella piattaforma (vedi UC-007)
Almeno una lista contatti esistente con campi custom valorizzati

Step 1 — Recupera contatti con filtri

Interroga i contatti con i filtri supportati da GET /contacts, qui solo quelli raggiungibili (isValid=true). La regione non è un query parameter: in questo esempio è salvata in customField1, con la spesa totale in customField2 e la data dell'ultimo acquisto in customField3 (valorizzati all'import o con PUT /contacts/{id}), e la selezione su questi campi avviene nel tuo codice.

curl -X GET "https://api.qlara.ai/api/partner-gateway/v1/contacts?isValid=true&page=0&limit=50" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Contatti filtrati

{
  "data": [
    {
      "id": 30112,
      "fullName": "Marco Rossi",
      "firstName": "Marco",
      "lastName": "Rossi",
      "phoneNumbers": ["+393471234567"],
      "emailAddresses": ["marco.rossi@email.it"],
      "mobilePhoneNumber": "+393471234567",
      "isValidMobilePhoneNumber": true,
      "city": "Milano",
      "customField1": "Lombardia",
      "customField2": "1250.00",
      "customField3": "2026-03-15"
    },
    {
      "id": 30113,
      "fullName": "Laura Bianchi",
      "firstName": "Laura",
      "lastName": "Bianchi",
      "phoneNumbers": ["+393489876543"],
      "emailAddresses": ["laura.bianchi@email.it"],
      "mobilePhoneNumber": "+393489876543",
      "isValidMobilePhoneNumber": true,
      "city": "Bergamo",
      "customField1": "Lombardia",
      "customField2": "6800.00",
      "customField3": "2026-01-10"
    }
  ],
  "page": 0,
  "limit": 50,
  "totalCount": 18640,
  "totalPages": 373
}

Dietro le quinte — Filtri disponibili e logica di query

Filtri standard: search (nome), gender, isValid, communicationSupported, isTest, phoneNumber, email, lastContactType, lastCampaignType, listIds e notListIds sono filtrabili direttamente come query parameter.
Campi custom: customField1, customField2 e customField3, come city e tags, vengono restituiti con ogni contatto ma non sono query parameter: seleziona su di essi lato client, oppure lascia che li confronti una smart list tramite i filters di POST /contacts/list (es. {"field": "customField1", "operand": "equals", "value": "Lombardia"}), valutati a ogni invio.
Paginazione: Usa page (a partire da 0) e limit per paginare risultati di grandi dimensioni; la risposta riporta totalCount e totalPages. Il massimo per limit e 1000.
Ordinamento: Usa sortBy=campo&sortOrder=asc|desc per ordinare i risultati (di default per fullName, in ordine crescente).
Combinazione filtri: Tutti i filtri sono in AND logico. Per logiche OR complesse, esegui più query e combina i risultati lato client.

Step 2 — Crea una lista segmentata

Crea una nuova lista destinata al segmento identificato.

curl -X POST https://api.qlara.ai/api/partner-gateway/v1/contacts/list \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "name": "VIP Lombardia - Spesa > 5000 EUR",
    "description": "Clienti lombardi con spesa totale superiore a 5000 EUR"
  }'

Response — Lista creata

{
  "id": 912,
  "name": "VIP Lombardia - Spesa > 5000 EUR",
  "description": "Clienti lombardi con spesa totale superiore a 5000 EUR",
  "filters": null,
  "companyId": 4618,
  "numContact": 0,
  "isTest": false,
  "isDeleted": false,
  "createdAt": "2026-04-09 09:00:00.418+0000",
  "updatedAt": "2026-04-09 09:00:00.418+0000"
}

Step 3 — Aggiungi contatti alla lista segmentata

Aggiungi i contatti filtrati alla nuova lista usando il loro ID.

curl -X POST https://api.qlara.ai/api/partner-gateway/v1/contacts/list/contacts \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "listIds": [912],
    "contactIds": [30113, 30127, 30188, 30241, 30302]
  }'

Response — Contatti aggiunti

[88101, 88102, 88103, 88104, 88105]

La risposta elenca gli ID delle associazioni create.

Automazione della segmentazione

Per liste di grandi dimensioni, automatizza il processo lato server: recupera tutti i contatti filtrati con paginazione, raccogli gli ID e inviali in batch alla lista. Il limite per batch e 1.000 contatti.

Risultato atteso

Step	Azione	Risultato
1	`GET /contacts?isValid=true`	Contatti raggiungibili, quelli lombardi selezionati su `customField1`
2	`POST /contacts/list`	Nuova lista segmentata creata
3	`POST /contacts/list/contacts`	Contatti VIP aggiunti alla lista

Esempio completo end-to-end

# 1. Recupera i contatti raggiungibili (paginando)
CONTACTS=$(curl -s -X GET \
  "https://api.qlara.ai/api/partner-gateway/v1/contacts?isValid=true&page=0&limit=1000" \
  -H "X-Api-Key: YOUR_API_KEY")

# 2. Filtra lato client: Lombardia (customField1) con spesa > 5000 EUR (customField2)
VIP_IDS=$(echo "$CONTACTS" | jq -c '[.data[] | select(.customField1 == "Lombardia" and ((.customField2 | tonumber?) // 0) > 5000) | .id]')
echo "VIP IDs: $VIP_IDS"

# 3. Crea la lista segmentata
LIST_ID=$(curl -s -X POST https://api.qlara.ai/api/partner-gateway/v1/contacts/list \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "name": "VIP Lombardia - Spesa > 5000 EUR",
    "description": "Segmento VIP per campagna esclusiva"
  }' | jq -r '.id')

echo "List ID: $LIST_ID"

# 4. Aggiungi contatti alla lista
curl -s -X POST https://api.qlara.ai/api/partner-gateway/v1/contacts/list/contacts \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d "{
    \"listIds\": [${LIST_ID}],
    \"contactIds\": ${VIP_IDS}
  }" | jq .

Varianti

Segmentazione per inattivita (re-engagement)

Filtra contatti che non acquistano da oltre 90 giorni, confrontando lato client la data dell'ultimo acquisto salvata in customField3 (formato yyyy-MM-dd):

curl -s -X GET "https://api.qlara.ai/api/partner-gateway/v1/contacts?isValid=true&page=0&limit=1000" \
  -H "X-Api-Key: YOUR_API_KEY" | jq -c '[.data[] | select((.customField3 // "") != "" and .customField3 < "2026-01-09") | .id]'

Rimuovere un contatto da una lista

Se un contatto non deve più appartenere a un segmento:

curl -X DELETE https://api.qlara.ai/api/partner-gateway/v1/contacts/list/contacts \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "listIds": [912],
    "contactIds": [30302]
  }'

Errori comuni

Risultati non filtrati — Filtro sconosciuto

GET /contacts non rifiuta i query parameter che non riconosce: un filtro come region=Lombardia o customField1=Lombardia viene ignorato, e la risposta contiene tutti i contatti che corrispondono agli altri filtri.

Soluzione: Usa solo i filtri standard elencati nello Step 1. Per city, tags e i campi custom, seleziona lato client oppure usa una smart list.

404 Not Found — Contatto non trovato

{
  "status": "fail",
  "data": {
    "contactId": "Contact not found: 999999"
  }
}

Soluzione: L'ID del contatto potrebbe essere stato eliminato o non esistere. Verifica l'ID con una GET prima dell'aggiunta alla lista.

401 Unauthorized — API Key mancante o non valida

{
  "status": "fail",
  "data": {
    "authentication": "Invalid or missing API key"
  }
}

Soluzione: Verifica che l'header X-Api-Key sia presente e che la chiave sia attiva nel pannello della piattaforma.

Prossimi passi

UC-007 — Gestione Contatti e Liste: Import contatti da CSV e VCard
UC-006 — Campagna SMS Bulk: Usa la lista segmentata in una campagna SMS
UC-022 — Campagna Bulk WhatsApp: Invia alla lista VIP tramite WhatsApp
UC-028 — Compliance Opt-out GDPR: Gestisci opt-out e conformita GDPR

Riferimenti

API Reference — Contacts: Documentazione completa endpoint contatti
Guida Contatti e Liste: Best practice per la gestione dei contatti
Guida Autenticazione: Dettagli su API Key e Basic Auth

Scenari reali​

Flusso di segmentazione​

Prerequisiti​

Step 1 — Recupera contatti con filtri​

Response — Contatti filtrati​

Step 2 — Crea una lista segmentata​

Response — Lista creata​

Step 3 — Aggiungi contatti alla lista segmentata​

Response — Contatti aggiunti​

Risultato atteso​

Esempio completo end-to-end​

Varianti​

Segmentazione per inattivita (re-engagement)​

Rimuovere un contatto da una lista​

Errori comuni​

Risultati non filtrati — Filtro sconosciuto​

404 Not Found — Contatto non trovato​

401 Unauthorized — API Key mancante o non valida​

Prossimi passi​

Riferimenti​