Connectors › HubSpot

HubSpot contact search

Source HubSpot contacts via the CRM v3 Search API, filtered by one HAS_PROPERTY predicate — reproduce a list's membership server-side; cursor pagination, standard portal properties only.

Connector	`hubspot/contact-search`
Role	source
Records	person
Tier	verified since 2026-08-30
Credential	`HUBSPOT_ACCESS_TOKEN` stored once with `gtme secret set HUBSPOT_ACCESS_TOKEN`
Cost	$0
Calls	`POST https://api.hubapi.com/crm/v3/objects/contacts/search`
Source	github.com/gtme-run/gtme-bindings/hubspot-contact-search

Use it

Install it from the registry. Nothing installs unverified: the fixtures run offline first.

gtme adapters add github.com/gtme-run/gtme-bindings/hubspot-contact-search@main

The command prints the hosts the binding will call and the credentials it will ask for, then pins the commit it fetched. Then, in a pipeline file:

source:
  use: hubspot/contact-search
  with:
    known_property: KNOWN_PROPERTY

Replace the placeholder:

KNOWN_PROPERTY: contact property that must be set (HubSpot IS_KNOWN / HAS_PROPERTY); email reproduces "every contact with an email".

gtme plan pipeline.yaml checks the credential is set and that every field this step needs is provided by a step before it, without calling anyone.

Needs

Nothing. A source starts the pipeline.

Provides

email, first_name, last_name, title, company_name, hubspot.contact_id, hubspot.lifecycle_stage

Config

Key	Type	What it does
`known_property` required	string	Contact property that must be set (HubSpot IS_KNOWN / HAS_PROPERTY); `email` reproduces "every contact with an email".
`per_page`	integer	Default `100`.
`limit`	integer	Stop after this many contacts (engine-enforced cap on a source).
`base_url`	string	Override the API host (testing). Default `https://api.hubapi.com`.

What a response looks like

Recorded from a real response to POST /crm/v3/objects/contacts/search, status 200. The conformance kit proves this payload in produces canonical records out, and gtme run --simulate serves it in place of the network.

{
  "total": 2,
  "results": [
    {
      "id": "101",
      "properties": {
        "email": "ada.quill@example.test",
        "firstname": "Ada",
        "lastname": "Quill",
        "jobtitle": "VP Marketing",
        "company": "Quill & Co",
        "lifecyclestage": "customer",
        "hs_object_id": "101"
      },
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-08-01T00:00:00.000Z",
      "archived": false
    },
    {
      "id": "102",
      "properties": {
        "email": "bo.marsh@example.test",
        "firstname": "Bo",
        "lastname": "Marsh",
        "jobtitle": "Head of Growth",
        "company": "Marshlight",
        "lifecyclestage": "lead",
        "hs_object_id": "102"
      },
      "createdAt": "2026-02-01T00:00:00.000Z",
      "updatedAt": "2026-08-02T00:00:00.000Z",
      "archived": false
    }
  ]
}

On this page, connector means what gtme calls an adapter. This one is a binding from the registry. Two adapter tiers explains the difference.