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

# Cerca persona

> Risolvi il nome di una persona in uno o più ID persona, con le aziende in cui è coinvolta.

`syrto_find_person` risolve il nome di una persona in ID persona. Usa quegli ID nella sezione `people` di [`syrto_search_companies`](/it/mcp/tools/search-companies) o [`syrto_aggregate_companies`](/it/mcp/tools/aggregate-companies) per trovare tutte le aziende in cui una persona è amministratore, socio o titolare effettivo.

## Quando usare questo strumento

* Cercare una persona per nome e ottenerne l'ID
* Distinguere più persone con lo stesso nome, tramite data di nascita, genere e coinvolgimenti aziendali
* Costruire il filtro `people` per una ricerca di aziende

**Strumenti correlati:** Per le aziende invece che per le persone, usa [Cerca azienda](/it/mcp/tools/find-company). Per i contatti di una persona, usa [Contatti persona](/it/mcp/tools/person-contacts).

<Tip>
  Quando la persona che cerchi è amministratore, azionista o titolare effettivo di un'azienda che hai già, [`syrto_get_company_structure`](/it/mcp/tools/company-structure) ne restituisce direttamente il `person_id`. È la via da preferire: questo strumento è una ricerca per nome, quindi può finire su un omonimo.
</Tip>

## Argomenti

<ParamField query="name" type="string" required>
  Nome completo da risolvere (massimo 200 caratteri). Il registro memorizza i nomi con il **cognome per primo** - `"Rossi Mario"`, non `"Mario Rossi"` - e la corrispondenza è sull'ortografia esatta, senza fuzzy matching: un nome scritto male non restituisce nulla.

  Rispetta le maiuscole così come sono memorizzate. Solo il livello di corrispondenza esatta distingue maiuscole e minuscole, quindi un nome tutto minuscolo lo salta e risponde dal livello prefisso, perdendo l'ordinamento con le corrispondenze esatte in testa.

  L'ordine delle parole è gestito automaticamente: quando l'ordine fornito non trova nessuno, vengono ritentati gli ordini invertiti.
</ParamField>

<ParamField query="match" type="string">
  Come viene confrontato il nome.

  | Valore     | Comportamento                                                                                                                                             |
  | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `auto`     | Predefinito. Restituisce le corrispondenze esatte se ce ne sono, altrimenti i nomi che iniziano con la query, altrimenti quelli che la contengono.        |
  | `exact`    | Solo le persone il cui nome completo è esattamente la query. Distingue maiuscole e minuscole.                                                             |
  | `prefix`   | Solo i nomi che iniziano con la query.                                                                                                                    |
  | `contains` | I nomi che contengono la query in qualsiasi posizione. È il livello che trova i cognomi composti - `"Conti Marco"` corrisponde a `"Bonanno Conti Marco"`. |
</ParamField>

<ParamField query="after" type="string">
  Cursore per la paginazione. Passa `end_cursor` della risposta precedente con lo stesso nome per ottenere la pagina successiva. Un cursore è legato al livello di corrispondenza per cui è stato emesso: abbinalo allo stesso valore di `match`, oppure omettilo per iniziare una nuova ricerca.
</ParamField>

<ParamField query="language" type="string">
  `"en"` per l'inglese (predefinito) o `"it"` per l'italiano.
</ParamField>

## Come funziona la corrispondenza

Esattamente uno di tre livelli risponde a ogni chiamata: il nome corrisponde esattamente se qualcuno lo porta, altrimenti come prefisso, altrimenti come sottostringa. È questo che porta in cima alla prima pagina la persona cercata - una ricerca di `"Conti Marco"` restituisce le persone che si chiamano davvero così, invece di seppellirle dietro gli `"Arconti Marco"` e `"Buoninconti Marco"` che l'ordine alfabetico mette per primi.

Il compromesso è che risponde un solo livello per volta. `warning` indica il livello ogni volta che non è il più ampio e spiega come allargare la ricerca; allargandola, le corrispondenze più strette vengono rielencate insieme alle altre.

## Risposta

Risultati paginati:

<ResponseField name="has_next_page" type="boolean">
  Se è disponibile un'altra pagina. Questo strumento restituisce fino a 20 persone per pagina.
</ResponseField>

<ResponseField name="end_cursor" type="string | null">
  Cursore per la pagina successiva. Passalo come `after`, insieme al nome sotto cui sono stati trovati questi risultati - quando `warning` indica un ordine di parole diverso, usa quel nome riordinato.
</ResponseField>

<ResponseField name="items" type="object[]">
  Persone corrispondenti, ciascuna con:

  * `id` - l'ID persona da usare nel filtro di ricerca `people`
  * `full_name` - nome come memorizzato, cognome per primo
  * `birth_date` e `gender` - valori grezzi, per distinguere gli omonimi
  * `officerships`, `shareholdings`, `beneficial_ownerships` - fino a cinque ciascuno, con le aziende in cui la persona è coinvolta
</ResponseField>

<ResponseField name="warning" type="string | null">
  Presente quando il livello di corrispondenza è più stretto del più ampio, quando ha risposto un ordine di parole invertito rispetto a quello digitato, o quando non ha corrisposto nulla.
</ResponseField>

<ResponseField name="credit_balance" type="object | null">
  Accanto ai risultati, la risposta riporta il saldo crediti dell'organizzazione - `{ "available": ..., "reserved": ... }` - con cui si acquistano [documenti ufficiali](/it/mcp/tools/official-documents) e [contatti persona](/it/mcp/tools/person-contacts).

  Assente quando non è stato possibile risolvere un viewer per la credenziale. Assente significa "non noto", mai "esauriti".
</ResponseField>

<Note>
  Le voci aziendali sotto `officerships`, `shareholdings` e `beneficial_ownerships` identificano l'azienda tramite `tax_id`, non tramite company ID. Per analizzare quelle aziende, raccogli i codici fiscali e passali a [`syrto_lookup_companies_by_tax_id`](/it/mcp/tools/lookup-companies-by-tax-id) (fino a 20 in una sola chiamata), poi usa i company ID restituiti.

  `tax_id` è omesso nella rara voce priva di codice fiscale a registro, e un codice fiscale può risultare `not_found`. In entrambi i casi quell'azienda è identificabile solo tramite `legal_name`.
</Note>

<Note>
  Quando non corrisponde nulla, il risultato è una lista `items` vuota con indicazioni in `warning` - non un errore.
</Note>

## Esempio

**Cercare una persona:**

```json theme={null}
{
  "name": "Rossi Mario"
}
```

**Allargare ai cognomi composti:**

```json theme={null}
{
  "name": "Conti Marco",
  "match": "contains"
}
```

Restituisce le persone che si chiamano esattamente `"Conti Marco"` insieme ai nomi più lunghi che lo contengono, come `"Bonanno Conti Marco"`.