Skip to main content

DocsREST API and MCP server

Company Data Search API

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

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

Audience Builder: Company Data Search

Business Search Count

Counts the business records that match a filter set. filters takes either named criteria (the filters.* fields below) or the { filterId, values, exclude } list that /ai-criteria returns; send countBy as an array to get several counts at once. 400 names the field at fault, and 429 or 503 mean too many counts are running, so retry shortly.

POSThttps://us-farmvision-new-api.onrender.com/api/v1/business-search/countTry it

In this section

Authentication

Get API key

Bearer token or partner key

Send your GTM Scoop API key (llmcp_…) as a Bearer token. Partner keys issued by our team go in x-api-key instead, never both. Calls with no credentials get 401.

Authorization: Bearer YOUR_API_KEY
x-api-key: YOUR_PARTNER_KEY

Request body

application/json
FieldTypeDescription
filtersbodyobject | arrayNamed criteria (below), or the list form [{ filterId, values, exclude }] from /ai-criteria; each field below names its filterId. A size bucket, range and comparison on the same measure are OR'd; everything else is AND'd. Omit for the whole dataset.
excludeFiltersbodyobjectNamed criteria to leave out (named form only; ignored with the list form). For the true/false fields, true here excludes companies that have it.
geoPlaceScopebodyobject{ "statesNarrowed": string[] }: the selected states that your cities, counties, ZIPs, metros or radius narrow; the other selected states count whole. In the list form, city-outside, county-outside, zipcode-outside and metro-outside then add places in unselected states. Without it, geography is AND'd like any other criteria.
countBybodystring | string[]dedupe (default: unique contacts, deduplicated by phone unless dedupeBy says otherwise), contacts (distinct named contacts), company (distinct businesses), companyName (distinct company names), executives (distinct executives at the matching companies). An array adds data.counts.
filters.statesbodystring[]Full state names or two-letter codes ("Texas", "TX"); District of Columbia is included. Unknown states are a 400. filterId: state.
filters.cityIdsbodystring[]City names, any case (e.g. "Austin"). filterId: city.
filters.countyIdsbodystring[]County names, with or without "County" (e.g. "Travis"). filterId: county.
filters.zipcodeIdsbodystring[]Five-digit ZIP codes (e.g. "78701"). filterId: zipcode.
filters.metroIdsbodystring[]Metro-area ids from the Navigator's geography catalog; /ai-criteria resolves metro names to them. filterId: metro.
filters.radiusbodyobject{ lat, lon, miles }: within that many miles of the point; miles must be positive. filterId: radius, values [lat, lon, miles].
filters.npaNxxbodystring[]Six-digit phone prefixes (area code + exchange), e.g. "512473". filterId: npa-nxx.
filters.areaCodebodystring[]Three-digit area codes, e.g. "512". filterId: area-code.
filters.sicBulkCodes, sicKeywordCodes, sicDrilldownCodesbodystring[]SIC codes or prefixes (2, 4, 6 or 8 digits); a range like "52-59" expands to each prefix. All three lists are OR'd. filterIds: sic-bulk, sic-keyword, sic-drilldown.
filters.naicsBulkCodes, naicsKeywordCodes, naicsDrilldownCodesbodystring[]NAICS codes or prefixes (2 to 6 digits). All three lists are OR'd. filterIds: naics-bulk, naics-keyword, naics-drilldown.
filters.employeeBucketsbodystring[]Employee-count buckets: 1-9, 10-19, 20-49, 50-99, 100-249, 250-499, 500-999, "1000-" (1,000 or more). filterId: employees.
filters.employeeExactRangesbodystring[]"min-max" employees, e.g. "50-75". filterId: employees-exact, values [min, max].
filters.employeeComparisonsbodystring[]"op:value" employees, op = more (at least), less or equal, e.g. "more:50". filterId: minimum-employees, values [op, value].
filters.revenueExactRangesbodystring[]"min-max" annual revenue in dollars. filterId: revenue.
filters.revenueComparisonsbodystring[]"op:value" annual revenue in dollars, op = more (above), less or equal. filterId: minimum-revenue.
filters.yearStartedRangesbodystring[]"min-max" years in business, e.g. "5-20". filterId: year-started.
filters.yearsInBusinessComparisonsbodystring[]"op:value" years in business, e.g. "more:10" (started more than 10 years ago). filterId: minimum-year.
filters.squareFootageComparisonsbodystring[]"op:value" building square footage, e.g. "more:5000". filterId: square-footage.
filters.locationComparisonsbodystring[]"op:value" number of additional locations (0 = a single site), e.g. "more:5". filterId: locations.
filters.statusbodystring[]"0" Stand Alone, "1" Head Quarters, "2" Branch. filterId: status.
filters.legalStatusbodystring[]"1" Proprietorship, "2" Partnership, "3" Corporation. filterId: legal-status.
filters.executiveGroupbodystring[]"CEO", "EFO" (CFO), "DECISION MKR", "HR MGR.", "IT DIR.", "OWNER", "PLANT MGR.", "PRES", "PURCHASING DIR.", "VP SALES", "VP MKT", "UNKNOWN". filterId: executive-group.
filters.executiveTitlebodystring[]Four-character executive title codes from the Navigator's title list (e.g. "E9FK" Accounting). filterId: executive-title.
filters.executiveGenderbodystring[]"m" or "f". filterId: executive-gender.
filters.ethnicLanguage, ethnicCodebodystring[]Two-character codes from the Navigator's language and ethnicity lists (e.g. "A4" Arabic). filterIds: ethnic-language, ethnic-code.
filters.ethnicGroupbodystring[]Group names or letter codes, e.g. "Hispanic" or "Y". filterId: ethnic-group.
filters.ethnicReligionbodystring[]Religion names or letter codes, e.g. "Catholic" or "C". filterId: ethnic-religion.
filters.qualityFiltersbodystring[]100% Phone, 100% Email, 100% Address, 100% Contact Name, 100% Deliverable, Email Verified: every one picked must hold. "All Contacts" turns deduplication off for the dedupe count. filterId: quality-filters.
filters.smallBusiness, subsidiary, publicCompany, hasWebsitebodybooleantrue = must be a small business / a subsidiary / a public company / have a website; false = must not. filterIds: small-business, subsidiary, public-company, url (values ["true"], exclude for false).
filters.dedupeBybodystringWhat the dedupe count deduplicates on: Phone (default), Address, Contact Name or Email. filterId: dedupe-by.

