> ## Documentation Index
> Fetch the complete documentation index at: https://docs.emailx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Importare People da CSV o XLSX

> Visualizza in anteprima un file CSV o XLSX con mappatura esplicita, conferma l’importazione e consulta gli esiti paginati senza iscrivere i contatti a una campagna.

L’importazione People crea o riutilizza contatti del workspace dopo aver esaminato un’anteprima in sola lettura. Non iscrive contatti a campagne, non genera messaggi e non avvia comunicazioni. Usa un host API compatibile con la versione 0.8.0, controlla le capacità del workspace e considera `503 feature_unavailable` come funzione non disponibile su quell’host. La disponibilità dell’host non è garantita.

## Visualizzare l’anteprima prima di scrivere

Scegli `email` o `linkedin`, associa ogni campo contatto supportato a un’intestazione esatta del file e invia il file a `POST /workspaces/{workspace_id}/contacts/imports/preview`. L’anteprima richiede `contacts:read`, non scrive contatti ed è disponibile anche quando l’esecuzione import è disattivata. Esamina esiti, blocchi, totali e `fingerprint` restituito.

Il file, dopo la decodifica base64, è limitato a 64 KiB e 1.000 righe di dati. Il corpo HTTP è limitato a 256 KiB. I comandi durevoli sono limitati a 128 KiB per l’importazione People e 64 KiB per gli altri comandi. Sono supportati CSV e XLSX; gli altri formati non sono disponibili.

## Confermare l’anteprima esatta

Solo dopo averla esaminata, invia lo stesso file e la stessa mappatura con l’esatto `expected_fingerprint` e `confirm_import: true` a `POST /contacts/imports`. Servono `contacts:write` e una chiave di idempotenza; la risposta `202` include l’ID dell’operazione. Se cambiano file, mappatura, canale o stato di contatto/esclusione, ripeti l’anteprima e usa il nuovo fingerprint.

Una riga può riutilizzare un contatto corrispondente idoneo o crearne uno. I campi identità esistenti non vengono sovrascritti e i contatti esclusi sono bloccati. Le righe solo LinkedIn possono creare contatti canonici senza email. L’endpoint legacy per creare direttamente un contatto richiede ancora un indirizzo email. Questa importazione People non esegue ricerche provider.

## Interrogare e leggere gli esiti

Leggi l’operazione con `operations:read` e `contacts:read`. Poi richiedi `/contacts/imports/{operation_id}/rows` con `contacts:read` e `operations:read`; usa `offset` e `limit` per paginare esiti e ID contatto. Il risultato non restituisce il file caricato.

Fermati a `awaiting_user_action`, `needs_reconciliation` o a uno stato terminale. In caso di timeout o esito incerto, leggi l’operazione originale e gli esiti delle righe; non accodare automaticamente una seconda importazione. Risolvi il problema noto e ripeti l’anteprima prima di iniziare una nuova importazione logica.

Il completamento dell’importazione salva solo i contatti. Aggiungerli a una campagna richiede un flusso separato ed esplicito.

Consulta [copertura API](https://docs.emailx.ai/it/api-reference/coverage.md), [limiti delle richieste](https://docs.emailx.ai/it/api-reference/rate-limits.md) e [idempotenza e recupero](https://docs.emailx.ai/it/api-reference/idempotency.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.