Actions

The ballerinax/hubspot.marketing.campaigns package exposes the following clients:

Client	Purpose
`Client`	Manage HubSpot marketing campaigns: CRUD, batch operations, asset associations, metrics, revenue, contacts, and budget.

Client

Manage HubSpot marketing campaigns: CRUD, batch operations, asset associations, metrics, revenue, contacts, and budget.

Configuration

Field	Type	Default	Description
`auth`	`http:BearerTokenConfig\|OAuth2RefreshTokenGrantConfig\|ApiKeysConfig`	Required	Authentication configuration: OAuth 2.0 refresh token, bearer token, or private app API key.
`httpVersion`	`http:HttpVersion`	`HTTP_2_0`	HTTP protocol version.
`timeout`	`decimal`	`30`	Maximum wait time for a response in seconds.
`retryConfig`	`http:RetryConfig`	`()`	Retry configuration for failed requests.
`secureSocket`	`http:ClientSecureSocket`	`()`	SSL/TLS configuration.
`proxy`	`http:ProxyConfig`	`()`	Proxy server configuration.
`circuitBreaker`	`http:CircuitBreakerConfig`	`()`	Circuit breaker configuration for fault tolerance.
`validation`	`boolean`	`true`	Enable or disable constraint validation.

Initializing the client

import ballerinax/hubspot.marketing.campaigns;

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

campaigns:Client campaignsClient = check new ({
    auth: {
        clientId: clientId,
        clientSecret: clientSecret,
        refreshToken: refreshToken
    }
});

Operations

Campaign CRUD

Campaign search

Signature: get .

Searches for campaigns with optional filtering by name, sorting, and pagination.

Parameters:

Name	Type	Required	Description
`headers`	`map<string\|string[]>`	No	Optional request headers.
`queries`	`GetMarketingV3CampaignsQueries`	No	Query parameters: `limit` (default 50), `name`, `sort` (default `hs_name`), `after`, `properties`.

Returns: CollectionResponseWithTotalPublicCampaignForwardPaging|error

Sample code:

campaigns:CollectionResponseWithTotalPublicCampaignForwardPaging results =
    check campaignsClient->/.();

Sample response:

{
  "total": 2,
  "results": [
    {
      "id": "512",
      "properties": {
        "hs_name": "Spring Product Launch",
        "hs_goal": "Generate leads for new product line"
      },
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-02-01T14:00:00Z"
    },
    {
      "id": "513",
      "properties": {
        "hs_name": "Summer Webinar Series",
        "hs_goal": "Increase brand awareness"
      },
      "createdAt": "2025-03-01T08:00:00Z",
      "updatedAt": "2025-03-10T12:00:00Z"
    }
  ],
  "paging": {
    "next": {
      "after": "513"
    }
  }
}

Create a campaign

Signature: post .

Creates a new marketing campaign with the specified properties.

Parameters:

Name	Type	Required	Description
`payload`	`PublicCampaignInput`	Yes	Campaign properties (e.g., `hs_name`, `hs_goal`, `hs_start_date`, `hs_end_date`).
`headers`	`map<string\|string[]>`	No	Optional request headers.

Returns: PublicCampaign|error

Sample code:

campaigns:PublicCampaign campaign = check campaignsClient->/.post({
    properties: {
        "hs_name": "Spring Product Launch",
        "hs_goal": "Generate leads for new product line",
        "hs_start_date": "2025-04-01",
        "hs_end_date": "2025-06-30"
    }
});

Sample response:

{
  "id": "512",
  "properties": {
    "hs_name": "Spring Product Launch",
    "hs_goal": "Generate leads for new product line",
    "hs_start_date": "2025-04-01",
    "hs_end_date": "2025-06-30"
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

Read a campaign

Signature: get [string campaignGuid]

Retrieves a single campaign by its GUID, optionally including associated assets.

Parameters:

Name	Type	Required	Description
`campaignGuid`	`string`	Yes	The UUID of the campaign to retrieve.
`headers`	`map<string\|string[]>`	No	Optional request headers.
`queries`	`GetMarketingV3CampaignsCampaignGuidQueries`	No	Query parameters: `startDate`, `endDate`, `properties`.

Returns: PublicCampaignWithAssets|error

Sample code:

campaigns:PublicCampaignWithAssets campaign =
    check campaignsClient->/["campaignGuid"];

Sample response:

{
  "id": "512",
  "properties": {
    "hs_name": "Spring Product Launch",
    "hs_goal": "Generate leads for new product line"
  },
  "assets": {},
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-02-01T14:00:00Z"
}

Update campaign

Signature: patch [string campaignGuid]

Updates an existing campaign's properties.

Parameters:

Name	Type	Required	Description
`campaignGuid`	`string`	Yes	The UUID of the campaign to update.
`payload`	`PublicCampaignInput`	Yes	Updated campaign properties.
`headers`	`map<string\|string[]>`	No	Optional request headers.

Returns: PublicCampaign|error

Sample code:

campaigns:PublicCampaign updated = check campaignsClient->/["campaignGuid"].patch({
    properties: {
        "hs_name": "Spring Product Launch 2025 (Updated)"
    }
});

Sample response:

{
  "id": "512",
  "properties": {
    "hs_name": "Spring Product Launch 2025 (Updated)",
    "hs_goal": "Generate leads for new product line"
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-03-18T09:00:00Z"
}

Delete campaign

Signature: delete [string campaignGuid]

Deletes a campaign by its GUID.

Parameters:

Name	Type	Required	Description
`campaignGuid`	`string`	Yes	The UUID of the campaign to delete.
`headers`	`map<string\|string[]>`	No	Optional request headers.

Returns: error?

Sample code:

check campaignsClient->/["campaignGuid"].delete();

Batch operations

Create a batch of campaigns

Signature: post batch/create

Creates multiple campaigns in a single request.

Parameters:

Name	Type	Required	Description
`payload`	`BatchInputPublicCampaignInput`	Yes	Array of campaign inputs to create.
`headers`	`map<string\|string[]>`	No	Optional request headers.

Returns: BatchResponsePublicCampaign|BatchResponsePublicCampaignWithErrors|error

Sample code:

campaigns:BatchResponsePublicCampaign|campaigns:BatchResponsePublicCampaignWithErrors result =
    check campaignsClient->/batch/create.post({
        inputs: [
            { properties: { "hs_name": "Campaign A" } },
            { properties: { "hs_name": "Campaign B" } }
        ]
    });

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "id": "514",
      "properties": { "hs_name": "Campaign A" },
      "createdAt": "2025-03-18T10:00:00Z",
      "updatedAt": "2025-03-18T10:00:00Z"
    },
    {
      "id": "515",
      "properties": { "hs_name": "Campaign B" },
      "createdAt": "2025-03-18T10:00:00Z",
      "updatedAt": "2025-03-18T10:00:00Z"
    }
  ],
  "startedAt": "2025-03-18T10:00:00Z",
  "completedAt": "2025-03-18T10:00:01Z"
}

Read a batch of campaigns

Signature: post batch/read

Reads multiple campaigns by their IDs in a single request, optionally including assets.

Parameters:

Name	Type	Required	Description
`payload`	`BatchInputPublicCampaignReadInput`	Yes	Array of campaign IDs to read.
`headers`	`map<string\|string[]>`	No	Optional request headers.
`queries`	`PostMarketingV3CampaignsBatchReadQueries`	No	Query parameters: `startDate`, `endDate`, `properties`.

Returns: BatchResponsePublicCampaignWithAssets|BatchResponsePublicCampaignWithAssetsWithErrors|error

Sample code:

campaigns:BatchResponsePublicCampaignWithAssets|campaigns:BatchResponsePublicCampaignWithAssetsWithErrors result =
    check campaignsClient->/batch/read.post({
        inputs: [
            { id: "514" },
            { id: "515" }
        ]
    });

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "id": "514",
      "properties": { "hs_name": "Campaign A" },
      "assets": {},
      "createdAt": "2025-03-18T10:00:00Z",
      "updatedAt": "2025-03-18T10:00:00Z"
    },
    {
      "id": "515",
      "properties": { "hs_name": "Campaign B" },
      "assets": {},
      "createdAt": "2025-03-18T10:00:00Z",
      "updatedAt": "2025-03-18T10:00:00Z"
    }
  ],
  "startedAt": "2025-03-18T10:00:00Z",
  "completedAt": "2025-03-18T10:00:01Z"
}

Update a batch of campaigns

Signature: post batch/update

Updates multiple campaigns in a single request.

Parameters:

Name	Type	Required	Description
`payload`	`BatchInputPublicCampaignBatchUpdateItem`	Yes	Array of campaign update items with IDs and updated properties.
`headers`	`map<string\|string[]>`	No	Optional request headers.

Returns: BatchResponsePublicCampaign|BatchResponsePublicCampaignWithErrors|error

Sample code:

campaigns:BatchResponsePublicCampaign|campaigns:BatchResponsePublicCampaignWithErrors result =
    check campaignsClient->/batch/update.post({
        inputs: [
            { id: "514", properties: { "hs_name": "Campaign A (Renamed)" } },
            { id: "515", properties: { "hs_goal": "Updated goal" } }
        ]
    });

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "id": "514",
      "properties": { "hs_name": "Campaign A (Renamed)" },
      "createdAt": "2025-03-18T10:00:00Z",
      "updatedAt": "2025-03-18T11:00:00Z"
    },
    {
      "id": "515",
      "properties": { "hs_name": "Campaign B", "hs_goal": "Updated goal" },
      "createdAt": "2025-03-18T10:00:00Z",
      "updatedAt": "2025-03-18T11:00:00Z"
    }
  ],
  "startedAt": "2025-03-18T11:00:00Z",
  "completedAt": "2025-03-18T11:00:01Z"
}

Delete a batch of campaigns

Signature: post batch/archive

Deletes multiple campaigns in a single request.

Parameters:

Name	Type	Required	Description
`payload`	`BatchInputPublicCampaignDeleteInput`	Yes	Array of campaign IDs to delete.
`headers`	`map<string\|string[]>`	No	Optional request headers.

Returns: error?

Sample code:

check campaignsClient->/batch/archive.post({
    inputs: [
        { id: "514" },
        { id: "515" }
    ]
});

Asset management

List assets

Signature: get [string campaignGuid]/assets/[string assetType]

Lists assets of a specific type associated with a campaign.

Parameters:

Name	Type	Required	Description
`campaignGuid`	`string`	Yes	The UUID of the campaign.
`assetType`	`string`	Yes	The type of asset to list (e.g., `FORM`, `OBJECT_LIST`, `EXTERNAL_WEB_URL`).
`headers`	`map<string\|string[]>`	No	Optional request headers.
`queries`	`GetMarketingV3CampaignsCampaignGuidAssetsAssetTypeQueries`	No	Query parameters: `startDate`, `endDate`, `limit` (default 10), `after`.

Returns: CollectionResponsePublicCampaignAssetForwardPaging|error

Sample code:

campaigns:CollectionResponsePublicCampaignAssetForwardPaging assets =
    check campaignsClient->/[campaignGuid]/assets/["EXTERNAL_WEB_URL"];

Sample response:

{
  "results": [
    {
      "id": "https://example.com/landing-page",
      "name": "Spring Launch Landing Page"
    }
  ],
  "paging": null
}

Add asset association

Signature: put [string campaignGuid]/assets/[string assetType]/[string assetId]

Associates an asset with a campaign. Only supports FORM, OBJECT_LIST, and EXTERNAL_WEB_URL asset types.

Parameters:

Name	Type	Required	Description
`campaignGuid`	`string`	Yes	The UUID of the campaign.
`assetType`	`string`	Yes	The type of asset: `FORM`, `OBJECT_LIST`, or `EXTERNAL_WEB_URL`.
`assetId`	`string`	Yes	The ID of the asset to associate (or a URL for `EXTERNAL_WEB_URL`).
`headers`	`map<string\|string[]>`	No	Optional request headers.

Returns: error?

Sample code:

check campaignsClient->/[campaignGuid]/assets/["EXTERNAL_WEB_URL"]/["https://example.com/landing-page"].put();

Remove asset association

Signature: delete [string campaignGuid]/assets/[string assetType]/[string assetId]

Removes the association between an asset and a campaign.

Parameters:

Name	Type	Required	Description
`campaignGuid`	`string`	Yes	The UUID of the campaign.
`assetType`	`string`	Yes	The type of asset: `FORM`, `OBJECT_LIST`, or `EXTERNAL_WEB_URL`.
`assetId`	`string`	Yes	The ID of the asset to disassociate.
`headers`	`map<string\|string[]>`	No	Optional request headers.

Returns: error?

Sample code:

check campaignsClient->/[campaignGuid]/assets/["EXTERNAL_WEB_URL"]/["https://example.com/landing-page"].delete();

Reports

Get Campaign Metrics

Signature: get [string campaignGuid]/reports/metrics

Retrieves aggregated metrics for a campaign including sessions, new contacts, and influenced contacts.

Parameters:

Name	Type	Required	Description
`campaignGuid`	`string`	Yes	The UUID of the campaign.
`headers`	`map<string\|string[]>`	No	Optional request headers.
`queries`	`GetMarketingV3CampaignsCampaignGuidReportsMetricsQueries`	No	Query parameters: `startDate` (default `2006-01-01`), `endDate` (default current date).

Returns: MetricsCounters|error

Sample code:

campaigns:MetricsCounters metrics =
    check campaignsClient->/[campaignGuid]/reports/metrics;

Sample response:

{
  "sessions": 1245,
  "newContactsFirstTouch": 42,
  "newContactsLastTouch": 38,
  "influencedContacts": 156
}

Fetch revenue

Signature: get [string campaignGuid]/reports/revenue

Retrieves revenue attribution data for a campaign with a configurable attribution model.

Parameters:

Name	Type	Required	Description
`campaignGuid`	`string`	Yes	The UUID of the campaign.
`headers`	`map<string\|string[]>`	No	Optional request headers.
`queries`	`GetMarketingV3CampaignsCampaignGuidReportsRevenueQueries`	No	Query parameters: `attributionModel` (default `LINEAR`, options: `FIRST_INTERACTION`, `LAST_INTERACTION`, `FULL_PATH`, `U_SHAPED`, `W_SHAPED`, `TIME_DECAY`, `J_SHAPED`, `INVERSE_J_SHAPED`), `startDate`, `endDate`.

Returns: RevenueAttributionAggregate|error

Sample code:

campaigns:RevenueAttributionAggregate revenue =
    check campaignsClient->/[campaignGuid]/reports/revenue(
        queries = { attributionModel: "U_SHAPED" }
    );

Sample response:

{
  "contactsNumber": 25,
  "dealsNumber": 8,
  "dealAmount": 45000.00,
  "revenueAmount": 45000.00,
  "currencyCode": "USD"
}

Fetch contact IDs

Signature: get [string campaignGuid]/reports/contacts/[string contactType]

Retrieves contact IDs associated with a campaign by attribution type.

Parameters:

Name	Type	Required	Description
`campaignGuid`	`string`	Yes	The UUID of the campaign.
`contactType`	`string`	Yes	Attribution type: `contactFirstTouch`, `contactLastTouch`, or `influencedContacts`.
`headers`	`map<string\|string[]>`	No	Optional request headers.
`queries`	`GetMarketingV3CampaignsCampaignGuidReportsContactsContactTypeQueries`	No	Query parameters: `startDate`, `endDate`, `limit` (default 100), `after`.

Returns: CollectionResponseContactReferenceForwardPaging|error

Sample code:

campaigns:CollectionResponseContactReferenceForwardPaging contacts =
    check campaignsClient->/[campaignGuid]/reports/contacts/["influencedContacts"];

Sample response:

{
  "results": [
    { "id": "101" },
    { "id": "102" },
    { "id": "103" }
  ],
  "paging": {
    "next": {
      "after": "103"
    }
  }
}

Read budget

Signature: get [string campaignGuid]/budget/totals

Retrieves the budget totals for a campaign including total budget, spend, and remaining budget.

Parameters:

Name	Type	Required	Description
`campaignGuid`	`string`	Yes	The UUID of the campaign.
`headers`	`map<string\|string[]>`	No	Optional request headers.

Returns: PublicBudgetTotals|error

Sample code:

campaigns:PublicBudgetTotals budget =
    check campaignsClient->/[campaignGuid]/budget/totals;

Sample response:

{
  "budgetTotal": 50000.00,
  "spendTotal": 32000.00,
  "remainingBudget": 18000.00,
  "currencyCode": "USD",
  "budgetItems": [
    {
      "id": "1",
      "name": "Q1 Budget",
      "amount": 25000.00,
      "order": 0,
      "createdAt": 1705300200,
      "updatedAt": 1705300200
    },
    {
      "id": "2",
      "name": "Q2 Budget",
      "amount": 25000.00,
      "order": 1,
      "createdAt": 1713162600,
      "updatedAt": 1713162600
    }
  ],
  "spendItems": [
    {
      "id": "10",
      "name": "Ad Spend: Google",
      "description": "Google Ads campaign spend",
      "amount": 20000.00,
      "order": 0,
      "createdAt": 1706509800,
      "updatedAt": 1709188200
    },
    {
      "id": "11",
      "name": "Ad Spend: LinkedIn",
      "amount": 12000.00,
      "order": 1,
      "createdAt": 1706509800,
      "updatedAt": 1709188200
    }
  ]
}

Client​

Configuration​

Initializing the client​

Operations​

Campaign CRUD​

Batch operations​

Asset management​

Reports​

Client

Configuration

Initializing the client

Operations

Campaign CRUD

Batch operations

Asset management

Reports