UC-007 — Gestione Contatti e Liste per Campagne

Campo	Valore
ID	UC-007
Obiettivo	Importare contatti, creare liste segmentate e prepararle per l'uso in campagne
Canale	Tutti
Complessità	⭐⭐ Intermedio
Tempo stimato	20 minuti
API coinvolte	`POST/GET/DELETE /api/partner-gateway/v1/contacts`, `PUT /contacts/{id}`, `POST/GET /contacts/list`, `POST /contacts/list/contacts`, `POST /contacts/upload`, `POST /contacts/upload/vcard`

Scenari reali

ShopItalia — Import rubrica clienti: Importa l'export dal CRM aziendale (CSV con 5.000 clienti) nella piattaforma per preparare la campagna Black Friday.
TurismoVeneto — Segmentazione per regione: Crea liste separate per clienti di Lombardia, Veneto ed Emilia-Romagna per inviare promozioni geolocalizzate sui soggiorni estivi.
Studio Legale Ferrara — Rubrica da telefono: Importa la rubrica aziendale in formato VCard per inviare comunicazioni istituzionali via SMS.

Flusso di gestione contatti

Il diagramma mostra i tre percorsi di importazione: aggiunta manuale, upload CSV/Excel o import VCard. I contatti caricati da file finiscono in rubrica e vengono poi aggiunti alla lista. Tutti i percorsi convergono nella verifica e nell'utilizzo in campagna.

Step 1 — Crea una lista contatti

Crea una lista vuota che funzionera da contenitore per i contatti.

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": "Clienti Nord Italia",
    "description": "Clienti delle regioni Lombardia, Piemonte, Veneto, Emilia-Romagna"
  }'

Response — Lista creata

{
  "id": 87,
  "name": "Clienti Nord Italia",
  "description": "Clienti delle regioni Lombardia, Piemonte, Veneto, Emilia-Romagna",
  "filters": null,
  "companyId": 4618,
  "numContact": 0,
  "isTest": false,
  "isDeleted": false,
  "createdAt": "2026-04-09 09:00:04.512+0000",
  "updatedAt": "2026-04-09 09:00:04.512+0000"
}

Salva l'ID lista

Il campo id e l'identificativo che userai per aggiungere contatti e associare la lista alle campagne.

Step 2a — Aggiungi contatti singolarmente

Crea un nuovo contatto nella rubrica e associalo alla lista.

curl -X POST https://api.qlara.ai/api/partner-gateway/v1/contacts \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "firstName": "Giulia",
    "lastName": "Rossi",
    "phoneNumbers": ["+393401234567"],
    "emailAddresses": ["giulia.rossi@example.it"],
    "gender": "F",
    "city": "Milano"
  }'

Response — Contatto creato

{
  "contacts": [
    {
      "id": 24501,
      "fullName": "Giulia Rossi",
      "firstName": "Giulia",
      "lastName": "Rossi",
      "gender": "F",
      "phoneNumbers": ["+393401234567"],
      "emailAddresses": ["giulia.rossi@example.it"],
      "city": "Milano",
      "isValidMobilePhoneNumber": true,
      "isValidEmail": true,
      "mobilePhoneNumber": "+393401234567",
      "isTest": false,
      "createdAt": "2026-04-09 09:01:12.284+0000"
    }
  ],
  "errors": []
}

Associa il contatto alla lista:

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 '{
    "contactIds": [24501],
    "listIds": [87]
  }'

La risposta elenca gli ID delle associazioni create:

[90412]

Aggiunta multipla

Puoi passare più contactIds e più listIds in una sola richiesta per associare N contatti a M liste contemporaneamente.

Step 2b — Import bulk da CSV

Per importazioni massive, carica un file CSV o Excel. Il processo avviene in due fasi: l'upload, che mappa le colonne e importa i contatti in un'unica chiamata, poi l'aggiunta dei contatti importati alla lista.

