> For the complete documentation index, see [llms.txt](https://help.impact.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.impact.com/brand/it/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participants/import-advocate-participants-in-bulk.md).

# Importa in blocco i partecipanti Advocate

Advocate accetta importazioni inviate in formato `.csv` o `.jsonl` file. Consulta il nostro [file CSV di importazione di esempio](https://assets.ctfassets.net/s68ib1kj8k5n/7LOYwhDlsI22uuaIMaWImE/71cefe860edc71c0968c8065e1d6e953/sample-user-upload.csv) e il [file JSONL di importazione di esempio](https://assets.ctfassets.net/s68ib1kj8k5n/5rD1ZiKEjqStp54qjDB90N/48918dfa8b53a935c7c83ea5fbf3af77/userImportSample.jsonl) per visualizzare la struttura richiesta per il file da importare.

{% hint style="info" %}
**Nota:** Ti consigliamo di non superare le 500.000 voci per importazione.
{% endhint %}

#### Importare partecipanti in blocco

1. Dal menu di navigazione a sinistra, seleziona ![](https://impact-1.gitbook.io/docs/emvxfLrwrlacc4y3y02Y/~gitbook/image?url=https%3A%2F%2F4048883401-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FwMLlMoFBtKJa8ptd3zaw%252Fuploads%252Fgit-blob-230534471fef5f40808e921e41ee44e4a06ded03%252Fe6cb9548999afdc1ed3ce4942e4cb5b45b5cecbd323267aac2a7cd1915fccc09.svg%3Falt%3Dmedia\&width=300\&dpr=3\&quality=100\&sign=71dd50ef\&sv=2) **\[Engage] → Partecipanti**.
2. Seleziona **Importa utenti**.
3. In *Tipo di importazione*, seleziona **Utenti**.
4. Aggiungi il file da importare selezionando **Seleziona file**.
5. **\[Facoltativo]** Per aggiungere o rimuovere i partecipanti importati da uno specifico segmento di utenti, seleziona il segmento dall'elenco a discesa.

{% hint style="info" %}
**Nota:** Questa selezione si applica a *tutti i* partecipanti inclusi in questo file di importazione.
{% endhint %}

6. Seleziona **Avvia importazione**.

Al termine dell'importazione, viene inviata un'email di conferma. A seconda della coda e delle dimensioni del file, l'importazione può richiedere fino a 30 minuti.

#### Campi

Le importazioni in blocco di utenti supportano sia i campi standard sia i campi personalizzati nel file caricato. **I campi distinguono tra maiuscole e minuscole.**

{% tabs %}
{% tab title="Campi standard" %}
I campi standard vengono analizzati con la stessa convalida usata per la nostra [chiamata API Open Endpoint User Upsert](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-api/api-open-endpoints):

| Campo                     | Tipo     | Descrizione                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| accountId (obbligatorio)  | stringa  | Identificatore univoco dell'account a cui appartiene questo partecipante.                                                                                                                                                                                                                                                                                                                                                                      |
| id (obbligatorio)         | stringa  | Identificatore univoco assegnato a questo partecipante.                                                                                                                                                                                                                                                                                                                                                                                        |
| firstName                 | stringa  | Nome del partecipante.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| lastName                  | stringa  | Cognome del partecipante.                                                                                                                                                                                                                                                                                                                                                                                                                      |
| email                     | stringa  | Indirizzo email del partecipante.                                                                                                                                                                                                                                                                                                                                                                                                              |
| referable                 | booleano | <p>Flag usato da impact.com per determinare se un partecipante può essere oggetto di referenza.</p><p><strong>Nota:</strong> Il flag deve essere scritto usando solo <em>uno</em> <code>r</code> affinché lo stato venga modificato correttamente.</p>                                                                                                                                                                                         |
| locale                    | stringa  | La lingua e l'area geografica del partecipante, usate per [l'internazionalizzazione](https://help.impact.com/brand/it/what-would-you-like-to-learn-about/advocate-program/advocate-program-settings/translate-and-localize-your-advocate-program.md). Il locale deve avere il formato `language_COUNTRY` dove il codice della lingua deve essere in minuscolo e il codice del paese in maiuscolo. Il separatore deve essere un trattino basso. |
| countryCode               | stringa  | La lingua e l'area geografica del partecipante, usate per [l'internazionalizzazione](https://help.impact.com/brand/it/what-would-you-like-to-learn-about/advocate-program/advocate-program-settings/translate-and-localize-your-advocate-program.md). Il codice del paese dell'utente (ad es. CA).                                                                                                                                             |
| referredBy.code           | stringa  | Il codice di referral dell'advocate che ha segnalato questo partecipante.                                                                                                                                                                                                                                                                                                                                                                      |
| referralCodes.{programId} | stringa  | Il codice referral personalizzato che il partecipante può condividere per il programma specificato (generato automaticamente se non incluso).                                                                                                                                                                                                                                                                                                  |
| sharelinks.{programId}    | stringa  | Il link personalizzato che il partecipante può condividere per il programma specificato (generato automaticamente se non incluso).                                                                                                                                                                                                                                                                                                             |
| dateCreated               | stringa  | La data di creazione di questo partecipante nel tuo programma Advocate.                                                                                                                                                                                                                                                                                                                                                                        |
| imageUrl                  | stringa  | Utilizzato facoltativamente in widget, email e temi. Se fornisci un URL assoluto dell'immagine del profilo, l'immagine deve misurare almeno 80 px x 80 px.                                                                                                                                                                                                                                                                                     |
| dateUsTaxFormSubmitted    | intero   | La data in cui il modulo fiscale W-9 del partecipante è stato contrassegnato come raccolto. Utilizzato per la conformità W-9 nel tuo tenant, se configurato.                                                                                                                                                                                                                                                                                   |
| customFields.{fieldName}  | stringa  | Usa questa struttura per includere un campo personalizzato a tua scelta.                                                                                                                                                                                                                                                                                                                                                                       |
| {% endtab %}              |          |                                                                                                                                                                                                                                                                                                                                                                                                                                                |

{% tab title="Campi personalizzati" %}
[Campi utente personalizzati](https://help.impact.com/brand/it/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participants/custom-and-calculated-fields/custom-fields-for-advocate-explained.md) consentono di gestire dati specifici dei tuoi partecipanti. Puoi impostare gli obiettivi del programma in modo che si attivino in base alle informazioni contenute in un campo utente personalizzato.

{% hint style="info" %}
**Esempio**: premia i partecipanti quando rinnovano l'abbonamento. Per prima cosa, includi il campo personalizzato `customFields.subscriptionPaid` con il valore **sì**. Poi, imposta l'obiettivo affinché venga raggiunto quando `customFields.subscriptionPaid` è uguale a **sì**.
{% endhint %}

Aggiungi i campi personalizzati all'intestazione della colonna usando questo formato: `customFields.yourCustomFieldName`.

{% hint style="info" %}
**Nota:** I campi personalizzati non accettano valori di tipo array o oggetto.
{% endhint %}
{% endtab %}
{% endtabs %}

**Risultati**

Ti invieremo un'email quando l'importazione sarà completata. Puoi scaricare i risultati dell'importazione dalla pagina ![](https://impact-1.gitbook.io/docs/emvxfLrwrlacc4y3y02Y/~gitbook/image?url=https%3A%2F%2F4048883401-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FwMLlMoFBtKJa8ptd3zaw%252Fuploads%252Fgit-blob-230534471fef5f40808e921e41ee44e4a06ded03%252Fe6cb9548999afdc1ed3ce4942e4cb5b45b5cecbd323267aac2a7cd1915fccc09.svg%3Falt%3Dmedia\&width=300\&dpr=3\&quality=100\&sign=71dd50ef\&sv=2) **\[Coinvolgi] → Report → Importazioni ed esportazioni** del tuo programma Advocate.

{% hint style="warning" %}
**Attenzione:** I link per il download scadono dopo 30 giorni.
{% endhint %}

{% tabs %}
{% tab title="Caricamento riuscito" %}
Se l'importazione viene completata correttamente, verrà generato un file con le informazioni dei partecipanti e ti verrà inviato via email. Le informazioni incluse in questi risultati sono le stesse presenti nel nostro [report dei dettagli utente](https://help.impact.com/brand/it/what-would-you-like-to-learn-about/advocate-program/advocate-reporting-and-analytics/advocate-program-reports-explained.md).
{% endtab %}

{% tab title="Errori" %}
Se si verificano errori durante l'importazione, verrà generato un file aggiuntivo. Questo file contiene una voce per ogni errore verificatosi, incluso il numero di riga del record (nel file di importazione originale) che ha generato l'errore e gli eventuali messaggi di errore associati.

| recordNumber | message                                            | apiErrorCode | statusCode |
| ------------ | -------------------------------------------------- | ------------ | ---------- |
| 2            | Questa richiesta richiede un id valido e non vuoto | BAD\_REQUEST | 400        |

Nell'improbabile eventualità che si verifichi un errore di sistema e l'importazione venga interrotta, lo stato dell'importazione sarà **interrotto** e non verrà ripristinato. Se hai bisogno di ulteriore assistenza, contatta il nostro team di supporto.
{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.impact.com/brand/it/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participants/import-advocate-participants-in-bulk.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
