canonical: https://jentic.com/apis/hubspot.com/hubspot-crm-companies # HubSpot Companies The HubSpot Companies API manages company records - the primary CRM object representing organisations that a HubSpot user does business with. It exposes the standard CRM v3 object pattern with batch read, create, update, archive, search, upsert, and merge operations against the companies object. Each company record carries default properties such as name and domain, supports custom properties, and can be associated with contacts, deals, tickets, and other CRM objects. ## For AI agents Create, read, update, merge, archive, search, and upsert HubSpot company records, including batch operations and associations to contacts and deals. ## Scope Does not handle deals, tickets, or marketing email - use only for HubSpot CRM company records. ## Capabilities - Create company records with name, domain, and custom property values - Batch upsert companies by domain or external id to keep CRM in sync without duplicates - Merge two company records into a single canonical record using the merge endpoint - Search companies by domain, industry, or any property using filter groups - Retrieve a company with associated contacts, deals, and tickets in one call - Update company properties (lifecycle stage, owner, ARR) as the relationship progresses - Archive company records in batch when removing from active CRM views ## Use cases ### Account-Based CRM Sync Sync company records from a data warehouse or a third-party enrichment provider into HubSpot so sales sees a complete picture of each account. Batch upsert by domain handles up to 100 companies per request and avoids duplicates from retried jobs. Example prompt: POST 100 company payloads to /crm/v3/objects/companies/batch/upsert with idProperty = domain and properties including name, industry, and annualrevenue. ### Duplicate Cleanup When two company records exist for the same organisation, merge them into a single canonical record using the merge endpoint. The merge preserves associations from both records and is non-reversible, so the typical pattern is a quarterly hygiene job driven by domain matching. Example prompt: Identify duplicate domains via search, then POST /crm/v3/objects/companies/merge with primaryObjectId and objectIdToMerge to consolidate the records. ### Account Segmentation Search Search companies filtered by industry, revenue band, and lifecycle stage to drive a targeted outreach campaign. The search endpoint supports paging, sorting, and property selection so the export is efficient even on large CRM accounts. Example prompt: POST /crm/v3/objects/companies/search with filterGroups for industry = SOFTWARE, annualrevenue GTE 10000000, and lifecyclestage = LEAD, returning name and ownerId. ### AI Agent Account Enrichment An AI agent reads each company in HubSpot, calls a third-party enrichment provider to find missing properties (industry, employee count, headquarters), and writes the enriched values back. Jentic exposes the search and update operations with typed schemas, so the agent updates the right fields without doc lookup. Example prompt: Search companies missing industry, fetch enrichment data per domain, and PATCH /crm/v3/objects/companies/{companyId} with the resolved industry and employee count. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /crm/v3/objects/companies/batch/create | Create company records in batch | | POST | /crm/v3/objects/companies/batch/upsert | Idempotent upsert by external id or domain | | POST | /crm/v3/objects/companies/batch/read | Read companies in batch by ID | | POST | /crm/v3/objects/companies/batch/update | Update company properties in batch | | POST | /crm/v3/objects/companies/merge | Merge two company records into one | | POST | /crm/v3/objects/companies/search | Search companies by filter groups | | GET | /crm/v3/objects/companies/{companyId} | Retrieve a single company | | GET | /crm/v3/objects/companies | List companies with pagination | ## Key resources - **companies** — Company object - name, domain, industry, lifecycle stage, owner, and custom properties. - **Batch operations** — Batch read, create, update, upsert, and archive endpoints for high-volume sync. - **Search** — Filter companies by any property using filter groups. - **Merge** — Consolidate two duplicate company records into a single canonical record. ## Why Jentic - **Setup:** Wiring the HubSpot Companies API by hand means handling its OAuth 2.0 authorization-code flow, targeting api.hubapi.com, and building batch, search, and merge payloads yourself. Through Jentic you install once, import HubSpot Companies from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** HubSpot gates this API with per-object OAuth scopes, so you grant only the company scopes your agent needs and you choose which operations it may call: you can allow reading and searching company records while leaving destructive operations like merge out of the allowed set unless you add them. - **Credential handling:** Your HubSpot OAuth token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'create a HubSpot company' or 'search companies by domain', and Jentic returns the matching companies operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Contacts** — Manages contact records that are typically associated with companies. - **Deals** — Tracks sales opportunities associated with company records. - **Salesforce** — Salesforce Account is the equivalent organisation record at enterprise scale. ## FAQ ### What authentication does the HubSpot Companies API use? It supports OAuth 2.0 and HubSpot private app tokens passed as bearer tokens. Through Jentic, tokens are stored encrypted in the vault and a scoped token is injected per request, so raw credentials never enter the agent context. ### Can I merge duplicate companies with the HubSpot Companies API? Yes - POST /crm/v3/objects/companies/merge with primaryObjectId and objectIdToMerge in the request body. Associations from the merged record transfer to the primary record. The operation is not reversible, so dry-run with a search-and-diff first. ### What are the rate limits for the HubSpot Companies API? Standard CRM v3 limits apply - 100 requests per 10 seconds for OAuth apps and 110 per 10 seconds for private apps on Pro and Enterprise. Use /crm/v3/objects/companies/batch/upsert (up to 100 records per call) when syncing large company lists. ### How do I upsert companies by domain through Jentic? Run the Jentic search "upsert hubspot company by domain" to find POST /crm/v3/objects/companies/batch/upsert, load the schema, and execute with idProperty = domain. Jentic handles authentication and returns per-record results. ### Is the HubSpot Companies API free? The Companies API is included with any HubSpot account, including the free tier. There is no per-call HubSpot fee, but advanced features like custom objects or higher API limits may require a paid tier. ### Can I associate a company with deals and contacts in one call? Yes - pass an associations array on create, or use the CRM Associations API afterwards, to link a single company to deals, contacts, and tickets. The single-record GET supports an associations parameter to return linked IDs in one response. ### Can I limit what my agent is allowed to do with the HubSpot Companies API? Yes. Because you run Jentic One yourself, your own rules decide which of the HubSpot Companies operations the agent may call and which credentials it may use, so you can allow read and search operations like GET /crm/v3/objects/companies and POST /crm/v3/objects/companies/search while withholding destructive ones such as the merge and batch archive endpoints. HubSpot itself gates this API with per-object OAuth scopes, so you also grant only the company scopes the agent needs. Your HubSpot token is stored once by your own instance and injected at execution time, never entering the agent's prompt or context.