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.
Entrambi gli strumenti richiedono un utente connesso. Su una connessione autenticata con una chiave API di organizzazione nessuno dei due viene proposto, e chiamarne uno restituisce un errore.
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 non è stato possibile leggere il saldo - assente significa “non noto”, mai “esauriti” - e in quel caso warning lo segnala.

​
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.
Entrambi gli strumenti restituiscono accanto a result i campi restituiti da ogni strumento. Qui display_title è il nome della persona, e subtitle indica che cosa contiene la risposta: Contact availability o Contacts held nella lettura, Contacts purchased o No contacts found nell’acquisto.

​
Esempio

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