Formato CSV atteso

Le colonne vengono mappate automaticamente in base ai nomi dell'intestazione, quindi usa i nomi dei campi del contatto (come firstName, lastName, phoneNumber, email):

firstName,lastName,phoneNumber,email
Marco,Bianchi,+393489876543,m.bianchi@example.it
Anna,Verdi,+393331122334,anna.verdi@example.it
Luca,Neri,+393201234567,l.neri@example.it

Fase 1 — Upload e import

Invia il file e il suo nome; removeHead=true evita che la riga di intestazione venga importata come contatto:

curl -X POST "https://api.qlara.ai/api/partner-gateway/v1/contacts/upload?removeHead=true" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@clienti_nord_italia.csv" \
  -F "fileName=clienti_nord_italia.csv"

Response — Import completato

{
  "numContact": 5230,
  "addedContact": 5104,
  "updatedContact": 98,
  "listId": null,
  "listName": null,
  "numError": 28
}

addedContact conta i nuovi contatti, updatedContact quelli già presenti (riconosciuti dal numero di telefono) aggiornati con i dati del file, e numError le righe che non è stato possibile importare. listId e listName sono null perché l'upload non ha un parametro per la lista di destinazione: i contatti finiscono nella tua rubrica.

Fase 2 — Aggiungi i contatti importati alla lista

Trova gli ID dei contatti importati con GET /contacts: notListIds=87 restituisce i contatti non ancora presenti nella lista, fino a 1.000 per pagina. Tieni quelli il cui numero di telefono è nel tuo file e aggiungili alla lista (qui sono mostrati tre ID):

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

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": [87],
    "contactIds": [24502, 24503, 24504]
  }'

Response — Contatti aggiunti alla lista

[90413, 90414, 90415]

Dietro le quinte — Processo di import CSV

Upload e parsing: Il file viene caricato e analizzato, e le sue colonne vengono mappate sui campi del contatto in base ai nomi dell'intestazione. Con removeHead=true la riga di intestazione non viene importata come contatto.
Import: Nella stessa chiamata i contatti vengono salvati in rubrica (creati, oppure aggiornati come al punto 4). Non vengono aggiunti a nessuna lista: è la Fase 2.
Validazione numeri: I numeri vengono validati in formato internazionale. Numeri malformati o senza prefisso vengono scartati.
Deduplicazione: I contatti il cui numero di telefono esiste già vengono aggiornati con i dati del file invece di essere inseriti di nuovo, e sono conteggiati in updatedContact.

Dato che il mapping è automatico e l'import avviene in un'unica chiamata, controlla i nomi dell'intestazione e prova con un piccolo file di esempio prima di importare migliaia di record.

Step 2c — Import da VCard

Per importare contatti da una rubrica telefonica in formato .vcf:

curl -X POST https://api.qlara.ai/api/partner-gateway/v1/contacts/upload/vcard \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@rubrica_aziendale.vcf" \
  -F "fileName=rubrica_aziendale.vcf"

Response — VCard importato

{
  "numContact": 342,
  "addedContact": 335,
  "updatedContact": 4,
  "listId": null,
  "listName": null,
  "numError": 3
}

Come per il CSV, l'import avviene in questa sola chiamata e i contatti finiscono in rubrica: aggiungili alla lista come nella Fase 2 dello Step 2b.

Mapping automatico VCard

Mentre il CSV si basa sui nomi dell'intestazione, i contatti VCard usano campi standard (FN, TEL, EMAIL, ADR) che vengono mappati automaticamente, senza alcuna configurazione.

Step 3 — Verifica i contatti nella lista

Consulta i contatti presenti nella lista con paginazione.

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

Response — Elenco contatti

