GTMMAXINGby BAGS

Developers

GTMMAXING API

Add work emails, mobile numbers, lead lists, hiring signals and company research to your product, spreadsheet or workflow. One HTTPS API, pay-as-you-go credits, and no supplier accounts to manage.

The same tools power the GTMMAXING web app, the MCP server and the gtm CLI, so anything you can do there you can do here.

Quickstart

1. Create an API key

Sign in and open API keys. Name a token, set its credit cap, click Create token, and copy it. New accounts start with 10 free credits.

2. Check your balance (free)

export GTM_API_KEY=...

curl -s https://api.gtmmaxing.com/v1/agent/tools/gtm_account \
  -H "Authorization: Bearer $GTM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

3. Get a free quote

Every paid tool accepts dry_run: true. Nothing runs and nothing is charged.

curl -s https://api.gtmmaxing.com/v1/agent/tools/gtm_find_contacts \
  -H "Authorization: Bearer $GTM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"people":["https://www.linkedin.com/in/satyanadella"],"verify":true,"dry_run":true,"max_credits":0}'
{
  "answer": {
    "status": "quote",
    "summary": "This would cost at most 3 credits; nothing was sent.",
    "quote": 3,
    "cost": 0,
    "balance": 393,
    "next": { "tool": "gtm_find_contacts", "args": { "people": ["https://www.linkedin.com/in/satyanadella"], "find": ["email"], "verify": true, "max_credits": 3 } }
  }
}

4. Run it with a budget

Send the same body with max_credits set to the most you are willing to spend, and an idempotency_key.

curl -s https://api.gtmmaxing.com/v1/agent/tools/gtm_find_contacts \
  -H "Authorization: Bearer $GTM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"people":["https://www.linkedin.com/in/satyanadella"],"verify":true,"max_credits":3,"idempotency_key":"crm-contact-8812"}'
{
  "answer": {
    "status": "completed",
    "summary": "Found 1 of 1 emails: 1 deliverable.",
    "run_id": "run_FO9InN2-HAH9K1sg",
    "cost": 3,
    "balance": 390,
    "total": 1,
    "label": "contacts",
    "columns": ["name", "email", "verdict"],
    "rows": [["Satya Nadella", "s***@microsoft.com", "deliverable"]],
    "next": { "tool": "gtm_results", "args": { "run_id": "run_FO9InN2-HAH9K1sg", "format": "csv" } }
  },
  "text": "summary: Found 1 of 1 emails: 1 deliverable.\nstatus: completed\n..."
}

That is the whole integration. Everything below is detail.

How calls work

Every tool is one endpoint: POST /v1/agent/tools/{tool} with a JSON body. The response is always { "answer": {...}, "text": "..." }. text is the same answer in compact TOON form, handy for LLM prompts. Send Accept: text/plain to get only the text. If you are building an integration, send X-GTM-Source: <your-product> so we can attribute usage and reach out when something changes.

Quotes and refusals are normal 200 answers, not HTTP errors. Always branch on answer.status:

statusMeaningWhat to do
completedDone.Read rows, or fetch every row with gtm_results.
not_foundNothing matched.Nothing was charged.
runningThe job continues on the server.Poll gtm_results with run_id every 4 seconds.
quoteAnswer to a dry_run.Show quote to the user, then run with max_credits.
refusedNot run, or stopped early.Read reason; nothing beyond cost was charged.
errorThe run failed.Retry with the same idempotency_key.

Common reason values are max_credits_required, over_max_credits, over_agent_cap, approval_required, insufficient_credits, invalid_input, temporarily_unavailable, partial_failure and unknown_tool. An invalid_input summary names the field that failed, for example more than 100 people in one call. On a refusal, fields lists what the call does accept.

Answer fields

FieldMeaning
summaryOne plain sentence you can show to your user as is.
costCredits this call charged.
balanceCredits left on the account.
quoteMost credits the request could cost.
run_idHandle for the full results.
totalRows kept on the server for this run.
columns, rowsUp to 5 preview rows. Look values up by column name, not position.
nextThe suggested next call, as { tool, args }.
linkA download link, such as a run’s CSV.
replayedtrue when an idempotency_key replayed an earlier call for free.

Credits and spending safety

A call can never spend more than its max_credits.

Need to price a large batch without listing every row? gtm_account takes {"quote": {"capability": "email-finder", "count": 5000}}.

Long jobs and full results

Large batches can answer status: running. Poll gtm_results with the run_id every 4 seconds until the status changes. Polling is free and also moves the job forward.

The answer previews at most 5 rows. To get every row, call gtm_results with "format": "csv" and download answer.link:

curl -s https://api.gtmmaxing.com/v1/agent/tools/gtm_results \
  -H "Authorization: Bearer $GTM_API_KEY" -H "Content-Type: application/json" \
  -d '{"run_id":"run_FO9InN2-HAH9K1sg","format":"csv"}'

The contacts CSV has one row per person, misses included: name,title,email,verdict,url,status. Match rows back to your records by url. The link is pre-signed, so treat it like a secret.

Tools

ToolWhat it doesPrice
gtm_find_contactsWork emails or mobiles by LinkedIn URL, {name, company} pairs, or a list run_id. Up to 100 people per call.1 credit per email found, 5 per mobile, 2 more per verified email. Misses free.
gtm_build_listPeople by title and location, decision-makers at a company domain, or local businesses by type and location.2 credits per people search, 1 per local search. Empty lists free.
gtm_research_companyCompany profile and website sales brief for one domain.Up to 2 credits.
gtm_find_leadsA target number of new leads with emails and why each fits, from your ICP and one optional signal.Normal tool prices, never past max_credits.
gtm_workspaceYour saved ICP and exclusions, used by lead searches.Free.
gtm_find_signalsCompanies hiring for a role in the past 30 days, with website and size.1 credit per non-empty search.
gtm_toolsSearch, describe or run any catalog capability: LinkedIn activity, profile finder, email verification, Google search, X and Reddit search, SEO/AEO audit and more.Per capability; describe is free.
gtm_resultsRows, job status or CSV link for a run.Free.
gtm_accountBalance, key cap, recent spend, batch quotes.Free.

Exact input schemas are in /openapi.json and the live catalog at GET /v1/agent/tools. To see what a catalog capability accepts, call gtm_tools with {"action":"describe","capability":"linkedin-activity"}.

Errors and rate limits

HTTPBodyMeaning
400{"error":"invalid_json"}The body is not valid JSON.
401{"error":"invalid_token"}Missing, wrong or revoked token.
403{"error":"insufficient_scope"}The token can read but not spend. Create a new one.
413{"error":"request_too_large"}Body over 64 KB. Split it into smaller calls.
429{"error":"rate_limited"}Rate limited. Wait Retry-After seconds and resend the same body.
5xxRetry with backoff and the same idempotency_key.

Build an app on GTMMAXING (OAuth)

If your product lets its own users connect their GTMMAXING account, use OAuth instead of asking them for a key. They spend their own credits, and you never handle billing.

Send the access token as Authorization: Bearer <token>, exactly like an API key.

Recipes

Building with an AI agent instead? Connect the MCP server at https://gtmmaxing.com/mcp or install the CLI with npm install -g gtmmaxing. See Add to your agent.