❯gtmclidocs

API reference

Waterfall enrichment

Try multiple providers in order until a valid result is found. gtmcli is always step 1 for email. Every result is validated before returning.

TIP

Configure your waterfall and add provider API keys at Dashboard → Waterfall.

Before you start

1Create an API key at Dashboard → Keys while signed into your organization. Personal keys (not linked to an org) cannot use the waterfall endpoints.
2(Optional) Add provider API keys at Dashboard → Waterfall for Findymail, LeadMagic, Prospeo, or Icypeas. Without a configured waterfall, /v1/waterfall/find falls back to gtmcli alone and /v1/waterfall/phone returns not_found.
3Send every request with Authorization: Bearer gtm_live_.... See Authentication for details.

How it works

1gtmcli tries to find the email first (always step 1).
2If not found or low confidence, the next provider is called.
3Every result is validated by gtmcli (if require_validation is on).
4Waterfall stops at the first valid email. Failed lookups are free.

Supported providers

ProviderEmailPhone
gtmcli✓-
Findymail✓✓
LeadMagic✓✓
Prospeo✓✓
Icypeas✓-

Email waterfall

POST/v1/waterfall/find

Parameters

ParameterTypeDescription
first_namereq
stringPerson's first name. Required unless full_name is provided.
last_namereq
stringPerson's last name. Required unless full_name is provided.
full_name
stringFull name (auto-split into first + last).
domainreq
stringCompany domain (e.g. stripe.com).
company_name
stringCompany name (optional, helps some providers).
company_url
stringCompany website URL (optional, helps some providers).
linkedin_url
stringLinkedIn profile URL (optional).
personal_email
stringPersonal email (optional, helps some providers).

Request

curl -X POST https://api.gtmcli.com/v1/waterfall/find \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Satya","last_name":"Nadella","domain":"microsoft.com"}'

Response

200 OKjson
{
  "email": "snadella@microsoft.com",
  "status": "found",
  "provider_used": "gtmcli",
  "confidence": 1,
  "steps": [
    {
      "provider": "gtmcli",
      "email": "snadella@microsoft.com",
      "status": "found",
      "ms": 176,
      "credits": 1.25,
      "own_key": true
    }
  ],
  "total_credits": 1.25,
  "ms": 183
}

Waterfall fallthrough example

When gtmcli does not find the email, the waterfall continues to the next provider:

All providers triedjson
{
  "status": "not_found",
  "steps": [
    { "provider": "gtmcli", "status": "not_found", "ms": 167, "credits": 0 },
    { "provider": "findymail", "status": "not_found", "ms": 461, "credits": 0 },
    { "provider": "leadmagic", "status": "not_found", "ms": 863, "credits": 0 }
  ],
  "total_credits": 0,
  "ms": 1497
}

Phone waterfall

POST/v1/waterfall/phone
ParameterTypeDescription
first_namereq
stringPerson's first name.
last_namereq
stringPerson's last name.
domainreq
stringCompany domain.
linkedin_url
stringLinkedIn profile URL (recommended for phone lookup).
curl -X POST https://api.gtmcli.com/v1/waterfall/phone \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Jeff","last_name":"Tucker","domain":"opflow.io","linkedin_url":"https://linkedin.com/in/jeff-tucker-gtm"}'
Responsejson
{
  "phone": "+1234567890",
  "status": "found",
  "provider_used": "leadmagic",
  "steps": [
    { "provider": "leadmagic", "phone": "+1234567890", "status": "found", "ms": 1731, "credits": 0 }
  ],
  "total_credits": 0,
  "ms": 1745
}

INFO

Phone lookups use your provider API keys directly. gtmcli does not have a phone database yet. LinkedIn URL significantly improves match rates for phone lookups.

Configuration

Configure your waterfall at Dashboard → Waterfall:

Provider order

Drag providers to set the order. gtmcli is always first for email.

API keys

Each provider requires your own API key. Keys are encrypted at rest (AES-256-GCM).

Require validation

When enabled, the waterfall only returns emails that pass gtmcli validation. Unverified results are skipped.

Billing

gtmcli step

1.25 credits if found (1.0 find + 0.25 validation). Free if not found.

External provider step

0.25 credits for gtmcli validation. Provider costs are on your own API key.

Phone waterfall

Zero gtmcli credits. Provider costs are on your own key.

Stop conditions

foundVerified by mail server. Waterfall stops.
valid_catchallHigh confidence on catch-all domain. Waterfall stops.
catchallLow confidence. Waterfall continues. Returned as fallback if no provider finds a verified email.
not_foundNo result. Waterfall continues to next provider.

Errors

401Missing API key. Set the Authorization header to 'Bearer gtm_live_...'.
401Invalid API key. The key was not recognized or has been revoked.
400API key is not linked to an organization. Create a new key at Dashboard → Keys while signed into your org.
400first_name (or full_name), last_name, and domain are required.
402Insufficient credits.
429Rate limit exceeded. Check the Retry-After header.