> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

---
id: 034091ac-b8dc-4e98-a301-f148d7e7e76b
---

# Campaigns API

> Learn how to use Campaigns API to manage your HubSpot campaigns

export const ScopesList = ({scopes = [], description = "This API requires one of the following scopes:"}) => {
  if (!scopes || scopes.length === 0) {
    return null;
  }
  const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
  return <div>
      <div className="text-sm mb-2">{description}</div>
      <div>
        {sortedScopes.map((scope, index) => <div key={index}>
            <code>
              <span className="text-xs">{scope}</span>
            </code>
          </div>)}
      </div>
    </div>;
};

export const SupportedProducts = ({marketing, sales, service, cms, data, commerce, crm, marketingLevel, salesLevel, serviceLevel, cmsLevel, dataLevel, commerceLevel, crmLevel}) => {
  const translations = {
    description: "Requires one of the following products or higher.",
    productNames: {
      marketing: "Marketing Hub",
      sales: "Sales Hub",
      service: "Service Hub",
      cms: "Content Hub",
      data: "Data Hub",
      commerce: "Revenue Hub",
      crm: "Smart CRM"
    },
    tiers: {
      free: "Free",
      starter: "Starter",
      professional: "Professional",
      enterprise: "Enterprise"
    }
  };
  const translateTier = tier => {
    if (!tier) return '';
    const lowerTier = tier.toLowerCase();
    return translations.tiers[lowerTier] || tier;
  };
  const products = [{
    name: marketing ? translations.productNames.marketing : '',
    level: translateTier(marketingLevel),
    icon: "https://mintlify-assets.b-cdn.net/Icons/marketing-bolt.svg",
    alt: "Marketing Hub"
  }, {
    name: sales ? translations.productNames.sales : '',
    level: translateTier(salesLevel),
    icon: "https://mintlify-assets.b-cdn.net/Icons/sales-star.svg",
    alt: "Sales Hub"
  }, {
    name: service ? translations.productNames.service : '',
    level: translateTier(serviceLevel),
    icon: "https://mintlify-assets.b-cdn.net/Icons/service-heart.svg",
    alt: "Service Hub"
  }, {
    name: cms ? translations.productNames.cms : '',
    level: translateTier(cmsLevel),
    icon: "https://mintlify-assets.b-cdn.net/Icons/content-play.svg",
    alt: "Content Hub"
  }, {
    name: data ? translations.productNames.data : '',
    level: translateTier(dataLevel),
    icon: "https://developers.hubspot.com/hubfs/Knowledge_Base_2023-24-25/subscription_key_icons/operations_icon.svg",
    alt: "Data Hub"
  }, {
    name: commerce ? translations.productNames.commerce : '',
    level: translateTier(commerceLevel),
    icon: "https://developers.hubspot.com/hubfs/Knowledge_Base/subscription_key_icons/commerce_icon.svg",
    alt: "Revenue Hub"
  }, {
    name: crm ? translations.productNames.crm : '',
    level: translateTier(crmLevel),
    icon: "https://developer.hubspot.com/hubfs/Knowledge_Base_2023-24-25/developer/icons/SmartCRM.svg",
    alt: "Smart CRM"
  }].filter(product => product.name && product.level);
  if (products.length === 0) return null;
  return <div>
      <div className="text-sm mb-2">{translations.description}</div>
      <div className={`grid ${products.length === 1 ? 'grid-cols-1' : 'grid-cols-2'} gap-1.5`}>
        {products.map((product, index) => <div key={index} style={{
    display: 'flex',
    alignItems: 'center'
  }}>
            <img src={product.icon} alt={product.alt} className="w-3.5 h-3.5 mr-1.5 mt-2.5 mb-2.5 flex-shrink-0 align-middle" />
            <span className="font-medium mr-1 text-sm">{product.name} -</span>
            <span className="text-sm">{product.level}</span>
          </div>)}
      </div>
    </div>;
};