Mounted at

/api/v1/business-search

Sizes a company audience across geography, industry (SIC/NAICS), company size, executives and data quality, or turns plain language into those filters. Same credentials and per-minute limits as the other audience searches; this dataset has no /meta endpoint.

Try it in the playground

Signed out: 10 free tries a day with names hidden. Log in for live data.

Open playground

Related endpoints

All 2 endpoints in this section

Bearer (API key or session token) or a partner x-api-key; a GTM Scoop request with no credentials gets 401.

MethodPathWhat it does
POST/api/v1/business-search/count

Business Search Count

Counts the business records that match a filter set. filters takes either named criteria (the filters.* fields below) or the { filterId, values, exclude } list that /ai-criteria returns; send countBy as an array to get several counts at once. 400 names the field at fault, and 429 or 503 mean too many counts are running, so retry shortly.

34 parameters
  • filters (object | array) Named criteria (below), or the list form [{ filterId, values, exclude }] from /ai-criteria; each field below names its filterId. A size bucket, range and comparison on the same measure are OR'd; everything else is AND'd. Omit for the whole dataset.
  • excludeFilters (object) Named criteria to leave out (named form only; ignored with the list form). For the true/false fields, true here excludes companies that have it.
  • geoPlaceScope (object) { "statesNarrowed": string[] }: the selected states that your cities, counties, ZIPs, metros or radius narrow; the other selected states count whole. In the list form, city-outside, county-outside, zipcode-outside and metro-outside then add places in unselected states. Without it, geography is AND'd like any other criteria.
  • countBy (string | string[]) dedupe (default: unique contacts, deduplicated by phone unless dedupeBy says otherwise), contacts (distinct named contacts), company (distinct businesses), companyName (distinct company names), executives (distinct executives at the matching companies). An array adds data.counts.
  • filters.states (string[]) Full state names or two-letter codes ("Texas", "TX"); District of Columbia is included. Unknown states are a 400. filterId: state.
  • filters.cityIds (string[]) City names, any case (e.g. "Austin"). filterId: city.
  • filters.countyIds (string[]) County names, with or without "County" (e.g. "Travis"). filterId: county.
  • filters.zipcodeIds (string[]) Five-digit ZIP codes (e.g. "78701"). filterId: zipcode.
  • filters.metroIds (string[]) Metro-area ids from the Navigator's geography catalog; /ai-criteria resolves metro names to them. filterId: metro.
  • filters.radius (object) { lat, lon, miles }: within that many miles of the point; miles must be positive. filterId: radius, values [lat, lon, miles].
  • filters.npaNxx (string[]) Six-digit phone prefixes (area code + exchange), e.g. "512473". filterId: npa-nxx.
  • filters.areaCode (string[]) Three-digit area codes, e.g. "512". filterId: area-code.
  • filters.sicBulkCodes, sicKeywordCodes, sicDrilldownCodes (string[]) SIC codes or prefixes (2, 4, 6 or 8 digits); a range like "52-59" expands to each prefix. All three lists are OR'd. filterIds: sic-bulk, sic-keyword, sic-drilldown.
  • filters.naicsBulkCodes, naicsKeywordCodes, naicsDrilldownCodes (string[]) NAICS codes or prefixes (2 to 6 digits). All three lists are OR'd. filterIds: naics-bulk, naics-keyword, naics-drilldown.
  • filters.employeeBuckets (string[]) Employee-count buckets: 1-9, 10-19, 20-49, 50-99, 100-249, 250-499, 500-999, "1000-" (1,000 or more). filterId: employees.
  • filters.employeeExactRanges (string[]) "min-max" employees, e.g. "50-75". filterId: employees-exact, values [min, max].
  • filters.employeeComparisons (string[]) "op:value" employees, op = more (at least), less or equal, e.g. "more:50". filterId: minimum-employees, values [op, value].
  • filters.revenueExactRanges (string[]) "min-max" annual revenue in dollars. filterId: revenue.
  • filters.revenueComparisons (string[]) "op:value" annual revenue in dollars, op = more (above), less or equal. filterId: minimum-revenue.
  • filters.yearStartedRanges (string[]) "min-max" years in business, e.g. "5-20". filterId: year-started.
  • filters.yearsInBusinessComparisons (string[]) "op:value" years in business, e.g. "more:10" (started more than 10 years ago). filterId: minimum-year.
  • filters.squareFootageComparisons (string[]) "op:value" building square footage, e.g. "more:5000". filterId: square-footage.
  • filters.locationComparisons (string[]) "op:value" number of additional locations (0 = a single site), e.g. "more:5". filterId: locations.
  • filters.status (string[]) "0" Stand Alone, "1" Head Quarters, "2" Branch. filterId: status.
  • filters.legalStatus (string[]) "1" Proprietorship, "2" Partnership, "3" Corporation. filterId: legal-status.
  • filters.executiveGroup (string[]) "CEO", "EFO" (CFO), "DECISION MKR", "HR MGR.", "IT DIR.", "OWNER", "PLANT MGR.", "PRES", "PURCHASING DIR.", "VP SALES", "VP MKT", "UNKNOWN". filterId: executive-group.
  • filters.executiveTitle (string[]) Four-character executive title codes from the Navigator's title list (e.g. "E9FK" Accounting). filterId: executive-title.
  • filters.executiveGender (string[]) "m" or "f". filterId: executive-gender.
  • filters.ethnicLanguage, ethnicCode (string[]) Two-character codes from the Navigator's language and ethnicity lists (e.g. "A4" Arabic). filterIds: ethnic-language, ethnic-code.
  • filters.ethnicGroup (string[]) Group names or letter codes, e.g. "Hispanic" or "Y". filterId: ethnic-group.
  • filters.ethnicReligion (string[]) Religion names or letter codes, e.g. "Catholic" or "C". filterId: ethnic-religion.
  • filters.qualityFilters (string[]) 100% Phone, 100% Email, 100% Address, 100% Contact Name, 100% Deliverable, Email Verified: every one picked must hold. "All Contacts" turns deduplication off for the dedupe count. filterId: quality-filters.
  • filters.smallBusiness, subsidiary, publicCompany, hasWebsite (boolean) true = must be a small business / a subsidiary / a public company / have a website; false = must not. filterIds: small-business, subsidiary, public-company, url (values ["true"], exclude for false).
  • filters.dedupeBy (string) What the dedupe count deduplicates on: Phone (default), Address, Contact Name or Email. filterId: dedupe-by.
Try Business Search Count in the Playground
POST/api/v1/business-search/ai-criteria

Business AI Criteria

Turns a plain-language request into Business filters, returned in the list form /count accepts as-is (it returns filters, not a count). Industry phrases become SIC or NAICS codes, place names are resolved, and anything it couldn't map comes back in unmatched. Uses the AI criteria budget shared with the other audience searches (429 AI_RATE_LIMIT or AI_DAILY_LIMIT); 502 means generation failed: retry.

2 parameters
  • text (string, required) The request in plain language, up to 2,000 characters.
  • hintStates (string[]) States already selected. Helps resolve a city, county or metro name that exists in several states.
Try Business AI Criteria in the Playground

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