Creazione Lista

Crea una nuova lista di contatti e ottieni il list_id per caricare i contatti.

POST /api/v1/{account_code}/lists/create
Authorization Bearer {token}  — 56 caratteri

Questo endpoint permette di creare una nuova lista di contatti. Una volta creata, viene restituito il list_id da utilizzare per caricare contatti tramite l'endpoint upload-contacts.

Limite creazione liste L'endpoint verifica automaticamente il numero massimo di liste consentite dal tuo piano. Se il limite è raggiunto, la creazione fallisce con errore 403.
Gestione automatica categorie Se specifichi una categoria, l'endpoint verifica se esiste già per il tuo account. Se non esiste, la crea in automatico. Il campo category_info.category_created nella risposta indica se è stata creata ora (true) o già esisteva (false).

Parametri (JSON)

Parametro Richiesto Tipo Descrizione
name SI string Nome della lista (es: "February 2026 Clients")
category SI string Categoria (es: "Clients", "Newsletter"). Creata automaticamente se non esiste.
default_domain SI string Dominio utilizzato per inviare email di conferma (double opt-in) ai contatti che si registrano tramite un eventuale form collegato alla lista.
reminder NO string Testo del reminder da mostrare agli iscritti (da richiamare nei Template Email)

Informazioni Opzionali Lista

Dati aggiuntivi salvati come metadati della lista.

Parametro Tipo Descrizione
representativestringNome del rappresentante
emailstringEmail di contatto
companystringNome azienda
vatstringPartita IVA
citystringCittà
addressstringIndirizzo completo
zipstringCodice postale
provincestringProvincia
countrystringNazione
phone_prefixstringPrefisso telefonico (es: +39)
phonestringNumero di telefono
websitestringSito web

Esempio Richiesta

JSON 
{
  "name": "February 2026 Clients",
  "category": "Clients",
  "reminder": "Ricevi questa comunicazione perché sei iscritto alla mia lista",
  "default_domain": "example.com",
  "representative": "Mario Rossi",
  "email": "info@example.com",
  "company": "Acme Corporation",
  "vat": "IT12345678901",
  "city": "Milan",
  "address": "Via Roma 123",
  "zip": "20100",
  "province": "MI",
  "country": "Italy",
  "phone_prefix": "+39",
  "phone": "0212345678",
  "website": "https://www.example.com"
}

Risposta Successo

201 Created
JSON 
{
  "success": true,
  "message": "List created successfully.",
  "data": {
    "list_id": 123,
    "name": "February 2026 Clients",
    "category": "Clients",
    "created_at": "2026-02-11 15:30:45",
    "categoria_info": {
      "category_id": 8,
      "category_created": false
    }
  }
}

Campi Risposta

Campo Tipo Descrizione
successbooleanRisultato dell'operazione
messagestringMessaggio descrittivo
data.list_idintegerID lista creata — usare per caricare contatti
data.namestringNome della lista
data.categorystringCategoria della lista
data.created_atstringData creazione (formato: Y-m-d H:i:s)
data.categoria_infoobjectPresente solo se è stata specificata una categoria
data.categoria_info.category_idintegerID categoria verificata/creata
data.categoria_info.category_createdbooleantrue se creata ora, false se già esisteva

Errori Comuni

400 Bad Request
JSON 
{
  "success": false,
  "message": "Necessary data is missing."
}
403 Forbidden — Limite raggiunto
JSON 
{
  "success": false,
  "message": "Failed to create list. You may have reached your list creation limit."
}
403 Forbidden — Token non valido
JSON 
{
  "success": false,
  "message": "NO Token Found."
}

Flusso Completo: Crea Lista + Carica Contatti

1
Crea la lista
JSON Request 
POST /api/v1/{account_code}/lists/create
Content-Type: application/json

{
  "name": "February 2026 Clients",
  "category": "Clients"
}

// → Risposta: { "data": { "list_id": 123 } }
2
Carica i contatti usando il list_id
JSON Request 
POST /api/v1/{account_code}/lists/upload-contacts
Content-Type: application/json

{
  "list_id": 123,
  "add_prefix": 1,
  "default_prefix": "+39",
  "column_headers": ["NOME", "COGNOME", "EMAIL", "PHONE"],
  "column_types": ["text", "text", "email", "phone"],
  "data_build": [
    ["Mario", "Rossi", "mario.rossi@email.com", "3331234567"],
    ["Laura", "Bianchi", "laura.bianchi@email.com", "3407654321"]
  ]
}

// → Risposta: { "success": true, "contacts_processed": 2 }