<AccordionGroup>
  <Accordion title="Supported products" defaultOpen="true" icon="cubes">
    <SupportedProducts marketing={true} marketingLevel="professional" />
  </Accordion>

  <Accordion title="Required Scopes" icon="key">
    <ScopesList
      scopes={[
    `marketing.campaigns.read`,
    `marketing.campaigns.write`,
    `marketing.campaigns.revenue.read`
]}
    />
  </Accordion>
</AccordionGroup>

Use the [campaigns tool](https://knowledge.hubspot.com/campaigns/understand-campaigns) 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 to raise awareness of an event.

Using the campaigns API, you can create, read, update, and delete marketing campaign data. For example, use these endpoints to create and manage HubSpot campaigns from your external applications. You can also retrieve campaign data from HubSpot 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.

<Warning>
  If your integration was set up before 9 July, 2025, and was configured to use only the `marketing.campaigns.read` scope group to execute campaign modifications, those API calls will fail, unless the integration also requests the `marketing.campaigns.write` scope group for the applicable API endpoints.
</Warning>

## Create a campaign

To create a campaign, make a `POST` request to `/marketing/campaigns/2026-09-beta`. 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. 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 `12345a-6789b-10111213b`.

<Tabs>
  <Tab title="Example request body">
    ```json theme={null}
    {
      "properties": {
        "hs_name": "Inbound",
        "hs_start_date": "2026-09-15",
        "hs_notes": "Campaign notes"
      }
    }
    ```
  </Tab>

  <Tab title="Example response">
    ```json theme={null}
    {
      "id": "12345a-6789b-10111213b",
      "properties": {
        "hs_name": "Inbound",
        "hs_start_date": "2026-09-15",
        "hs_notes": "Campaign notes"
      },
      "createdAt": "2025-10-30T03:30:17.883Z",
      "updatedAt": "2025-12-07T16:50:06.678Z"
    }
    ```
  </Tab>
</Tabs>

## Clone campaigns

Instead of creating a campaign from scratch, you can clone a campaign as a starting point for your new campaign. You can check the available clonable assets for a campaign, clone your campaign, then check the status of the cloned campaign.

### Retrieve all cloneable assets

Not all assets in an account can be cloned. It is recommended to retrieve a list of cloneable assets before cloning a campaign. To retrieve a list of cloneable assets, make a `GET` request to `/marketing/campaigns/2026-09-beta/clone/asset-types`. A list of asset types eligible for cloning within your account will be returned.

### Clone a campaign

To clone a campaign, make a `POST` request to `/marketing/campaigns/2026-09-beta/clone`.

After making your request, the response will include the `campaignGuid` of the newly created campaign and a status of `PENDING` by default. You can then make a `GET` request to `/marketing/campaigns/2026-09-beta/{campaignGuid}` with your new `campaignGuid` until the operation reaches a final state.

```json expandable title="Example cloning request body" theme={null}
 {
  "sourceCampaignGuid": "12345a-6789b-10111213b",
  "name": "string",
  "startDate": "string",
  "endDate": "string",
  "notes": "string",
  "audience": "string",
  "currencyCode": "string",
  "assetsToClone": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  },
  "shouldCloneTasks": true,
  "shouldCloneTrackingUrls": true,
  "shouldCloneDraftNodes": true,
  "shouldCloneEdges": true,
  "shouldCloneStickyNotes": true
}
```

### Retrieve status of a cloned campaign

After cloning a campaign, to retrieve the status of a cloned campaign, make a `GET` request to `/marketing/campaigns/2026-09-beta/clone/{campaignGuid}/status`, using the `campaignGuid` returned when cloning the campaign.

The response will include the `campaignGuid` and a `status` field, which will return one of the following:

* `PENDING`
* `COMPLETE`
* `FAILED`
* `PARTIAL_FAILURE`

```json theme={null}
{
  "campaignGuid": "345a-6789b-123456c",
  "status": "PENDING"
}
```

## Retrieve a campaign

To retrieve the details of an existing campaign, make a `GET` request to `/marketing/campaigns/2026-09-beta/{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 (e.g., `hs_name`, `hs_campaign_status`) to be returned in the response.
  * 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/campaigns/2026-09-beta/edb9b6c3-d2e2-4ca8-8396-832262aed0d4?properties=hs_name,hs_start_date`, this would result in the following response body:

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

## Retrieve campaigns

To search for and retrieve campaigns based on query parameters, make a `GET` request to `/marketing/campaigns/2026-09-beta`.

When using this endpoint, you can use the following query parameters to filter your campaigns.

* `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`, and `updatedAt`.
  * An optional hyphen (`-`) before the property name will denote descending order. For example, you can use `-createdAt` to sort your campaigns from newest to oldest.
  * If the sort order 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 (e.g., `hs_name`, `hs_campaign_status`) to be returned in the response.
  * 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.

```json expandable title="Example search response body" theme={null}
{
  "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 2025"
      },
      "createdAt": "2025-06-25T10:57:26.232Z",
      "updatedAt": "2025-06-25T10:57:26.232Z"
    }
  ],
  "paging": {
    "next": {
      "after": "Mg%3D%3D",
      "link": "https://api.hubspot.com/marketing/campaigns/2026-09-beta?properties=hs_name&limit=2&after=Mg%3D%3D"
    }
  }
}
```

## Update campaign

To perform a partial update of a campaign identified by the specified campaignGuid, make a `PATCH` request to `/marketing/campaigns/2026-09-beta/{campaignGuid}`.

You can use [campaigns properties](#campaign-properties) to update your campaign. This will overwrite any existing campaign property values. If your request includes read-only or non-existent properties, you will encounter a `400 error`. Learn more about which [properties can be used to update campaigns](#campaign-properties).

<Tabs>
  <Tab title="Example request body">
    ```json theme={null}
    {
      "properties": {
        "hs_name": "Inbound 2025"
      }
    }
    ```
  </Tab>

  <Tab title="Example response">
    ```json theme={null}
    {
      "id": "edb9b6c3-d2e2-4ca8-8396-832262aed0d4",
      "properties": {
        "hs_name": "Inbound 2025"
      },
      "createdAt": "2025-10-30T03:30:17.883Z",
      "updatedAt": "2025-12-07T16:50:06.678Z"
    }
    ```
  </Tab>
</Tabs>

## Delete a campaign

To delete a campaign, make a `DELETE` request to `/marketing/campaigns/2026-09-beta/{campaignGuid}`.

This call will always return a `204 No Content` response, regardless of whether the `campaignGuid` corresponds to an existing campaign or not.

## Campaign properties

When using the `properties` query parameter for your campaign endpoints, you can use the properties below. 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](https://knowledge.hubspot.com/campaigns/manage-your-campaign-budget). |
| `hs_spend_items_sum_amount`  | Monetary value | The sum of all spend items. Learn more about managing your [campaign budget](https://knowledge.hubspot.com/campaigns/manage-your-campaign-budget).  |

<Warning>
  **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.
</Warning>

## Manage campaign assets

Use the following endpoints to review and manage your campaign assets.

### List campaign asset types

To list all supported campaign asset types, make a `GET` request to `/marketing/campaigns/2026-09-beta/asset-types`. This will return a list of asset types that can be used in campaigns. Use this endpoint to review the available options when creating or managing campaign assets.

### List assets associated with a campaign

To retrieve the assets associated with a campaign, make a `GET` request to `/marketing/campaigns/2026-09-beta/{campaignGuid}/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:

<Expandable title="list of available asset types and metrics">
  | Asset                   | Asset type                 | Metrics                                                                                |
  | ----------------------- | -------------------------- | -------------------------------------------------------------------------------------- |
  | Ad campaigns            | `AD_CAMPAIGN`              | No metrics available.                                                                  |
  | Blog posts              | `BLOG_POST`                | `CONTACTS_FIRST_TOUCH`, `CONTACTS_LAST_TOUCH`, `SUBMISSIONS`, and `VIEWS`              |
  | Calls                   | `CALL`                     | No metrics available.                                                                  |
  | Case Studies            | `CASE_STUDY`               | `CTA_CLICKS`                                                                           |
  | CTAs                    | `WEB_INTERACTIVE`          | `CLICKS` and `VIEWS`                                                                   |
  | CTAs (Legacy)           | `CTA`                      | `CLICKS`, `SUBMISSIONS`, and `VIEWS`                                                   |
  | External website pages  | `EXTERNAL_WEB_URL`         | `VIEWS`                                                                                |
  | Feedback surveys        | `FEEDBACK_SURVEY`          | No metrics available.                                                                  |
  | Forms                   | `FORM`                     | `CONVERSION_RATE`, `SUBMISSIONS`, and `VIEWS`                                          |
  | Files                   | `FILE_MANAGER_FILE`        | No metrics available.                                                                  |
  | Knowledge Base Articles | `KNOWLEDGE_ARTICLE`        | No metrics available.                                                                  |
  | Landing pages           | `LANDING_PAGE`             | `CONTACTS_FIRST_TOUCH`, `CONTACTS_LAST_TOUCH`, `CUSTOMERS`, `SUBMISSIONS`, and `VIEWS` |
  | Marketing emails        | `MARKETING_EMAIL`          | `CLICKS`, `OPEN`, and `SENT`                                                           |
  | Marketing events        | `MARKETING_EVENT`          | `ATTENDEES`, `CANCELLATIONS`, and `REGISTRATIONS`                                      |
  | Meetings                | `MEETING_EVENT`            | No metrics available.                                                                  |
  | Playbooks               | `PLAYBOOK`                 | No metrics available.                                                                  |
  | Podcast episodes        | `PODCAST_EPISODE`          | No metrics available.                                                                  |
  | Sales documents         | `SALES_DOCUMENT`           | No metrics available.                                                                  |
  | Sales emails            | `EMAIL`                    | No metrics available.                                                                  |
  | Sequences               | `SEQUENCE`                 | No metrics available.                                                                  |
  | SMS                     | `MARKETING_SMS`            | `SENT`, `DELIVERED`, and `UNIQUE_CLICKS`                                               |
  | Social posts            | `SOCIAL_BROADCAST`         | `FACEBOOK_CLICKS`, `LINKEDIN_CLICKS`, and `TWITTER_CLICKS`                             |
  | Static lists            | `OBJECT_LIST`              | `CONTACTS`                                                                             |
  | Videos                  | `MEDIA`                    | No metrics available.                                                                  |
  | Website pages           | `SITE_PAGE`                | `CONTACTS_FIRST_TOUCH`, `CONTACTS_LAST_TOUCH`, `CUSTOMERS`, `SUBMISSIONS`, and `VIEWS` |
  | Workflows               | `AUTOMATION_PLATFORM_FLOW` | `CURRENTLY_ENROLLED` and `STARTED`                                                     |
</Expandable>

### Manage asset associations

To associate an asset with a campaign, make a `PUT` request to `/marketing/campaigns/2026-09-beta/{campaignGuid}/assets/{assetType}/{assetId}`.

To remove an asset from a campaign, make a `DELETE` request to `/marketing/campaigns/2026-09-beta/{campaignGuid}/assets/{assetType}/{assetId}`.

You can use the endpoints above to create and remove associations for the following asset types. For other asset types, learn how to [associate assets and content with a campaign](https://knowledge.hubspot.com/campaigns/associate-assets-and-content-with-a-campaign) in HubSpot.

<Expandable title="assets that can be associated or removed with the campaigns API">
  * Ads
  * Blog Posts
  * Calls
  * Case Studies
  * CTAs
  * CTAs (Legacy)
  * External Website Pages
  * Feedback Surveys
  * Forms
  * Files
  * Knowledge Base Articles
  * Landing Pages
  * Marketing Emails
  * Marketing Events
  * Meetings
  * Playbooks
  * Podcast Episodes
  * Sales Documents
  * Sales Emails
  * Sequences
  * SMS
  * Social Posts
  * Static Lists
  * Videos
  * Website Pages
  * Workflows
</Expandable>