{
  "data": [
    {
      "id": 24501,
      "fullName": "Giulia Rossi",
      "firstName": "Giulia",
      "lastName": "Rossi",
      "phoneNumbers": ["+393401234567"],
      "emailAddresses": ["giulia.rossi@example.it"],
      "mobilePhoneNumber": "+393401234567",
      "isValidMobilePhoneNumber": true,
      "listIds": [87]
    },
    {
      "id": 24502,
      "fullName": "Marco Bianchi",
      "firstName": "Marco",
      "lastName": "Bianchi",
      "phoneNumbers": ["+393489876543"],
      "emailAddresses": ["m.bianchi@example.it"],
      "mobilePhoneNumber": "+393489876543",
      "isValidMobilePhoneNumber": true,
      "listIds": [87]
    }
  ],
  "page": 0,
  "limit": 10,
  "totalCount": 5542,
  "totalPages": 555
}

Step 4 — Usa la lista in una campagna

Passa l'id della lista in contactListIds della campagna:

curl -X PUT https://api.qlara.ai/api/partner-gateway/v1/campaigns/1542 \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "smsSender": "ShopItalia",
    "smsBody": "Offerta esclusiva per i clienti del Nord Italia! -30% su tutto con codice NORD30.",
    "contactListIds": [87]
  }'

Vedi UC-006 — Campagna SMS Bulk per il flusso completo di invio campagna.

Operazioni aggiuntive

Rimuovi contatti da una lista

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 '{
    "contactIds": [24501],
    "listIds": [87]
  }'

true

Cerca contatti per filtro

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

Riferimento rapido endpoint

Azione	Metodo	Endpoint
Lista contatti	`GET`	`/contacts`
Crea contatto	`POST`	`/contacts`
Aggiorna contatto	`PUT`	`/contacts/{id}`
Elimina contatti	`DELETE`	`/contacts`
Lista delle liste	`GET`	`/contacts/list`
Crea lista	`POST`	`/contacts/list`
Aggiungi a lista	`POST`	`/contacts/list/contacts`
Rimuovi da lista	`DELETE`	`/contacts/list/contacts`
Contatti in lista	`GET`	`/contacts/list/{id}/contacts`
Upload CSV	`POST`	`/contacts/upload`
Upload VCard	`POST`	`/contacts/upload/vcard`

Risultato atteso

Step	Azione	Risultato
1	`POST /contacts/list`	Lista creata con `id`
2a	`POST /contacts` + `POST /contacts/list/contacts`	Contatto creato e associato alla lista
2b	`POST /contacts/upload` + `POST /contacts/list/contacts`	5.202 contatti importati da CSV (5.104 nuovi, 98 aggiornati) e aggiunti alla lista
2c	`POST /contacts/upload/vcard` + `POST /contacts/list/contacts`	339 contatti importati da VCard e aggiunti alla lista
3	`GET /contacts/list/{id}/contacts`	Elenco paginato dei contatti nella lista
4	`PUT /campaigns/{id}` con `contactListIds`	Lista associata alla campagna

Prossimi passi

UC-006 — Campagna SMS Bulk: Usa le liste appena create per lanciare campagne
Guida Contatti e Liste: Approfondisci filtri, paginazione e gestione avanzata
Guida Export: Esporta i contatti per analisi esterne

Scenari reali​

Flusso di gestione contatti​

Step 1 — Crea una lista contatti​

Response — Lista creata​

Step 2a — Aggiungi contatti singolarmente​

Response — Contatto creato​

Step 2b — Import bulk da CSV​

Formato CSV atteso​

Fase 1 — Upload e import​

Response — Import completato​

Fase 2 — Aggiungi i contatti importati alla lista​

Response — Contatti aggiunti alla lista​

Step 2c — Import da VCard​

Response — VCard importato​

Step 3 — Verifica i contatti nella lista​

Response — Elenco contatti​

Step 4 — Usa la lista in una campagna​

Operazioni aggiuntive​

Rimuovi contatti da una lista​

Cerca contatti per filtro​

Riferimento rapido endpoint​

Risultato atteso​

Prossimi passi​