Campaigns API - HubSpot docs

Supported products

Requires one of the following products or higher.

Marketing Hub -Professional

Required Scopes

This API requires one of the following scopes:

CALL

CASE_STUDY

EMAIL

EXTERNAL_WEB_URL

FEEDBACK_SURVEY

FORM

KNOWLEDGE_ARTICLE

MEETING_EVENT

OBJECT_LIST

PLAYBOOK

PODCAST_EPISODE

SALES_DOCUMENT

SEQUENCE

WEB_INTERACTIVE

Last modified: October 9, 2025

In HubSpot, the campaigns tool can be used to create, manage, and report on a single marketing campaign using multiple assets in one place. For example, you can create a campaign using marketing emails and social posts and raise awareness of a new product or an event. Using the campaigns API, you can create, read, update, and delete marketing campaign data. For example, you can use these endpoints to create and manage HubSpot campaigns from your external applications. You can also transfer campaign data to external data warehouses for analytics.

Scope requirements

The following scopes are required to use the campaigns API, based on the endpoints you’re using:

marketing.campaigns.read: provides access to view details about marketing campaigns and their associated assets. This scope is required for all endpoints.
marketing.campaigns.write: grants access to create, delete, and modify marketing campaigns. This is required for all modification endpoints.
marketing.campaigns.revenue.read: provides access to view revenue details and deal amounts attributed to a marketing campaign.

Create a campaign

To create a campaign, make a POST request to /marketing/v3/campaigns. Create a campaign with the given properties and return the campaign object, including the campaignGuid and created properties. For example, to create a new campaign, you would make a POST request with the following request body.

{
  "properties": {
    "hs_name": "Inbound",
    "hs_start_date": "2024-10-30",
    "hs_notes": "Campaign notes"
  }
}

The response will include a campaignGuid, a unique identifier for the campaign. This will be formatted as a UUID. In the following example, the campaignGuid is edb9b6c3-d2e2-4ca8-8396-832262aed0d4.

{
  "id": "edb9b6c3-d2e2-4ca8-8396-832262aed0d4",
  "properties": {
    "hs_name": "Inbound",
    "hs_start_date": "2024-10-30",
    "hs_notes": "Campaign notes"
  },
  "createdAt": "2024-10-30T03:30:17.883Z",
  "updatedAt": "2024-12-07T16:50:06.678Z"
}

Retrieve a campaign

To retrieve the details of an existing campaign, make a GET request to /marketing/v3/campaigns/{campaignGuid}. This endpoint will return the campaign information. Depending on the query parameters used, this can also be used to return information about the assets and the corresponding assets’ metrics. When using this endpoint, you can use the following query parameters.

properties:a comma-separated list of the properties to be returned in the response. For example, hs_name, hs_campaign_status, hs_notes.
- If any of the specified properties has an empty value on the requested object, it will be ignored and not returned in response.
- If the parameter is empty, the response will include an empty properties map.
- If you have the Brands add-on and you’ve associated your campaign with a brand, the response will return a businessUnits value, which will indicate the associated brand.
startDate:the start date to fetch asset metrics, formatted as YYYY-MM-DD. This is used to fetch the metrics associated with the assets for a specified period. If no date is specified, no asset metrics will be retrieved.
endDate:the end date to fetch asset metrics, formatted as YYYY-MM-DD. This is used to fetch the metrics associated with the assets for a specified period. If no date is specified, no asset metrics will be retrieved.

For example, if you made a GET request with /marketing/v3/campaigns/edb9b6c3-d2e2-4ca8-8396-832262aed0d4?properties=hs_name,hs_start_date, this would result in the following response body:

{
  "id": "edb9b6c3-d2e2-4ca8-8396-832262aed0d4",
  "properties": {
    "hs_name": "Inbound",
    "hs_start_date": "2024-10-30"
  },
  "assets": {
    "EMAIL": {
      "paging": {
        "next": {
          "link": "?after=NTI1Cg%3D%3D",
          "after": "NTI1Cg%3D%3D"
        },
        "results": [
          {
            "id": "832",
            "name": "My email"
          }
        ]
      }
    }
  },
  "createdAt": "2024-10-30T03:30:17.883Z",
  "updatedAt": "2024-12-07T16:50:06.678Z"
}

