Skip to main content
Syrto can buy a person’s business email addresses and direct phone numbers from external data providers. They are not part of the registry record, so they cost credits. Two tools cover them: Person IDs come from syrto_find_person, or from the person_id on an officer, shareholder or beneficial owner returned by syrto_get_company_structure. The structure route is the more precise of the two - syrto_find_person is a name search, so it can land on a namesake.
Purchased contacts belong to the whole organization, not to the person who bought them. A colleague may already have paid for them - syrto_get_person_contacts is how you find out, and it costs no credits.

​
syrto_get_person_contacts

Reports the contact details held for a person and the cost of buying them. Spends no contact credits and is safe to call repeatedly. Use it:
  • Before every purchase. It supplies the cost to confirm with the user, and says whether anything can be found for this person at all.
  • To read contacts already bought.
  • To collect data that is still arriving. Providers return emails first and phone numbers afterwards, so contacts with status IN_PROGRESS are incomplete for a short while. Calling this again is how the rest arrives - buying again would pay twice for it.

​
Arguments

​
string
required
The person ID, from syrto_find_person or from a person_id in syrto_get_company_structure.
​
string
"en" for English (default) or "it" for Italian.

​
Returns

​
object
id (the person_id you passed) and name.
​
object
What can be bought, not what is held:
  • has_email - an email address can be found
  • has_direct_phone - a direct phone number can be found
  • credit_cost - what buying it would cost
Both flags false means nothing can be found for this person at any price.
​
object | null
What the organization has already bought:
  • status - COMPLETED, or IN_PROGRESS while more is still arriving
  • emails - list of email addresses
  • phone_numbers - list of phone numbers
Omitted entirely when nobody has bought them yet.
​
object | null
available and reserved credits for the organization. Omitted when the credential has no organization the API can resolve credits for.

​
syrto_request_person_contacts

Buys a person’s contact details. This spends the organization’s credits.

​
Before buying

  1. Call syrto_get_person_contacts for the exact credit_cost, and to check anything can be found for this person at all.
  2. Tell the user whose contacts these are and what they cost, and get their explicit agreement to spend it.
  3. Pass that cost as expected_credit_cost. The purchase is refused if the live price differs, which catches a stale price - it does not establish that anyone agreed to it, so step 2 still stands on its own.
The duplicate and price checks run just before the purchase, not atomically with it. The upstream API takes no price ceiling, so a price that moves between the check and the purchase is charged at the new figure.

​
When a repeat costs nothing

Two independent things decide whether a repeat is charged:
  • The upstream API deduplicates a dispatched purchase intent - the same person and force_new - for 24 hours, returning the first purchase rather than charging again.
  • Separately, this tool refuses contacts the organization already holds, whether or not that window has passed, unless force_new is true.
So a plain repeat stays protected after 24 hours by the second rule, while a repeat of an intent that already carried force_new: true is protected only by the first, and buys again once the window passes. Do not call this tool to collect contacts that are still arriving. Providers return emails first and phone numbers afterwards, and syrto_get_person_contacts returns the rest at no cost once they land. If the call times out or fails, call it again with the same purchase intent - the same person and force_new. Adding force_new makes it a different purchase, charged in full. expected_credit_cost and language are not part of the intent.

​
Arguments

​
string
required
The person to buy contact details for.
​
integer
required
The credit_cost from syrto_get_person_contacts, as shown to the user.
​
boolean
Run a fresh provider lookup for a person whose contacts the organization already has. Charges in full. Default false. Not for collecting in-progress data - that is free through syrto_get_person_contacts.
​
string
"en" for English (default) or "it" for Italian.

​
Returns

​
object
id and name.
​
object | null
status (COMPLETED, or IN_PROGRESS while more is arriving), emails and phone_numbers. Omitted when the provider found nothing.
​
integer
The price quoted for this enrichment, not a confirmed debit - the upstream API does not report what it charged.0 is the exception and is certain: an enrichment that finds nothing is not charged for at all. A positive value can also end up uncharged, if this call repeated an identical force_new purchase within 24 hours - which is replayed upstream and is not detectable here.
The provider may find nothing. That is a successful, unbilled call: it comes back with no contacts and a warning saying so. It is “no contacts could be found”, not an error, and retrying will not change it.

​
Example

1. Check what is available and what it costs (free):
2. Buy, after the user agreed to the cost: