Skip to main content

DocsREST API and MCP server

HubSpot Contacts API

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

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

HubSpot Contacts

Search HubSpot Contacts

Lists contacts, newest first, using HubSpot's contact search. Page with nextAfter, which is null on the last page.

GEThttps://us-farmvision-new-api.onrender.com/api/v1/hubspot/contacts?search=acme&limit=25Try it

In this section

Authentication

Get API key

Bearer token

Send your GTM Scoop API key (llmcp_…) or a signed-in session token as a Bearer token.

Authorization: Bearer YOUR_API_KEY

Query parameters

FieldTypeDescription
searchquerystringFree-text search across HubSpot's default searchable contact properties. Trimmed and cut to 100 characters.
limitqueryintegerContacts per page, 1 to 100. Default 25.
afterquerystringThe nextAfter value from the previous page.

Mounted at

/api/v1/hubspot

Reads and writes contacts and leads in the connected HubSpot portal. Every call returns 401 with disconnected: true when there is no connection or its token can no longer be refreshed; other HubSpot errors come back as 502.

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 6 endpoints in this section

Bearer token plus an active HubSpot connection; deletes, uploads and lead write-back need a signed-in web session.

MethodPathWhat it does
GET/api/v1/hubspot/contacts

Search HubSpot Contacts

Lists contacts, newest first, using HubSpot's contact search. Page with nextAfter, which is null on the last page.

3 parameters
  • search (string) Free-text search across HubSpot's default searchable contact properties. Trimmed and cut to 100 characters.
  • limit (integer) Contacts per page, 1 to 100. Default 25.
  • after (string) The nextAfter value from the previous page.
Try Search HubSpot Contacts in the Playground
POST/api/v1/hubspot/contacts/delete-all

Delete All HubSpot Contacts

Deletes (archives in HubSpot) up to 10,000 contacts that match search; with no search it archives every contact in the portal, up to 10,000. The request runs until they are all archived and reports the counts.

1 parameter
  • search (string) Archive only contacts matching this HubSpot search text. Max 100 characters.
POST/api/v1/hubspot/leads/delete-all

Delete All HubSpot Leads

The same as Delete All HubSpot Contacts, for HubSpot Lead records (up to 10,000; every lead when search is empty). 403 when the connection has no access to Leads, which needs Sales Hub Professional or Enterprise.

1 parameter
  • search (string) Archive only leads matching this HubSpot search text. Max 100 characters.
POST/api/v1/hubspot/upload

Create HubSpot Contacts

Creates one HubSpot contact per row, for up to 5,000 rows (extra rows are ignored). Only the listed properties are kept and lastname is required. Each row is reported on its own, so the call returns 200 even when rows fail; disconnected: true means the connection dropped part-way and the remaining rows were not tried.

1 parameter
  • rows (array, required) Objects of HubSpot property to value; the first 5,000 are used. Allowed: firstname, lastname (required), company, email, phone, mobilephone, website, description, address, city, state, zip, country, jobtitle, lifecyclestage. Other keys and empty values are dropped.
POST/api/v1/hubspot/enrich-sync

Sync HubSpot Contacts for Enrichment

Copies HubSpot contacts into a new Connect Data upload, ready to map and enrich, named "HubSpot Contacts" (then "HubSpot Contacts (2)" and so on). Mode all pages through the newest contacts, optionally filtered by search, up to 5,000; mode selected reads the given contact ids. The upload keeps each contact's HubSpot Id column, which lets a later lead write-back attach to the same contact; 400 when no contacts are found, and GTM Scoop accounts can run 20 CRM syncs per hour.

4 parameters
  • mode (string) "all" (default; any other value counts as all) or "selected".
  • ids (array) Required for selected mode: HubSpot contact ids, at most 5,000. Selected mode with no ids fails.
  • search (string) All mode only: HubSpot search text to filter the contacts.
  • businessContext (object) Context stored with the upload for later AI analysis: { companyName, website, businessContext, updatedAt }, all strings. At most 4,000 characters in total; a larger value is refused.
POST/api/v1/hubspot/writeback-leads

Write Matched Rows to HubSpot as Leads

Creates a HubSpot Lead for each matched row of an analysis run, up to 10,000, linked to the existing contact found by the row's HubSpot Id or email when there is one; rows are chosen as in the Salesforce write-back, and a HubSpot Id column is trusted only on uploads made by HubSpot enrich-sync. If the portal cannot create Leads (it needs Sales Hub Professional or Enterprise), matching existing contacts are marked as leads instead (lifecycle stage lead, lead status New, nothing else changed): the response then has fallback: true and a fallbackNote, and rows with no matching contact are counted in skipped. 400 if there is nothing to write.

4 parameters
  • runId (string) The analysis run whose rows to write. Send runId, uploadId or savedListId.
  • mode (string) "ai" (default; any other value counts as ai) or "data": which of the run's results to try first. Used with runId.
  • uploadId (string) An upload: its run is written when runId is not sent, and its own rows are the last fallback. With runId, the run's own upload is used if this one differs.
  • savedListId (string) A saved results list to write instead of a run (404 if it is not this account's).

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