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.
- Base URL:
https://api.gtmmaxing.com - OpenAPI spec:
/openapi.json - Tool catalog with live JSON schemas:
GET /v1/agent/tools
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:
status | Meaning | What to do |
|---|---|---|
completed | Done. | Read rows, or fetch every row with gtm_results. |
not_found | Nothing matched. | Nothing was charged. |
running | The job continues on the server. | Poll gtm_results with run_id every 4 seconds. |
quote | Answer to a dry_run. | Show quote to the user, then run with max_credits. |
refused | Not run, or stopped early. | Read reason; nothing beyond cost was charged. |
error | The 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
| Field | Meaning |
|---|---|
summary | One plain sentence you can show to your user as is. |
cost | Credits this call charged. |
balance | Credits left on the account. |
quote | Most credits the request could cost. |
run_id | Handle for the full results. |
total | Rows kept on the server for this run. |
columns, rows | Up to 5 preview rows. Look values up by column name, not position. |
next | The suggested next call, as { tool, args }. |
link | A download link, such as a run’s CSV. |
replayed | true when an idempotency_key replayed an earlier call for free. |
Credits and spending safety
A call can never spend more than its max_credits.
- Every paid call needs
max_credits. Without it, the call is refused and you get a free quote instead. dry_run: trueis always free. Use it to show users a price before they confirm.- Misses are free. You pay for results, not attempts.
- Repeats are free. Looking up a profile your account already paid for costs nothing.
idempotency_keymakes retries safe. Resending the same key replays the original answer for free, so timeouts and retries never double-charge. Use a stable ID from your system, such as a CRM record ID: 8 to 128 printable ASCII characters with no spaces.- Each token has its own credit cap. New tokens default to 1,000 credits per day, and
gtm_accountreports what is left.
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
| Tool | What it does | Price |
|---|---|---|
gtm_find_contacts | Work 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_list | People 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_company | Company profile and website sales brief for one domain. | Up to 2 credits. |
gtm_find_leads | A 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_workspace | Your saved ICP and exclusions, used by lead searches. | Free. |
gtm_find_signals | Companies hiring for a role in the past 30 days, with website and size. | 1 credit per non-empty search. |
gtm_tools | Search, 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_results | Rows, job status or CSV link for a run. | Free. |
gtm_account | Balance, 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
| HTTP | Body | Meaning |
|---|---|---|
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. |
5xx | Retry 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.
- Discovery:
https://gtmmaxing.com/.well-known/oauth-authorization-server - Authorize:
https://gtmmaxing.com/oauth/authorize(authorization code with PKCES256) - Token and refresh:
https://gtmmaxing.com/oauth/token - Device flow, for command-line tools:
https://gtmmaxing.com/oauth/device_authorization - Client registration:
https://gtmmaxing.com/oauth/register(RFC 7591) - Scopes:
gtm:readto read account and results,gtm:runto spend credits
Send the access token as Authorization: Bearer <token>, exactly like an API key.
Recipes
- Clay: find and verify emails in a table column
- Google Sheets:
=GTM_EMAIL(A2)and bulk enrichment - n8n: find emails in any workflow
- Let your agent buy its own credits: pay through Uniswap from the agent’s wallet when it runs out.
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.