canonical: https://jentic.com/apis/hubspot.com/hubspot-crm-pipelines

# HubSpot CRM Pipelines

The HubSpot CRM Pipelines API manages the pipelines and pipeline stages that define how records move through a workflow - sales deals through sales stages, support tickets through resolution stages, and any custom-object pipeline a portal defines. Endpoints cover full CRUD on pipelines and stages, plus dedicated audit endpoints that return the change history for both. Agents can list, read, create, update, and delete pipelines for a given object type, manage the ordered list of stages within each pipeline, and inspect every change made to either through the audit log. Use it to provision pipelines for a new portal, programmatically rename stages without breaking automation, or build governance dashboards from the audit history.

## For AI agents

Manage HubSpot CRM pipelines and pipeline stages for any object type, including create, read, update, delete, and full audit history of changes.

## Scope

Does not move individual records between stages, run pipeline-based automation, or assign deal owners - use for pipeline and stage configuration and audit only.

## Capabilities

- Create, read, update, and delete pipelines for deals, tickets, or custom objects
- List all pipelines defined for a given object type
- Add, update, and remove stages within a pipeline in a defined display order
- Retrieve the audit log of every change made to a pipeline
- Retrieve the audit log of every change made to a specific pipeline stage
- Read a single pipeline stage including its metadata such as probability and ticket state

## Use cases

### Pipeline provisioning for a new portal

Stand up the sales and ticket pipelines a customer needs as part of onboarding a new HubSpot portal. POST /crm/v3/pipelines/{objectType} creates a pipeline, then POST /crm/v3/pipelines/{objectType}/{pipelineId}/stages adds each stage in order. Lets a setup agent reproduce a tested pipeline structure across portals without manual configuration.

Example prompt: POST a new sales pipeline to /crm/v3/pipelines/deals with label='Enterprise Sales' and displayOrder=1, then POST four ordered stages to /crm/v3/pipelines/deals/{pipelineId}/stages.

### Stage rename with audit trail

Rename a pipeline stage as the team's process evolves and capture the change in HubSpot's audit log. PATCH /crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId} updates the stage label, and GET /crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}/audit returns who made the change and when, so governance teams can trace the modification.

Example prompt: PATCH /crm/v3/pipelines/deals/{pipelineId}/stages/{stageId} setting label to 'Closed Won - Annual', then GET the same stage's /audit endpoint and return the most recent entry.

### Pipeline configuration export

Export a portal's pipeline configuration as a structured document for backup, documentation, or migration to another portal. List pipelines per object type, then list stages per pipeline, and serialise the result. Useful for partners managing multiple portals or for disaster-recovery snapshots.

Example prompt: GET /crm/v3/pipelines/deals to list pipelines, then for each pipeline GET /crm/v3/pipelines/deals/{pipelineId}/stages and return the combined configuration as JSON.

### AI agent execution through Jentic

An agent that needs to manage pipelines discovers this API via Jentic's intent search using a query like 'create a hubspot pipeline' or 'list pipeline stages', loads the input schema for the chosen operation, and executes the call with credentials supplied from your Jentic One instance. Audit endpoints work the same way for read-only governance flows.

Example prompt: Search Jentic for 'create a hubspot pipeline', load POST /crm/v3/pipelines/{objectType}, and execute it for objectType=deals with a label and stages payload.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /crm/v3/pipelines/{objectType} | List all pipelines for an object type |
| POST | /crm/v3/pipelines/{objectType} | Create a new pipeline for an object type |
| GET | /crm/v3/pipelines/{objectType}/{pipelineId} | Read a single pipeline by ID |
| PATCH | /crm/v3/pipelines/{objectType}/{pipelineId} | Update a pipeline's label or display order |
| DELETE | /crm/v3/pipelines/{objectType}/{pipelineId} | Delete a pipeline |
| GET | /crm/v3/pipelines/{objectType}/{pipelineId}/stages | List stages for a pipeline |
| POST | /crm/v3/pipelines/{objectType}/{pipelineId}/stages | Add a stage to a pipeline |
| GET | /crm/v3/pipelines/{objectType}/{pipelineId}/audit | Read the audit log for a pipeline |

## Key resources

- **Pipelines** — Create, read, update, and delete pipelines for any object type
- **Pipeline Stages** — Manage the ordered list of stages within a pipeline
- **Pipeline Audits** — Read the audit log of changes to a pipeline
- **Pipeline Stage Audits** — Read the audit log of changes to a specific pipeline stage

## Why Jentic

- **Setup:** Wiring CRM Pipelines by hand means implementing HubSpot's OAuth2 authorization-code flow (or managing a private-app header token), sending each call to api.hubapi.com with the correct objectType in the path and stage metadata payloads, and handling token refresh yourself. Through Jentic you install once, import CRM Pipelines from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** This API puts the object type in the URL path (/crm/v3/pipelines/{objectType}/...), so a rule can pin your agent to one object type: it can read that type's pipelines and stages and no other. You choose the operations it may call, so destructive ones like pipeline delete are not included unless you add them.
- **Credential handling:** Your HubSpot 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 pipeline' or 'list pipeline stages', and Jentic returns the matching Pipelines operation with its input schema, including the objectType path parameter and stage fields, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **HubSpot CRM Deals** — Manages the deal records that move through pipeline stages
- **HubSpot CRM Tickets** — Manages support ticket records that flow through ticket pipelines
- **HubSpot CRM Objects** — Generic CRM record API used to update the pipeline stage property on individual records

## FAQ

### What authentication does the HubSpot Pipelines API use?

It accepts OAuth 2.0 access tokens and private app access tokens passed as a Bearer credential in the Authorization header. Pipeline write operations require a token with the appropriate CRM scopes for the target object type.

### Which object types support pipelines?

Deals and tickets are the standard supported types, plus any custom object configured for pipeline use. The objectType path parameter on /crm/v3/pipelines/{objectType} accepts these values.

### What are the rate limits for the HubSpot Pipelines API?

It shares HubSpot's account-level rate limits, typically 100 requests per 10 seconds for OAuth apps. Pipeline configuration changes are infrequent enough that the standard limits are rarely a constraint.

### How do I add a stage to a pipeline through Jentic?

Search Jentic with 'add hubspot pipeline stage', load POST /crm/v3/pipelines/{objectType}/{pipelineId}/stages, and execute it with the stage label, displayOrder, and metadata payload. Jentic returns the new stage's id.

### Can I see who changed a pipeline?

Yes. GET /crm/v3/pipelines/{objectType}/{pipelineId}/audit returns a chronological list of changes with the user that made each change. There is also a per-stage audit endpoint at /audit under the stage path.

### What happens to deals when I delete a pipeline stage?

Deleting a stage requires that no records are currently in it; HubSpot returns an error if deals or tickets are present. Move records to another stage with a property update before issuing DELETE.

### Can I limit what my agent is allowed to do with the HubSpot Pipelines API?

Yes. Because you self-host Jentic One, your own rules decide which of this API's operations the agent can call, so you can grant only reads like GET /crm/v3/pipelines/{objectType} and its audit endpoints while withholding writes such as pipeline create, PATCH, or DELETE. Since the object type sits in the URL path, a rule can also pin the agent to a single type, letting it touch deals pipelines and stages but no others. The HubSpot token stays stored by your Jentic One instance and is injected only at execution time, never entering the agent's prompt or logs.