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.

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_name
stringPerson's first name. Required unless full_name is provided.
last_name
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).
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_name
stringPerson's first name.
last_name
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.