SourceLace Docs
FAQOpen the app

HubSpot

How to connect HubSpot's CRM: contacts, companies, deals, tickets, owners and custom objects, with optional confirmed changes. Each person signs in with their own HubSpot login.

Status: Available. Built on HubSpot's published API, and validated in your account during onboarding.

At a glance

Connects through Sign-in Network Status First test question
HubSpot HubSpot CRM API (search, objects, properties, owners) Personal sign-in Nothing to open Available "Show the 5 largest open deals in hubspot:prod." You see deals you can see in HubSpot.

Add each source with the usual steps. The network answers are explained in What your network needs. If the first test question fails, the error message tells you what to fix: look it up under When something goes wrong below.

How sign-in works

SourceLace has its own HubSpot app. Each person signs in to HubSpot with their own login, chooses the HubSpot account, and approves the app. HubSpot then shows SourceLace only what that person could see in HubSpot itself.

What your admin does in HubSpot

Nothing is registered: SourceLace provides the HubSpot app. Your HubSpot admin only makes sure people may approve it. About 5 minutes.

Who: a HubSpot Super Admin of the account, or a user with the App Marketplace access permission.

Before you start, write down the HubSpot account ID: click your account name at the top right of HubSpot; the number under it (also in the address bar, as in app.hubspot.com/contacts/12345678/...) is the account ID, such as 12345678.

  1. Decide who may install apps. HubSpot lets only Super Admins and users with App Marketplace access approve an app for an account. Either connect first yourself (step 2), which installs SourceLace's app for the account, or give people that permission: Settings (the gear icon) → Users & Teams → the person → Permissions → Account → App Marketplace access, then Save.
  2. Connect once yourself. After your SourceLace admin adds the source, click Connect on it. HubSpot asks which account to use: pick the one whose ID you wrote down. It then lists what SourceLace may read (and change, if changes are on) and may say the app is not verified by HubSpot: that is normal for apps outside HubSpot's App Marketplace. Click Connect app.
  3. Make sure people can see the records. SourceLace shows each person what their own HubSpot permissions allow: in Settings → Users & Teams → the person → Permissions → CRM, they need View on contacts, companies, deals and tickets (and Edit on the objects your SourceLace admin made writable). Custom objects need a HubSpot Enterprise plan.

Check that it worked: in HubSpot, Settings → Integrations → Connected apps lists SourceLace. Then ask the first test question from At a glance. To remove SourceLace later, uninstall it from that same page.

HubSpot's own guide: HubSpot Knowledge Base (search for "Connected apps" and "App Marketplace access").

Permissions SourceLace asks for:

When Scopes
Always (reading) oauth, crm.objects.contacts.read, crm.objects.companies.read, crm.objects.deals.read, crm.objects.tickets.read, crm.objects.owners.read, crm.schemas.contacts.read, crm.schemas.companies.read, crm.schemas.deals.read, crm.schemas.tickets.read
Optional (custom objects, Enterprise plans only; HubSpot leaves them out for accounts without custom objects) crm.objects.custom.read, crm.schemas.custom.read
Only for objects your SourceLace admin made writable crm.objects.contacts.write, crm.objects.companies.write, crm.objects.deals.write, crm.objects.tickets.write, crm.objects.custom.write

With changes off, nobody is asked for write access.

Add the source (SourceLace admin)

On Connections → Add a source, choose HubSpot (hubspot).

Option Type Default Example What it is
hub_id Number (none) 12345678 Optional but recommended: the HubSpot account ID (in the account menu at the top right, or the address bar, as in app.hubspot.com/contacts/12345678/...). Many people belong to more than one HubSpot account; with hub_id set, SourceLace refuses a sign-in to any other account.

Changes are off unless you turn them on. HubSpot's object names are lowercase plurals: contacts, companies, deals, tickets, or a custom object's name as search_schema shows it (such as p12345678_cars). Owners cannot be changed. After turning changes on or changing the objects, people connect HubSpot again so their sign-in gets the new write permission.

What people can do

  • search_schema and describe_object list objects and their properties.

  • query takes the hubspot_search language: one JSON object in the shape of HubSpot's own search API, plus the object to search:

    {"object": "deals",
     "properties": ["dealname", "amount", "dealstage"],
     "filterGroups": [{"filters": [{"propertyName": "amount", "operator": "GT", "value": "1000"}]}],
     "sorts": [{"propertyName": "amount", "direction": "DESCENDING"}],
     "limit": 100}
    

    Up to 5 filter groups (a record matches if any group matches), each with up to 6 filters that must all match (18 filters in all). Operators: EQ, NEQ, LT, LTE, GT, GTE, BETWEEN (with value and highValue), IN and NOT_IN (with values), HAS_PROPERTY, NOT_HAS_PROPERTY, CONTAINS_TOKEN, NOT_CONTAINS_TOKEN. query searches text across the main fields; sorts takes one sort. {"object": "owners"} lists the users who can own records. Every key, operator and property name is checked before anything is sent.

  • get_record reads one record by its id (digits only), with associated records as related lists.

  • Changes (create, update, delete one record at a time), on the objects your admin made writable, after a preview and the person's confirmation. Deleting moves the record to HubSpot's recycling bin, where a HubSpot admin can restore it for 90 days.

Limits: SourceLace fetches 200 rows at a time up to its usual 2,000-row limit; HubSpot itself stops a search at 10,000 rows: when a search has more, SourceLace keeps the first 10,000 and the answer says it is incomplete, so add filters to narrow it. HubSpot allows a few searches per second per account: when it asks SourceLace to slow down, SourceLace waits and tries again twice before giving up with a clear message. HubSpot sign-ins last 30 minutes and are refreshed automatically.

When something goes wrong

What you see What it means What to do
"Sign-in was not completed: ..." The person stopped on HubSpot's page, or HubSpot refused there. Often they may not install apps in that account. A Super Admin connects first, or gives them App Marketplace access (step 1).
"HubSpot sign-in failed: ..." HubSpot's own reason follows, such as an expired sign-in code. Connect again. If it repeats, see step 1.
"You signed in to HubSpot account ..., but ... is account .... Connect again and choose that account." The person picked another HubSpot account on the sign-in page. Connect again and choose the account in hub_id.
"The HubSpot hub_id for ... must be the account's number, such as 12345678." hub_id is not a number. Copy the account ID (see Before you start).
"HubSpot did not say which user signed in." HubSpot's answer about the sign-in was incomplete, or the app was uninstalled while connecting. Connect again. If it repeats, contact support.
"HubSpot: your sign-in does not include the permission this needs. If an admin just turned on writes, connect the source again..." The sign-in was made before writes were turned on, or the person's HubSpot permissions lack it. Connect HubSpot again. If it persists, check the person's permissions (step 3).
"HubSpot: ..." (such as a VALIDATION_ERROR) HubSpot's own words about the request, such as a value it does not accept. The AI usually fixes the request itself.
"HubSpot is limiting how fast SourceLace can call it. Wait a few seconds and try again." HubSpot's rate limit for the account. Wait and ask again.
"HubSpot: that record does not exist, or you cannot see it." or "HubSpot: no ... record with id ... that you can see." The id is wrong, or the person may not see that record. Check the id, and the person's permissions (step 3).
"'...' is not a HubSpot record id (digits only)." The id is not HubSpot's numeric record id. Use the id from a query's hs_object_id.
"'...' is not a valid HubSpot object name. Use search_schema to find one." The object name is not one HubSpot knows. Use contacts, companies, deals, tickets or a custom object's name from search_schema.
"... has no property ... Use describe_object to see the property names." The query used a property that does not exist on that object. Use the names describe_object lists.
"This ... record changed in HubSpot after the preview. Propose the change again." Someone changed the record after the preview. Ask for a new preview.
"HubSpot owners are users and cannot be changed through SourceLace." Owners are read-only. Change users in HubSpot itself.
"Your HubSpot sign-in has expired." The sign-in ended, or the app was uninstalled. Connect again.
"HubSpot answered with a web page instead of data (HTTP ...)." or "HubSpot returned HTTP ...." HubSpot had a problem. Try again shortly.
"The hubspot connector is not set up on SourceLace yet..." SourceLace's HubSpot app is not ready yet. Contact support.
"HubSpot sent back data in an unexpected shape." or "SourceLace refused to call an unexpected HubSpot address." HubSpot's answer was not in the form SourceLace expects, or it pointed outside HubSpot, which SourceLace never follows. Try again shortly. If it repeats, contact support.