gtm-router 1.0.0

Official Python SDK for the GTM Router API — email enrichment, phone finding, bulk operations, and more.

GTM Router Python SDK

Official Python client for the GTM Router API — email enrichment, phone finding, bulk operations, and more.

Installation

pip install gtm-router

Local development (from this repo):

pip install -e packages/python-sdk

Quick Start

from gtm_router import GTMRouter

client = GTMRouter()  # reads GTM_ROUTER_API_KEY from env

# Find a single email
result = client.email.find(
    first_name="John",
    last_name="Doe",
    domain="acme.com"
)
print(result)

# Bulk email enrichment (auto-polls until done, fetches all results)
job = client.bulk.email_find(
    records=[
        {"first_name": "John", "last_name": "Doe", "domain": "acme.com"},
        {"first_name": "Jane", "last_name": "Smith", "domain": "example.com"},
    ],
    mode="fastest"
)

print(f"Status: {job.status}")
print(f"Total: {job.total_records}, Found: {job.completed_records}")

for r in job.results:
    output = r.get("output") or {}
    if r["status"] == "success" and output.get("found"):
        print(f"  {output['email']}")

Configuration

client = GTMRouter(
    api_key="sk_live_xxx",              # or set GTM_ROUTER_API_KEY env var
    base_url="http://localhost:3000/api/v1",  # or set GTM_ROUTER_API_URL env var
    timeout=30,                         # request timeout in seconds
    max_retries=2,                      # retry count for 5xx / connection errors
    poll_interval=3.0,                  # seconds between poll requests
    poll_timeout=300.0,                 # max seconds to wait for job completion
)

Resources

client.email

• find(first_name, last_name, domain, mode="fastest", verify=False)
• verify(email, mode="fastest")

client.phone

• find(email=None, linkedin_url=None, first_name=None, last_name=None, domain=None, mode="fastest")

client.bulk

• email_find(records, mode="fastest") — returns BulkJob with .results
• email_verify(records, mode="fastest") — returns BulkJob with .results
• phone_find(records, mode="fastest") — returns BulkJob with .results
• get(job_id) — get job status
• get_results(job_id, limit=100, offset=0) — paginated results
• cancel(job_id) — cancel a running job
• list(status=None, limit=20, offset=0) — list all jobs

client.account

• get() — account info and balance

Error Handling

from gtm_router import GTMRouter, GTMRouterError, RateLimitError, InsufficientBalanceError

client = GTMRouter()

try:
    job = client.bulk.email_find(records=records, mode="fastest")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except InsufficientBalanceError:
    print("Not enough credits")
except GTMRouterError as e:
    print(f"API error: {e.code} — {e.message}")

License

MIT