Vai al contenuto principale
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, limiti delle richieste e idempotenza e recupero.