Actions

The ballerinax/hubspot.crm.pipelines package exposes the following clients:

Client	Purpose
Client	Manage HubSpot CRM pipelines and pipeline stages via the Pipelines REST API.

---

Client

Manage HubSpot CRM pipelines and pipeline stages via the Pipelines REST API.

Configuration

Field	Type	Default	Description
auth	http:BearerTokenConfig|OAuth2RefreshTokenGrantConfig|ApiKeysConfig	Required	Authentication configuration: OAuth 2.0 bearer token, refresh token grant, or API key.
httpVersion	HttpVersion	HTTP_2_0	HTTP protocol version.
timeout	decimal	30	Request timeout in seconds.
retryConfig	RetryConfig	()	Retry configuration for failed requests.
secureSocket	ClientSecureSocket	()	SSL/TLS configuration.
proxy	ProxyConfig	()	Proxy server configuration.
validation	boolean	true	Enable or disable payload validation.
laxDataBinding	boolean	true	Use lax data binding for response payloads.

Initializing the client

import ballerina/oauth2;
import ballerinax/hubspot.crm.pipelines as hspipelines;

configurable string clientId = ?;
configurable string clientSecret = ?;
configurable string refreshToken = ?;

final hspipelines:OAuth2RefreshTokenGrantConfig auth = {
    clientId,
    clientSecret,
    refreshToken,
    credentialBearer: oauth2:POST_BODY_BEARER
};

final hspipelines:Client hubSpotPipelines = check new ({auth});

Operations

Pipeline operations

List all pipelines

Signature: get /[string objectType]

Returns all pipelines for the specified object type.

Parameters:

Name	Type	Required	Description
objectType	string	Yes	The CRM object type (e.g., "deals", "tickets", "orders").
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: CollectionResponsePipelineNoPaging|error

Sample code:

hspipelines:CollectionResponsePipelineNoPaging pipelines = check hubSpotPipelines->/orders;

Sample response:

{
  "results": [
    {
      "id": "67890",
      "label": "Orders Pipeline",
      "displayOrder": 0,
      "archived": false,
      "stages": [
        {
          "id": "11111",
          "label": "Order Received",
          "displayOrder": 0,
          "archived": false,
          "metadata": {"probability": "0.1"},
          "createdAt": "2025-01-15T10:00:00.000Z",
          "updatedAt": "2025-01-15T10:00:00.000Z"
        }
      ],
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": "2025-01-15T10:00:00.000Z"
    }
  ]
}

Create a pipeline

Signature: post /[string objectType]

Creates a new pipeline for the specified object type with the given stages.

Parameters:

Name	Type	Required	Description
objectType	string	Yes	The CRM object type (e.g., "deals", "tickets", "orders").
payload	PipelineInput	Yes	Pipeline definition including label, display order, and stages.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: Pipeline|error

Sample code:

hspipelines:Pipeline pipeline = check hubSpotPipelines->/orders.post({
    label: "Orders Pipeline",
    displayOrder: 0,
    stages: [
        {label: "Order Received", displayOrder: 0, metadata: {"probability": "0.1"}},
        {label: "Processing", displayOrder: 1, metadata: {"probability": "0.3"}},
        {label: "Ready for Shipment", displayOrder: 2, metadata: {"probability": "0.5"}},
        {label: "Shipped", displayOrder: 3, metadata: {"probability": "0.8"}},
        {label: "Delivered", displayOrder: 4, metadata: {"probability": "1.0"}}
    ]
});

Sample response:

{
  "id": "67890",
  "label": "Orders Pipeline",
  "displayOrder": 0,
  "archived": false,
  "stages": [
    {"id": "11111", "label": "Order Received", "displayOrder": 0, "archived": false, "metadata": {"probability": "0.1"}, "createdAt": "2025-01-15T10:00:00.000Z", "updatedAt": "2025-01-15T10:00:00.000Z"},
    {"id": "22222", "label": "Processing", "displayOrder": 1, "archived": false, "metadata": {"probability": "0.3"}, "createdAt": "2025-01-15T10:00:00.000Z", "updatedAt": "2025-01-15T10:00:00.000Z"},
    {"id": "33333", "label": "Ready for Shipment", "displayOrder": 2, "archived": false, "metadata": {"probability": "0.5"}, "createdAt": "2025-01-15T10:00:00.000Z", "updatedAt": "2025-01-15T10:00:00.000Z"},
    {"id": "44444", "label": "Shipped", "displayOrder": 3, "archived": false, "metadata": {"probability": "0.8"}, "createdAt": "2025-01-15T10:00:00.000Z", "updatedAt": "2025-01-15T10:00:00.000Z"},
    {"id": "55555", "label": "Delivered", "displayOrder": 4, "archived": false, "metadata": {"probability": "1.0"}, "createdAt": "2025-01-15T10:00:00.000Z", "updatedAt": "2025-01-15T10:00:00.000Z"}
  ],
  "createdAt": "2025-01-15T10:00:00.000Z",
  "updatedAt": "2025-01-15T10:00:00.000Z"
}

Get a pipeline

Signature: get /[string objectType]/[string pipelineId]

Retrieves a single pipeline by its ID for the specified object type.

Parameters:

Name	Type	Required	Description
objectType	string	Yes	The CRM object type.
pipelineId	string	Yes	The ID of the pipeline to retrieve.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: Pipeline|error

Sample code:

hspipelines:Pipeline pipeline = check hubSpotPipelines->/orders/["67890"];

Sample response:

{
  "id": "67890",
  "label": "Orders Pipeline",
  "displayOrder": 0,
  "archived": false,
  "stages": [
    {"id": "11111", "label": "Order Received", "displayOrder": 0, "archived": false, "metadata": {"probability": "0.1"}, "createdAt": "2025-01-15T10:00:00.000Z", "updatedAt": "2025-01-15T10:00:00.000Z"}
  ],
  "createdAt": "2025-01-15T10:00:00.000Z",
  "updatedAt": "2025-01-15T10:00:00.000Z"
}

Replace a pipeline

Signature: put /[string objectType]/[string pipelineId]

Replaces a pipeline entirely with the provided definition. Use this to overwrite all fields and stages.

Parameters:

Name	Type	Required	Description
objectType	string	Yes	The CRM object type.
pipelineId	string	Yes	The ID of the pipeline to replace.
payload	PipelineInput	Yes	Complete pipeline definition to replace the existing one.
queries	PutCrmV3PipelinesObjectTypePipelineIdReplaceQueries	No	Optional query parameters for validation before deletion.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: Pipeline|error

Sample code:

hspipelines:Pipeline updated = check hubSpotPipelines->/orders/["67890"].put({
    label: "Updated Orders Pipeline",
    displayOrder: 0,
    stages: [
        {label: "New Order", displayOrder: 0, metadata: {"probability": "0.2"}},
        {label: "Fulfilled", displayOrder: 1, metadata: {"probability": "1.0"}}
    ]
});

Sample response:

{
  "id": "67890",
  "label": "Updated Orders Pipeline",
  "displayOrder": 0,
  "archived": false,
  "stages": [
    {"id": "66666", "label": "New Order", "displayOrder": 0, "archived": false, "metadata": {"probability": "0.2"}, "createdAt": "2025-01-15T12:00:00.000Z", "updatedAt": "2025-01-15T12:00:00.000Z"},
    {"id": "77777", "label": "Fulfilled", "displayOrder": 1, "archived": false, "metadata": {"probability": "1.0"}, "createdAt": "2025-01-15T12:00:00.000Z", "updatedAt": "2025-01-15T12:00:00.000Z"}
  ],
  "createdAt": "2025-01-15T10:00:00.000Z",
  "updatedAt": "2025-01-15T12:00:00.000Z"
}

Update a pipeline

Signature: patch /[string objectType]/[string pipelineId]

Partially updates a pipeline's properties (label, display order, archived status).

Parameters:

Name	Type	Required	Description
objectType	string	Yes	The CRM object type.
pipelineId	string	Yes	The ID of the pipeline to update.
payload	PipelinePatchInput	Yes	Fields to update (label, displayOrder, archived).
queries	PatchCrmV3PipelinesObjectTypePipelineIdUpdateQueries	No	Optional query parameters for validation before deletion.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: Pipeline|error

Sample code:

hspipelines:Pipeline patched = check hubSpotPipelines->/orders/["67890"].patch({
    label: "Renamed Orders Pipeline"
});

Sample response:

{
  "id": "67890",
  "label": "Renamed Orders Pipeline",
  "displayOrder": 0,
  "archived": false,
  "stages": [],
  "createdAt": "2025-01-15T10:00:00.000Z",
  "updatedAt": "2025-01-15T14:00:00.000Z"
}

Delete a pipeline

Signature: delete /[string objectType]/[string pipelineId]

Archives (deletes) a pipeline by its ID.

Parameters:

Name	Type	Required	Description
objectType	string	Yes	The CRM object type.
pipelineId	string	Yes	The ID of the pipeline to delete.
queries	DeleteCrmV3PipelinesObjectTypePipelineIdArchiveQueries	No	Optional query parameters for validation before deletion.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: error?

Sample code:

check hubSpotPipelines->/orders/["67890"].delete();

Get pipeline audit log

Signature: get /[string objectType]/[string pipelineId]/audit

Returns the audit history for a pipeline, showing changes made over time.

Parameters:

Name	Type	Required	Description
objectType	string	Yes	The CRM object type.
pipelineId	string	Yes	The ID of the pipeline to audit.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: CollectionResponsePublicAuditInfoNoPaging|error

Sample code:

hspipelines:CollectionResponsePublicAuditInfoNoPaging auditLog =
    check hubSpotPipelines->/orders/["67890"]/audit;

Sample response:

{
  "results": [
    {
      "identifier": "67890",
      "action": "PIPELINE_CREATE",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "portalId": 12345678,
      "fromUserId": 98765
    },
    {
      "identifier": "67890",
      "action": "PIPELINE_UPDATE",
      "timestamp": "2025-01-15T14:00:00.000Z",
      "portalId": 12345678,
      "fromUserId": 98765,
      "message": "Label changed"
    }
  ]
}

Pipeline stage operations

List all stages in a pipeline

Signature: get /[string objectType]/[string pipelineId]/stages

Returns all stages for a specific pipeline.

Parameters:

Name	Type	Required	Description
objectType	string	Yes	The CRM object type.
pipelineId	string	Yes	The ID of the pipeline.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: CollectionResponsePipelineStageNoPaging|error

Sample code:

hspipelines:CollectionResponsePipelineStageNoPaging stages =
    check hubSpotPipelines->/tickets/["67890"]/stages;

Sample response:

{
  "results": [
    {
      "id": "11111",
      "label": "New Ticket",
      "displayOrder": 0,
      "archived": false,
      "metadata": {"ticketStatus": "OPEN"},
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": "2025-01-15T10:00:00.000Z"
    },
    {
      "id": "22222",
      "label": "Resolved",
      "displayOrder": 1,
      "archived": false,
      "metadata": {"ticketStatus": "CLOSED"},
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": "2025-01-15T10:00:00.000Z"
    }
  ]
}

Create a pipeline stage

Signature: post /[string objectType]/[string pipelineId]/stages

Creates a new stage within a pipeline.

Parameters:

Name	Type	Required	Description
objectType	string	Yes	The CRM object type.
pipelineId	string	Yes	The ID of the pipeline to add the stage to.
payload	PipelineStageInput	Yes	Stage definition including label, display order, and optional metadata.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: PipelineStage|error

Sample code:

hspipelines:PipelineStage stage = check hubSpotPipelines->/tickets/["67890"]/stages.post({
    label: "Waiting on Customer",
    displayOrder: 2,
    metadata: {"ticketStatus": "OPEN", "priority": "HIGH"}
});

Sample response:

{
  "id": "33333",
  "label": "Waiting on Customer",
  "displayOrder": 2,
  "archived": false,
  "metadata": {"ticketStatus": "OPEN", "priority": "HIGH"},
  "createdAt": "2025-01-15T11:00:00.000Z",
  "updatedAt": "2025-01-15T11:00:00.000Z"
}

Get a pipeline stage

Signature: get /[string objectType]/[string pipelineId]/stages/[string stageId]

Retrieves a single stage by its ID within a pipeline.

Parameters:

Name	Type	Required	Description
objectType	string	Yes	The CRM object type.
pipelineId	string	Yes	The ID of the pipeline.
stageId	string	Yes	The ID of the stage to retrieve.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: PipelineStage|error

Sample code:

hspipelines:PipelineStage stage =
    check hubSpotPipelines->/tickets/["67890"]/stages/["33333"];

Sample response:

{
  "id": "33333",
  "label": "Waiting on Customer",
  "displayOrder": 2,
  "archived": false,
  "metadata": {"ticketStatus": "OPEN", "priority": "HIGH"},
  "createdAt": "2025-01-15T11:00:00.000Z",
  "updatedAt": "2025-01-15T11:00:00.000Z"
}

Replace a pipeline stage

Signature: put /[string objectType]/[string pipelineId]/stages/[string stageId]

Replaces a pipeline stage entirely with the provided definition.

Parameters:

Name	Type	Required	Description
objectType	string	Yes	The CRM object type.
pipelineId	string	Yes	The ID of the pipeline.
stageId	string	Yes	The ID of the stage to replace.
payload	PipelineStageInput	Yes	Complete stage definition to replace the existing one.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: PipelineStage|error

Sample code:

hspipelines:PipelineStage replaced =
    check hubSpotPipelines->/tickets/["67890"]/stages/["33333"].put({
        label: "Escalated",
        displayOrder: 2,
        metadata: {"ticketStatus": "OPEN", "priority": "CRITICAL"}
    });

Sample response:

{
  "id": "33333",
  "label": "Escalated",
  "displayOrder": 2,
  "archived": false,
  "metadata": {"ticketStatus": "OPEN", "priority": "CRITICAL"},
  "createdAt": "2025-01-15T11:00:00.000Z",
  "updatedAt": "2025-01-15T15:00:00.000Z"
}

Update a pipeline stage

Signature: patch /[string objectType]/[string pipelineId]/stages/[string stageId]

Partially updates a pipeline stage's properties (label, display order, metadata, archived status).

Parameters:

Name	Type	Required	Description
objectType	string	Yes	The CRM object type.
pipelineId	string	Yes	The ID of the pipeline.
stageId	string	Yes	The ID of the stage to update.
payload	PipelineStagePatchInput	Yes	Fields to update (label, displayOrder, metadata, archived).
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: PipelineStage|error

Sample code:

hspipelines:PipelineStage patched =
    check hubSpotPipelines->/tickets/["67890"]/stages/["33333"].patch({
        label: "Awaiting Response"
    });

Sample response:

{
  "id": "33333",
  "label": "Awaiting Response",
  "displayOrder": 2,
  "archived": false,
  "metadata": {"ticketStatus": "OPEN", "priority": "HIGH"},
  "createdAt": "2025-01-15T11:00:00.000Z",
  "updatedAt": "2025-01-15T16:00:00.000Z"
}

Delete a pipeline stage

Signature: delete /[string objectType]/[string pipelineId]/stages/[string stageId]

Archives (deletes) a stage from a pipeline.

Parameters:

Name	Type	Required	Description
objectType	string	Yes	The CRM object type.
pipelineId	string	Yes	The ID of the pipeline.
stageId	string	Yes	The ID of the stage to delete.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: error?

Sample code:

check hubSpotPipelines->/tickets/["67890"]/stages/["33333"].delete();

Get pipeline stage audit log

Signature: get /[string objectType]/[string pipelineId]/stages/[string stageId]/audit

Returns the audit history for a specific pipeline stage.

Parameters:

Name	Type	Required	Description
objectType	string	Yes	The CRM object type.
pipelineId	string	Yes	The ID of the pipeline.
stageId	string	Yes	The ID of the stage to audit.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: CollectionResponsePublicAuditInfoNoPaging|error

Sample code:

hspipelines:CollectionResponsePublicAuditInfoNoPaging stageAudit =
    check hubSpotPipelines->/tickets/["67890"]/stages/["33333"]/audit;

Sample response:

{
  "results": [
    {
      "identifier": "33333",
      "action": "STAGE_CREATE",
      "timestamp": "2025-01-15T11:00:00.000Z",
      "portalId": 12345678,
      "fromUserId": 98765
    }
  ]
}