List assets

To retrieve the assets associated with a campaign make a GET request to /marketing/v3/campaigns/{campaignId}/assets/{assetType}. This endpoint lists all assets of the campaign by asset type. The assetType parameter is required, and each request can only fetch assets of a single type. The following are required:

campaignGuid:the UUID of the campaign.
assetType:the type of asset to be fetched.

You can use the following query parameters with the endpoint:

after:a cursor for pagination. If provided, the results will start after the given cursor. For example, you can use the value NTI1Cg%3D%3D.
limit:define the maximum number of results to return. The allowed values range from 1 to 100. If no limit is specified, it will be set to 10 assets by default.
startDate:the start date to fetch asset metrics, formatted as YYYY-MM-DD. This is used to fetch the metrics associated with the assets for a specified period. If no date is specified, no asset metrics will be retrieved.
endDate:the end date to fetch asset metrics, formatted as YYYY-MM-DD. This is used to fetch the metrics associated with the assets for a specified period. If no date is specified, no asset metrics will be retrieved.

The following is a list of available asset types and metrics related to the assets that are returned in response:

Asset	Asset type	Metrics
Ad campaigns	`AD_CAMPAIGN`	No metrics available.
Blog posts	`BLOG_POST`	`CONTACTS_FIRST_TOUCH`, `CONTACTS_LAST_TOUCH`, `SUBMISSIONS`, and `VIEWS`
Social posts	`SOCIAL_BROADCAST`	`FACEBOOK_CLICKS`, `LINKEDIN_CLICKS`, and `TWITTER_CLICKS`
CTAs	`WEB_INTERACTIVE`	`CLICKS` and `VIEWS`
CTAs (Legacy)	`CTA`	`CLICKS`, `SUBMISSIONS`, and `VIEWS`
External website pages	`EXTERNAL_WEB_URL`	`VIEWS`
Forms	`FORM`	`CONVERSION_RATE`, `SUBMISSIONS`, and `VIEWS`
Landing pages	`LANDING_PAGE`	`CONTACTS_FIRST_TOUCH`, `CONTACTS_LAST_TOUCH`, CUSTOMERS, `SUBMISSIONS`, and `VIEWS`
Emails	`MARKETING_EMAIL`	CLICKS, OPEN, and SENT
Marketing events	`MARKETING_EVENT`	`ATTENDEES`, `CANCELLATIONS`, and `REGISTRATIONS`
Static lists	`OBJECT_LIST`	`CONTACTS`
Website pages	`SITE_PAGE`	`CONTACTS_FIRST_TOUCH`, `CONTACTS_LAST_TOUCH`, `CUSTOMERS`, `SUBMISSIONS`, and `VIEWS`.
Workflows	`AUTOMATION_PLATFORM_FLOW`	`CURRENTLY_ENROLLED` and `STARTED`
Marketing SMS	`MARKETING_SMS`	`SENT`, `DELIVERED`, and `UNIQUE_CLICKS`

Manage asset associations

To associate an asset with a campaign make a PUT request to /marketing/v3/campaigns/{campaignGuid}/assets/{assetType}/{assetId}. To remove an asset from a campaign make a DELETE request to /marketing/v3/campaigns/{campaignGuid}/assets/{assetType}/{assetId}. You can use the endpoints above to create and remove associations for the asset types listed below. For other asset types, learn how to associate assets and content with a campaign in HubSpot.

Update campaign

To perform a partial update of a campaign identified by the specified campaignGuid, make a PATCH request to /marketing/v3/campaigns/{campaignGuid}. You can use campaigns properties to update your campaign. The provided property values will be overwritten. If your request includes read-only or non-existent properties, you will encounter a 400 error. Learn more about which properties can be used. Example request body:

{
  "properties": {
    "hs_name": "Inbound 2024"
  }
}

Example response:

{
  "id": "edb9b6c3-d2e2-4ca8-8396-832262aed0d4",
  "properties": {
    "hs_name": "Inbound 2024"
  },
  "createdAt": "2024-10-30T03:30:17.883Z",
  "updatedAt": "2024-12-07T16:50:06.678Z"
}

Delete a campaign

