Enrichment Tools

Enrichment tools all share a shape: you pass an identifier you already have, and you get back an attribute you don’t. A name plus a domain becomes a verified email address. A name becomes a set of social handles. A free-text location becomes coordinates.

They are grouped together because they behave alike, not because they share a data source. Each answers in one call, none of them paginate, and each returns a status field that tells you whether the answer is trustworthy rather than handing back a guess. When enrichment can’t confirm something, it says so — that contract is the reason these tools are safe to run across a list unattended.

Tools

get_email

$
curl -X POST https://api.gtm-tools.sh/api/v0/get_email \
>
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "name": "Justin Mares",
>
    "domain": "kettleandfire.com",
>
    "input_parameters": {"source": "linkedin"}
>
  }'

1
{
2
  "email": "justin@kettleandfire.com",
3
  "status": "ok",
4
  "domain": "kettleandfire.com",
5
  "input_parameters": {"source": "linkedin"}
6
}

Response fields

When the domain is catch-all

Catch-all domains accept SMTP traffic for every local-part, so verification can’t disambiguate the true address. Rather than hand back a guess that might silently bounce, get_email stays strict:

1
{ "email": null, "status": "not_found", "reason": "catch_all", "domain": "acme.com" }

If you want to act anyway, generate the dominant pattern yourself and treat it as a hypothesis: cross-check against LinkedIn, and prefer a channel where being wrong is cheap. Every reason value and what to do about it is on Why is get_email returning not_found?, and the batching and retry patterns are in Outbound.

How verification works

get_email does three things:

1. Generate candidates. Every common pattern is produced from the name (justin@, justinmares@, justin.mares@, j.mares@, jmares@, etc.).
2. Verify via SMTP. Each candidate is probed against the domain’s MX records: the verifier speaks SMTP, issues RCPT TO, and observes the server’s response, all without DATA, so no mail is ever sent.
3. Return the first deliverable hit. Catch-all domains are detected by probing a known-bogus address first; if the server accepts it, the result comes back as not_found with reason: "catch_all" rather than a best guess.

This adds 2–5 seconds of latency per call.

get_social_profiles

get_social_profiles answers a different question: given a person’s name, which accounts across LinkedIn, X, Instagram and TikTok belong to them?

$
curl -X POST https://api.gtm-tools.sh/api/v0/get_social_profiles \
>
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{"name": "Andrei Negrau", "domain": "siena.cx"}'

It reads search-engine snippets only. There is no platform login and no profile fetch, which is why it works on Instagram and TikTok at all: their profile pages are hostile to anonymous requests, but their snippets are indexed.

Always pass context when you have it. A bare common name returns whoever ranks highest in search, which may be a different person entirely. Any company, domain, location or keywords you supply must be corroborated in a candidate’s own snippet before that candidate is accepted, so context does not just re-rank the results, it filters them.

The strongest signal is a brand appearing on two different platforms. That is what resolves a handle bearing no resemblance to the person’s name, such as a personal brand or a nickname account.

Response fields

Platforms with no confident match are omitted rather than guessed, so treat a missing key as “not found”, not as an error.

Reach for get_linkedin_profile_url instead when you only need LinkedIn and you already know the company domain: it is cached, so a repeat lookup is instant.

get_coordinates

get_coordinates forward-geocodes any free-text location — a street address, city, region, landmark or country — to a latitude/longitude using global OpenStreetMap data. At 1 credit it is the cheapest tool in the catalog.

$
curl -X POST https://api.gtm-tools.sh/api/v0/get_coordinates \
>
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{"location": "1600 Amphitheatre Parkway, Mountain View, CA"}'

1
{
2
  "status": "ok",
3
  "location": "1600 Amphitheatre Parkway, Mountain View, CA",
4
  "lat": 37.4224858,
5
  "lng": -122.0855846,
6
  "formatted": "Google Building 41, 1600 Amphitheatre Parkway, Mountain View, CA 94043, United States of America",
7
  "country": "United States",
8
  "city": "Mountain View",
9
  "result_type": "amenity",
10
  "confidence": 1
11
}

Response fields

formatted and result_type together are how you catch a wrong answer. A location of "Springfield" resolves, but result_type: "city" with a formatted naming the wrong state tells you the input was ambiguous rather than the geocoder wrong. On try_again_later the upstream geocoder was rate-limited; retry the same input.

Next steps