Reference
Response format
success flag. Payloads sit under data; failures carry a readable message.{
"success": true,
"data": { "count": 3841 }
}{
"success": false,
"message": "Not authorized, no token"
}Base URL
https://us-farmvision-new-api.onrender.comThe envelope
| Field | Present | Meaning |
|---|---|---|
success | Always | true when the request did what it asked, false otherwise. Check this before reading anything else. |
data | On success | The payload: an object for a single item or a count, an array for a list. |
message | On errors, and some successes | Readable text you can show a person. |
field, invalidValues | Search validation errors (400) | The request field at fault, and the values it did not recognise. |
code | 500 errors, and some others | A 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_tokenon success,erroranderror_descriptionon failure.
{
"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, andRetry-Afterwhen you are over the limit. - A session token sent as a Bearer token gets a fresh one in
X-New-Access-Tokenwhen it is close to expiring. - Send an
Idempotency-Keyheader (up to 128 visible characters; a UUID fits) onPOST /api/v1/billing/checkout-session,/confirm-payment,/change-plan,POST /api/v1/purchases/checkout-linkand the enrichment and analysis job starts to retry them safely. For 24 hours a repeat returns the first answer withIdempotent-Replayed: true, 409IDEMPOTENCY_IN_PROGRESSwhile the first is still running, and 422IDEMPOTENCY_KEY_REUSEDif the request differs. A first attempt that failed with a 5xx keeps nothing, so send the same key again.POST /api/v1/billing/claim-autopaytakes a key of 16 to 128 letters, digits, hyphens or underscores and returns the order that key first placed.
Read a response in code
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"))// 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);