Skip to main content

DocsREST API and MCP server

API response format

Endpoints, auth and live samples for Audience Builder, Connect Data and CRM sync.

Base URLhttps://us-farmvision-new-api.onrender.com

Reference

Response format

Every JSON response has a top-level success flag. Payloads sit under data; failures carry a readable message.
Success
{
  "success": true,
  "data": { "count": 3841 }
}
Failure
{
  "success": false,
  "message": "Not authorized, no token"
}

Base URL

https://us-farmvision-new-api.onrender.com

The envelope

FieldPresentMeaning
successAlwaystrue when the request did what it asked, false otherwise. Check this before reading anything else.
dataOn successThe payload: an object for a single item or a count, an array for a list.
messageOn errors, and some successesReadable text you can show a person.
field, invalidValuesSearch validation errors (400)The request field at fault, and the values it did not recognise.
code500 errors, and some othersA stable string for code to branch on, such as TIMEOUT, AI_DAILY_LIMIT or MAPPING_COMBO_INCOMPLETE.

Error bodies

A 4xx answer is { success: false, message }, plus field and invalidValues when a search filter is wrong, and a code on some errors (a 422 mapping error also lists what is missing). A 500 answer adds a code: TIMEOUT and NETWORK mean a dependency was slow or unreachable and the request is worth retrying, INTERNAL means something else failed. An unknown path answers 404 {"success": false, "message": "Not found"}.

  • Exception: when the per-IP limit or a plan's per-minute search limit is reached, the 429 body is plain text, "Too many requests, please try again later." Read the body as text before parsing it as JSON.
  • Exception: the OAuth token endpoint, POST /api/v1/gtmscoop/oauth/token, follows the OAuth standard: access_token on success, error and error_description on failure.
500 · server error
{
  "success": false,
  "code": "TIMEOUT",
  "message": "This is taking longer than expected. Please try again."
}

Lists and pagination

Most list endpoints return the whole list in data, with a cap: up to 100 uploads or match jobs, and up to 200 saved criteria. Run results return every row in one response. Three endpoints page through larger sets: HubSpot contacts take limit (1 to 100, default 25) and an after cursor and return nextAfter; Salesforce records take limit (1 to 200, default 50) and offset; purchase previews take limit and offset.

Requests and headers

  • Send request bodies as JSON with Content-Type: application/json. Compressed request bodies are refused with 415.
  • Bodies have size limits: 16 KB on the sign-in routes, 2 MB on most Connect Data routes and 60 MB on uploads. Anything larger gets 413.
  • Rate-limited routes send RateLimit-* headers, and Retry-After when you are over the limit.
  • A session token sent as a Bearer token gets a fresh one in X-New-Access-Token when it is close to expiring.
  • Send an Idempotency-Key header (up to 128 visible characters; a UUID fits) on POST /api/v1/billing/checkout-session, /confirm-payment, /change-plan, POST /api/v1/purchases/checkout-link and the enrichment and analysis job starts to retry them safely. For 24 hours a repeat returns the first answer with Idempotent-Replayed: true, 409 IDEMPOTENCY_IN_PROGRESS while the first is still running, and 422 IDEMPOTENCY_KEY_REUSED if the request differs. A first attempt that failed with a 5xx keeps nothing, so send the same key again. POST /api/v1/billing/claim-autopay takes a key of 16 to 128 letters, digits, hyphens or underscores and returns the order that key first placed.

Read a response in code

Python
import os
import requests

res = requests.post(
    "https://us-farmvision-new-api.onrender.com/api/v1/business-search/count",
    json={"filters": {"states": ["Texas"]}},
    headers={"Authorization": f"Bearer {os.environ['GTMSCOOP_API_KEY']}"},
    timeout=60,
)
try:
    body = res.json()
except ValueError:  # a plain-text 429 from the per-IP or per-minute limit
    body = {"success": False, "message": res.text}
if body["success"]:
    print("count:", body["data"]["count"])
else:
    print(res.status_code, body.get("code"), body["message"], body.get("field"))
Node.js
// Save as read.mjs (top-level await needs an ES module), Node.js 18 or later.
const res = await fetch("https://us-farmvision-new-api.onrender.com/api/v1/business-search/count", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GTMSCOOP_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ filters: { states: ["Texas"] } }),
});
const text = await res.text();
let body;
try {
  body = JSON.parse(text);
} catch {
  body = { success: false, message: text }; // a plain-text 429 from the per-IP or per-minute limit
}
if (body.success) console.log("count:", body.data.count);
else console.error(res.status, body.code, body.message, body.field);

Related

Cookies on GTM Scoop

Essential cookies keep you signed in and the site secure, and are always on. Optional cookies (Google Analytics) help us understand how the site is used. They are on by default, except in the EU/EEA, the UK and Switzerland, where they stay off until you choose Accept All Cookies; choose Essential Cookies Only to turn them off. We do not use advertising cookies and we do not sell or share your personal information. The site works the same whichever you choose. We keep a record of your choice with the date, your IP address and the page you were on. Cookie Policy · Privacy Policy