To delete a campaign, make a DELETE request to /marketing/v3/campaigns. This call will always return a 204 No Content response, regardless of whether the campaignGuid provided corresponds to an existing campaign or not.

Search for campaigns

To search for campaigns based on query parameters, make a GET request to /marketing/v3/campaigns/{campaignGuid}. When using this endpoint, you can use the following query parameters.

name: return all campaigns whose names contain the specified substring. This allows partial matching of campaign names, returning all campaigns that include the given substring in their name. If this parameter is not provided, the search will return all campaigns.
sort: the field by which to sort the results. Allowed values are hs_name, createdAt, updatedAt. An optional hyphen (-) before the property name will denote descending order. For example, you can use -CREATED_AT to sort your campaigns from newest to oldest. If this is not specified, the list of campaigns will be sorted in alphabetical order by campaign name.
after: a cursor for pagination. If provided, the results will start after the given cursor. For example, you can use the value NTI1Cg%3D%3D.
limit: define the maximum number of results to return. The allowed values range from 1 to 100. If no limit is specified, it will be set to 50 campaigns by default.
properties: a comma-separated list of the properties to be returned in the response. For example, hs_name, hs_campaign_status, hs_notes. If any of the specified properties has an empty value on the requested object, it will be ignored and not returned in response. If the parameter is empty, the response will include an empty properties map.

{
  "total": 14,
  "results": [
    {
      "id": "972e2774-7409-43c2-a8b9-581732dff5a7",
      "properties": {
        "hs_name": "Inbound 2023"
      },
      "createdAt": "2023-09-07T10:18:06.320Z",
      "updatedAt": "2023-09-07T10:18:06.320Z"
    },
    {
      "id": "703bc2f0-f000-4840-b6ae-b2d74bc09fa0",
      "properties": {
        "hs_name": "Inbound 2024"
      },
      "createdAt": "2024-06-25T10:57:26.232Z",
      "updatedAt": "2024-06-25T10:57:26.232Z"
    }
  ],
  "paging": {
    "next": {
      "after": "Mg%3D%3D",
      "link": "https://api.hubspotqa.com/marketing/v3/campaigns? properties=hs_name&limit=2&after=Mg%3D%3D"
    }
  }
}

Campaign properties

Please note:On July 9, 2025, the hs_goal property was sunsetted.

If your integration is still sending or expecting the hs_goal property, it will not break the request. Instead, the hs_goal property will be silently ignored.
If your integration relies on the returned value from the hs_goal property, this change could cause breakages (e.g., parsing errors or null value handling issues).

To avoid these issues, check that your code does not depend on hs_goal values being present in API responses, and remove any logic or mapping tied to this field if no longer required.

When using the properties query parameter for your campaign endpoints, you can use the properties below. Note that the first set of properties can be both retrieved and updated, while the second set are read-only.

Property	Type	Description
`hs_name`	String	The campaign’s name. This should be unique, with a max size of 256 characters.
`hs_start_date`	Date (YYYY-MM-DD)	The campaign’s start date.
`hs_end_date`	Date (YYYY-MM-DD)	The campaign’s end date.
`hs_notes`	String	Any notes about the campaign.
`hs_audience`	String	The campaign’s audience.
`hs_currency_code`	ISO currency code	The currency code used for the campaign.
`hs_campaign_status`	Enumeration	The status of the campaign. This includes `planned`, `in_progress`, `active`, `paused`, and `completed`.
`hs_utm`	String	The campaign’s UTM values. This must not exceed 256 characters.

Read-only properties

Property	Type	Description
`hs_owner`	User ID	The user id of the user that owns the campaign
`hs_color_hex`	Hex code	The color of the campaign in hex color code.
`hs_created_by_user_id`	User ID	The user id of the user that originally created the campaign
`hs_object_id`	String	The internal CRM object ID.
`hs_budget_items_sum_amount`	Monetary value	The sum of all budget items. Learn more about managing your campaign budget.
`hs_spend_items_sum_amount`	Monetary value	The sum of all spend items. Learn more about managing your campaign budget.

​Scope requirements

​Create a campaign

​Retrieve a campaign

​List assets

​Manage asset associations

​Update campaign

​Delete a campaign

​Search for campaigns

​Campaign properties