Skip to main content
Syrto può acquistare da fornitori di dati esterni gli indirizzi email di lavoro e i numeri di telefono diretti di una persona. Non fanno parte delle risultanze camerali, e per questo costano crediti. Se ne occupano due strumenti: Gli ID persona provengono da syrto_find_person, oppure dal person_id di un amministratore, azionista o titolare effettivo restituito da syrto_get_company_structure. La seconda via è la più precisa: syrto_find_person è una ricerca per nome, quindi può finire su un omonimo.
I contatti acquistati appartengono all’intera organizzazione, non a chi li ha comprati. Un collega potrebbe averli già pagati: syrto_get_person_contacts è il modo per scoprirlo, e non costa crediti.

​
syrto_get_person_contacts

Riporta i contatti disponibili per una persona e il costo per acquistarli. Non spende crediti contatto ed è sicuro da chiamare ripetutamente. Usalo:
  • Prima di ogni acquisto. Fornisce il costo da confermare con l’utente e indica se per questa persona si possa trovare qualcosa.
  • Per leggere contatti già acquistati.
  • Per raccogliere dati ancora in arrivo. I fornitori restituiscono prima le email e poi i numeri di telefono, quindi i contatti con stato IN_PROGRESS restano incompleti per un breve periodo. Richiamare questo strumento è il modo per ottenere il resto - acquistare di nuovo significherebbe pagarlo due volte.

​
Argomenti

​
string
obbligatorio
L’ID della persona, da syrto_find_person o da un person_id in syrto_get_company_structure.
​
string
"en" per inglese (predefinito) o "it" per italiano.

​
Risposta

​
object
id (il person_id che hai passato) e name.
​
object
Che cosa si può acquistare, non che cosa è già posseduto:
  • has_email - è possibile trovare un indirizzo email
  • has_direct_phone - è possibile trovare un numero di telefono diretto
  • credit_cost - quanto costerebbe acquistarlo
Entrambi i flag false significa che per questa persona non si può trovare nulla, a nessun prezzo.
​
object | null
Ciò che l’organizzazione ha già acquistato:
  • status - COMPLETED, oppure IN_PROGRESS mentre altro è ancora in arrivo
  • emails - lista di indirizzi email
  • phone_numbers - lista di numeri di telefono
Interamente omesso quando nessuno li ha ancora acquistati.
​
object | null
Crediti available e reserved dell’organizzazione. Omesso quando la credenziale non ha un’organizzazione per cui l’API possa risolvere i crediti.

​
syrto_request_person_contacts

Acquista i contatti di una persona. Questo spende i crediti dell’organizzazione.

​
Prima di acquistare

  1. Chiama syrto_get_person_contacts per il credit_cost esatto, e per verificare che per questa persona si possa trovare qualcosa.
  2. Comunica all’utente di chi sono i contatti e quanto costano, e ottieni il suo consenso esplicito a spenderli.
  3. Passa quel costo come expected_credit_cost. L’acquisto viene rifiutato se il prezzo corrente è diverso, il che intercetta un prezzo ormai vecchio - non attesta che qualcuno lo abbia approvato, quindi il passo 2 resta indispensabile.
I controlli su duplicati e prezzo vengono eseguiti immediatamente prima dell’acquisto, non in modo atomico con esso. L’API a monte non accetta un tetto di prezzo, quindi un prezzo che cambia tra il controllo e l’acquisto viene addebitato alla nuova cifra.

​
Quando una ripetizione non costa nulla

Due meccanismi indipendenti determinano se una ripetizione viene addebitata:
  • L’API a monte deduplica un’intenzione di acquisto già inviata - stessa persona e stesso force_new - per 24 ore, restituendo il primo acquisto invece di addebitare di nuovo.
  • Separatamente, questo strumento rifiuta i contatti che l’organizzazione già possiede, che quella finestra sia trascorsa o meno, a meno che force_new non sia true.
Quindi una ripetizione semplice resta protetta anche dopo 24 ore dalla seconda regola, mentre la ripetizione di un’intenzione che già portava force_new: true è protetta solo dalla prima, e acquista di nuovo una volta trascorsa la finestra. Non usare questo strumento per raccogliere contatti ancora in arrivo. I fornitori restituiscono prima le email e poi i numeri di telefono, e syrto_get_person_contacts restituisce il resto senza costi una volta che è arrivato. Se la chiamata va in timeout o fallisce, richiamala con la stessa intenzione di acquisto - stessa persona e stesso force_new. Aggiungere force_new la rende un acquisto diverso, addebitato per intero. expected_credit_cost e language non fanno parte dell’intenzione.

​
Argomenti

​
string
obbligatorio
La persona di cui acquistare i contatti.
​
integer
obbligatorio
Il credit_cost da syrto_get_person_contacts, come mostrato all’utente.
​
boolean
Esegue una nuova ricerca presso il fornitore per una persona i cui contatti l’organizzazione possiede già. Addebita l’intero costo. Predefinito false. Non serve per raccogliere dati in corso di arrivo - quelli sono gratuiti tramite syrto_get_person_contacts.
​
string
"en" per inglese (predefinito) o "it" per italiano.

​
Risposta

​
object
id e name.
​
object | null
status (COMPLETED, oppure IN_PROGRESS mentre altro è in arrivo), emails e phone_numbers. Omesso quando il fornitore non ha trovato nulla.
​
integer
Il prezzo quotato per questo arricchimento, non un addebito confermato - l’API a monte non riporta quanto ha addebitato.0 è l’eccezione ed è certo: un arricchimento che non trova nulla non viene addebitato affatto. Anche un valore positivo può non essere addebitato, se questa chiamata ha ripetuto un acquisto force_new identico entro 24 ore - cosa che viene replicata a monte e non è rilevabile qui.
Il fornitore può non trovare nulla. È una chiamata riuscita e non fatturata: torna senza contatti e con un warning che lo segnala. Significa “non è stato possibile trovare contatti”, non è un errore, e ritentare non cambia il risultato.

​
Esempio

1. Verificare che cosa è disponibile e quanto costa (gratuito):
2. Acquistare, dopo che l’utente ha accettato il costo: