HubSpot

​

At a glance

npx @deploybaseline/cli start --service hubspot

import { createEmulator } from "@deploybaseline/cli";

const hubspot = await createEmulator({ service: "hubspot" });
// hubspot.url is http://localhost:4000

{
  "hubspot": {
    "portal": {
      "id": 12345678,
      "name": "Acme"
    },
    "owners": [
      {
        "email": "[email protected]",
        "first_name": "Olivia",
        "last_name": "Owner"
      }
    ],
    "private_apps": [
      {
        "name": "Local app",
        "token": "pat-na1-baseline-local",
        "scopes": [
          "crm.objects.contacts.write",
          "crm.objects.companies.write",
          "crm.objects.deals.write",
          "tickets",
          "crm.schemas.contacts.write",
          "crm.objects.owners.read"
        ]
      }
    ],
    "contacts": [
      {
        "email": "[email protected]",
        "firstname": "Ada",
        "lastname": "Lovelace",
        "lifecyclestage": "lead"
      }
    ],
    "companies": [
      {
        "name": "Acme",
        "domain": "acme.com"
      }
    ],
    "deals": [
      {
        "dealname": "Acme renewal",
        "amount": 12000,
        "dealstage": "qualifiedtobuy"
      }
    ],
    "associations": [
      {
        "from": {
          "contacts": "[email protected]"
        },
        "to": {
          "companies": "acme.com"
        },
        "labels": ["Primary"]
      },
      {
        "from": {
          "deals": "Acme renewal"
        },
        "to": {
          "companies": "acme.com"
        }
      }
    ]
  }
}

​

Start

npx @deploybaseline/cli start --service hubspot

import { Client } from "@hubspot/api-client";

const hubspot = new Client({
  accessToken: "pat-na1-baseline-local",
  basePath: process.env.HUBSPOT_EMULATOR_URL,
});

const contact = await hubspot.crm.contacts.basicApi.create({
  properties: { email: "[email protected]", firstname: "Ada" },
  associations: [],
});

​

URL mapping

​

Auth

• Private app tokens come from private_apps in the seed. Each works only for the operations its scopes allow. A missing scope gets HTTP 403 with category MISSING_SCOPES and the scopes that would have worked in errors[0].context.requiredGranularScopes, as HubSpot answers.
• OAuth access tokens come from the OAuth flow and work for the scopes the install granted, checked the same way. They last 30 minutes; an expired one gets HTTP 401 with category EXPIRED_AUTHENTICATION and HubSpot’s message The OAuth token used to make this call expired N second(s) ago.
• Any other token the CLI accepts acts with every scope, so a quick start needs no setup.

​

OAuth

• an unknown client_id, or a redirect_uri that is not one of the app’s redirect URLs (compared by origin and path, ignoring a trailing slash);
• an account id in the path other than the seeded portal.id;
• scopes that do not fit the app: scope must include every required scope and nothing outside the app’s required and optional scopes, and optional_scope only the app’s scopes. This page uses HubSpot’s wording, Authorization failed because there is a mismatch between the scopes in the install URL and the app's configured scopes.

import { Client } from "@hubspot/api-client";

const base = process.env.HUBSPOT_EMULATOR_URL!;
const installUrl = new Client().oauth
  .getAuthorizationUrl(clientId, redirectUri, "oauth crm.objects.contacts.read")
  .replace("https://app.hubspot.com", base);
// After the user picks an account, your redirect URL receives ?code=...
const tokens = await new Client({ basePath: base }).oauth.tokensApi.create(
  "authorization_code",
  code,
  redirectUri,
  clientId,
  clientSecret,
);
const hubspot = new Client({ accessToken: tokens.accessToken, basePath: base });

​

Objects

• GET /crm/v3/objects/{objectType} lists records by id with limit (default 10, at most 100), after, properties, propertiesWithHistory, and archived. paging.next.after is the id of the next record and paging.next.link the full URL, so the client’s getAll walks every page.
• POST /crm/v3/objects/{objectType} creates a record (HTTP 201) and answers with every property that has a value. associations links it to existing records in the same request (see Associations).
• GET /crm/v3/objects/{objectType}/{id} reads one, with properties, propertiesWithHistory, associations, archived, and idProperty.
• PATCH /crm/v3/objects/{objectType}/{id} updates one (idProperty works here too). An empty string clears a value.
• DELETE /crm/v3/objects/{objectType}/{id} archives one (HTTP 204, also for ids that do not exist). Archived records read only with archived=true and keep archivedAt.

​

Values

• number values must be numeric (INVALID_INTEGER), bool values true or false (INVALID_BOOLEAN).
• date values take YYYY-MM-DD or a UTC midnight timestamp in milliseconds and are stored as YYYY-MM-DD; datetime values take ISO 8601 or milliseconds and are stored as ISO strings (INVALID_DATE).
• Enumerations take one of their option values (INVALID_OPTION). Multiple checkbox properties take values separated by semicolons; a leading semicolon (;b;c) adds to the current values instead of replacing them.
• A contact’s email must look like an address (INVALID_EMAIL) and is stored in lower case. hubspot_owner_id must be an active owner’s id (INVALID_OWNER_ID).
• Unknown properties get PROPERTY_DOESNT_EXIST, and HubSpot’s own computed values (hs_object_id, the last modified date, deal closed state) get READ_ONLY_VALUE.
• lifecyclestage only moves forward (subscriber, lead, marketing qualified lead, sales qualified lead, opportunity, customer, evangelist, other). Clear it first to set an earlier stage.

​

Unique values

​

Deals and tickets

• Tickets need hs_pipeline_stage: without it, HTTP 400 Some required properties were not set. with context.properties. Entering a stage whose ticketState is CLOSED sets closed_date; reopening clears it.
• Deals get hs_deal_stage_probability, hs_is_closed, and hs_is_closed_won from the stage. Entering a closed stage sets closedate when it is empty.

​

Batch

• create (HTTP 201) is all or nothing, unless every input carries an objectWriteTraceId: then valid inputs are created and the response is HTTP 207 with numErrors and an errors entry per failed input, its trace id in context.objectWriteTraceId, as HubSpot documents.
• read takes properties, propertiesWithHistory, idProperty, and the archived query parameter. Missing ids give HTTP 207 with one OBJECT_NOT_FOUND error listing them in context.ids.
• update refuses repeated ids (Duplicate IDs found in batch input), reports missing ids like read, and writes the rest; bad values fail the batch unless every input has a trace id.
• upsert takes idProperty and id per input (a unique property other than hs_object_id), creates or updates, and marks each result with new. Upserts by email are all or nothing; other unique properties allow partial success with trace ids.
• archive answers HTTP 204 and skips ids that do not exist.

​

Search

• filterGroups: groups are ORed and the filters in a group are ANDed. At most 5 groups, 6 filters in a group, and 18 filters in all. A top level filters list is read as one group.
• Operators: EQ, NEQ, LT, LTE, GT, GTE, BETWEEN (value and highValue, both ends included), IN and NOT_IN (values), HAS_PROPERTY, NOT_HAS_PROPERTY, CONTAINS_TOKEN, and NOT_CONTAINS_TOKEN. Without operator, a filter is EQ.
• Values compare by property type: numbers as numbers, dates and datetimes as instants (milliseconds or ISO 8601), strings without regard to case, enumerations exactly (case matters), as HubSpot documents. A multiple checkbox property matches when any chosen value does.
• IN and NOT_IN match string properties only for values given in lower case, as HubSpot documents.
• CONTAINS_TOKEN matches a whole word, or with * wildcards the whole value or any word (*@example.com).
• NEQ, NOT_IN, and NOT_CONTAINS_TOKEN match records with no value; the other comparisons never do.
• associations.{object} (for example associations.contact) matches records associated with the given record id, with EQ or IN.
• query looks for every word in the type’s default searchable properties: firstname, lastname, email, phone, mobilephone, and company for contacts; website, phone, name, and domain for companies; dealname, pipeline, dealstage, description, and dealtype for deals; subject, content, hs_pipeline_stage, and hs_ticket_category for tickets. At most 3,000 characters.
• sorts takes one sort: { propertyName, direction: "ASCENDING" | "DESCENDING" }, or a property name as a string ("-name" for descending), since the client types sorts as strings. Records without the value come last. Without a sort, records come oldest first.
• limit defaults to 10 and may be at most 200; after is the offset from paging.next.after. Results stop at 10,000.
• properties picks the properties returned, as reads do.

​

Associations

​

v4

• PUT /crm/v4/objects/{fromType}/{fromId}/associations/default/{toType}/{toId} adds the unlabeled association and answers with both directions.
• PUT /crm/v4/objects/{type}/{id}/associations/{toType}/{toId} with [{ associationCategory, associationTypeId }] sets the pair’s labels (HTTP 201 { fromObjectTypeId, fromObjectId, toObjectTypeId, toObjectId, labels }). The labels sent replace the pair’s labels; send the current ones too to keep them.
• GET /crm/v4/objects/{type}/{id}/associations/{toType} lists { toObjectId, associationTypes: [{ category, typeId, label }] } by record id, with limit (at most 500) and after.
• DELETE /crm/v4/objects/{type}/{id}/associations/{toType}/{toId} removes every type between the two records.
• POST /crm/v4/associations/{fromType}/{toType}/batch/create (labels, replacing as above), batch/associate/default, batch/archive (whole associations), and batch/labels/archive (some types) take up to 2,000 inputs; batch/read takes up to 1,000 and answers HTTP 207 with a crm.associations.NO_ASSOCIATIONS_FOUND error for each record without associations. Batch create reports a missing record or a bad type per input (HTTP 207).

​

Labels and limits

• GET/POST/PUT /crm/v4/associations/{fromType}/{toType}/labels and DELETE .../labels/{associationTypeId} (also under /crm/associations/v4). A new label takes name (letters, digits, and underscores, not starting with a digit), label, and for a paired label inverseLabel. Each direction gets its own USER_DEFINED type id, from 100 up; a single label between records of one object has one id. Ten labels per pair of objects; a repeated name gets HTTP 409. HubSpot’s types cannot be changed or deleted, and a label in use cannot be deleted.
• Limits: POST /crm/v4/associations/definitions/configurations/{fromType}/{toType}/batch/{create,update,purge} with { category, typeId, maxToObjectIds }, GET .../configurations/{fromType}/{toType} (every type, with userEnforcedMaxToObjectIds where set), and GET .../configurations/all (the limits set). An association that would pass a limit, on either record, gets HTTP 400 with subCategory crm.associations.ASSOCIATION_LIMIT_EXCEEDED.

​

Associations on create

​

v3 (legacy)

• GET /crm/v3/associations/{fromType}/{toType}/types lists { id, name } in v3 names: the primary type has the plain name (contact_to_company) and the unlabeled type ends in _unlabeled; a custom label uses its name.
• POST /crm/v3/associations/{fromType}/{toType}/batch/{create,read,archive} with { from, to, type }, where type is a v3 name or a type id. Read lists one { id, type } per association type.
• GET /crm/v3/objects/{type}/{id}/associations/{toType}, and PUT/DELETE .../associations/{toType}/{toId}/{associationType}. PUT answers with the record and its associations of that object.

​

Properties

• GET/POST /crm/v3/properties/{objectType} and GET/PATCH/DELETE /crm/v3/properties/{objectType}/{propertyName}. GET takes archived and properties (names to return).
• POST /crm/v3/properties/{objectType}/batch/{create,read,archive}. Batch create answers HTTP 207 with an error per refused definition; batch read reports missing names.
• Groups: GET/POST /crm/v3/properties/{objectType}/groups and GET/PATCH/DELETE .../groups/{groupName}. A group that still holds properties, and each type’s HubSpot group (contactinformation, companyinformation, dealinformation, ticketinformation), cannot be archived.

​

Pipelines

• GET/POST /crm/v3/pipelines/{objectType} and GET/PUT/PATCH/DELETE /crm/v3/pipelines/{objectType}/{pipelineId}.
• Stages: GET/POST .../{pipelineId}/stages and GET/PUT/PATCH/DELETE .../stages/{stageId}.
• Audits: GET .../{pipelineId}/audit and GET .../stages/{stageId}/audit, newest first, with action, message, and the pipeline or stage as rawObject. The client’s stage audit method sends {pipelineId} unfilled; the emulator finds the stage’s pipeline.

​

Owners

• GET /crm/v3/owners (also with the trailing slash the client sends) with email, after, limit (default 100, at most 500), and archived.
• GET /crm/v3/owners/{ownerId} with idProperty (id or userId) and archived.

​

Errors

​

Webhooks

import { Signature } from "@hubspot/api-client";

Signature.isValid({
  signatureVersion: "v3",
  signature: req.headers["x-hubspot-signature-v3"],
  clientSecret,
  requestBody: rawBody,
  url: "https://your-app.example.com/hubspot/webhooks",
  timestamp: Number(req.headers["x-hubspot-request-timestamp"]),
});

​

Seed config

{
  "hubspot": {
    "portal": {
      "id": 12345678,
      "name": "Acme",
      "domain": "acme.com"
    },
    "owners": [
      {
        "email": "[email protected]",
        "first_name": "Olivia",
        "last_name": "Owner",
        "id": "501",
        "teams": [
          {
            "name": "Sales"
          }
        ]
      }
    ],
    "private_apps": [
      {
        "name": "Local app",
        "token": "pat-na1-baseline-local",
        "scopes": ["crm.objects.contacts.write", "crm.objects.deals.read", "tickets"]
      }
    ],
    "developer_api_key": "dev-api-key",
    "oauth_apps": [
      {
        "name": "CRM Sync",
        "client_id": "1b2c3d4e-0000-4000-8000-00000000c1d1",
        "client_secret": "5e6f7a8b-0000-4000-8000-0000000005ec",
        "app_id": 777001,
        "redirect_uris": ["http://localhost:3000/oauth-callback"],
        "scopes": ["oauth", "crm.objects.contacts.read", "crm.objects.contacts.write"],
        "optional_scopes": ["crm.objects.deals.read"],
        "installed": true,
        "webhooks": {
          "target_url": "http://localhost:3000/hubspot/webhooks",
          "max_concurrent_requests": 10,
          "subscriptions": [
            {
              "event_type": "contact.creation"
            },
            {
              "event_type": "contact.propertyChange",
              "property_name": "lifecyclestage"
            },
            {
              "event_type": "deal.creation",
              "active": false
            }
          ]
        }
      }
    ],
    "property_groups": {
      "deals": [
        {
          "name": "partner_info",
          "label": "Partner info"
        }
      ]
    },
    "properties": {
      "deals": [
        {
          "name": "partner",
          "label": "Partner",
          "type": "enumeration",
          "field_type": "radio",
          "group_name": "partner_info",
          "options": ["acme", "globex"]
        }
      ],
      "companies": [
        {
          "name": "external_id",
          "label": "External ID",
          "type": "string",
          "field_type": "text",
          "has_unique_value": true
        }
      ]
    },
    "pipelines": {
      "deals": [
        {
          "id": "partners",
          "label": "Partners",
          "stages": [
            {
              "id": "intro",
              "label": "Intro",
              "probability": 0.1
            },
            {
              "label": "Won",
              "probability": 1
            }
          ]
        }
      ],
      "tickets": [
        {
          "label": "Escalations",
          "stages": [
            {
              "label": "Open"
            },
            {
              "label": "Done",
              "ticket_state": "CLOSED"
            }
          ]
        }
      ]
    },
    "contacts": [
      {
        "email": "[email protected]",
        "firstname": "Ada",
        "lastname": "Lovelace",
        "lifecyclestage": "lead"
      }
    ],
    "companies": [
      {
        "name": "Acme",
        "domain": "acme.com",
        "external_id": "acme-1"
      }
    ],
    "deals": [
      {
        "dealname": "Partner deal",
        "pipeline": "partners",
        "dealstage": "intro",
        "partner": "globex",
        "hubspot_owner_id": "501"
      }
    ],
    "tickets": [
      {
        "subject": "Printer on fire",
        "hs_pipeline_stage": "1",
        "hs_ticket_priority": "HIGH"
      }
    ],
    "association_labels": [
      {
        "from": "contacts",
        "to": "companies",
        "name": "billing",
        "label": "Billing contact"
      },
      {
        "from": "companies",
        "to": "companies",
        "name": "reseller",
        "label": "Reseller",
        "inverse_label": "Supplier"
      }
    ],
    "associations": [
      {
        "from": {
          "contacts": "[email protected]"
        },
        "to": {
          "companies": "acme.com"
        },
        "labels": ["Primary", "Billing contact"]
      },
      {
        "from": {
          "deals": "Partner deal"
        },
        "to": {
          "companies": "Acme"
        }
      }
    ]
  }
}

• domain: hub_domain in OAuth token info; example.com when left out
• id: optional; generated when left out
• developer_api_key: the webhooks API’s ?hapikey; any key works when left out
• app_id: optional; generated when left out
• installed: installed from the start, so webhooks flow without an OAuth round trip

​

Inspector

​

Limits

• OAuth covers public apps installed by the account: user level apps, the client credentials grant, and the webhook journal API are not served, and the date versioned webhooks paths (/app-webhooks/2026-09/...) are not served. Generic object.* subscriptions are refused.
• Webhook subscriptions to merge, restore, privacy deletion, product, line item, and conversation events are accepted but never fire, since those changes are not modeled. maxConcurrentRequests is stored, but deliveries for one app go one at a time.
• Search has no phone number normalization, and query matches words anywhere in a value rather than by HubSpot’s tokenizer. Records appear in search as soon as they are written.
• Association reads on records (associations= and the v3 record path) are not paged. The date versioned paths (/crm/objects/2026-03/...) and the association usage report are not served.
• Only contacts, companies, deals, and tickets exist. Custom objects, activities (calls, emails, meetings, notes, tasks), line items, products, quotes, and leads are not modeled.
• Calculation properties store their formula but never compute a value. Sensitive data properties, merges, GDPR delete, and the recycle bin restore are not modeled.
• Rate limit headers are not sent and requests are never limited.

​

Conformance