With HubSpot’s marketing tools, you can publish and manage landing pages and website pages to meet a variety of your business needs. Please see this help article to learn more about what you can do with your website pages in HubSpot, or this help article to learn more about what you can do with your landing pages in HubSpot. The documentation below will provide additional detail on what you can accomplish specifically with the Pages v3 API.

Limits

The page APIs are subject to the limits defined in the API Usage guidelines.
Endpoint specific limits are defined within the API documentation. For example, the maximum number of objects returned per page from the GET cms/v3/pages/{landing-pages|site-pages} is 100. 

Changes in V3

• The following properties are deprecated and no longer included within the response:
  • campaign_name
  • is_draft
  • style_override_id
  • meta_keywords

Searching Pages

In addition to the standard filters on the createdAt and updatedAt dates, the GET cms/v3/pages/{landing-pages|site-pages} endpoints support filtering and sorting on the properties below. 

Filtering

Filters are applied as query parameters, by adding the property name, followed by two underscores (_), and then the operator. For example, you can filter the results to only include pages where the name property contains the word 'marketing' using this parameter: &name__icontains=marketing. Any number of filters can be included as query parameters in the request URL. All filters are ANDed together. ORing filters is not currently supported.

The available filter types are listed below.

The table below lists the properties which can be filtered on, along with their supported filter types.

Filtering: Publish State

To retrieve pages with a given publish state, the following query parameters may be used.

Note:
The currentState is a generated field which cannot be filtered against, but will reflect the page’s publish state.

Filtering: A/B 

Note:
An A/B test is running only when there are published, active A and B pages.
An A/B test is complete when a winning and losing variant has been selected, i.e. there isn’t an active B page.

Filtering: Multi-language 

Note: Languages with locales (e.g. en-us) are not supported when using the eq filter with the language field.

Sorting

Sorting can also be applied as query parameters.  You can specify the property name as value to the query parameter `sort` and it returns the pages in the natural order of the specified property. You can reverse the sort by adding a - to the property name: sort=-publishDate. 

By combining query parameters for filtering, sorting and paging, you can retrieve the pages which match your search criteria. For example, the request below fetches landing pages that do not have a language assigned, ordered by most recently updated. The limit and offset parameters below return the second page of results.

Creating Pages

Pages can be created via a POST request to the root endpoint. This endpoint accepts a JSON payload representing the page model. The required fields when creating a page are name and templatePath. To set the URL of a page, the domain and slug fields should be set. Note that the url field is generated and cannot be updated. See this help article for more general information on creating pages.

Editing Pages

CMS pages have both draft and live versions. The draft version may be updated without affecting the live page content. Drafts can be reviewed and then pushed live / published by a user working in HubSpot or via the /push-live endpoint. They may also be scheduled for publication at a future time via the /schedule endpoint. Draft changes can also be discarded via /reset endpoint, allowing users to go back to the current live version of the page without disruption. See this help article for more general information on editing pages.

Edit Draft

The draft version of a page can be updated via a PATCH request to the {objectid}/draft endpoint. This endpoint accepts a JSON payload representing the page model.

Modifying the content of a page via these APIs is not recommended -- the HubSpot Editor is the simplest way to modify content managed by HubSpot CMS. That said, the widgets, widgetContainers, and layoutSections properties are all modifiable via this endpoint. They store page-level module data, contained directly in the template (widgets), within flex columns (widgetContainers) and in drag-and-drop areas (layoutSections) respectively. One thing to note, is that the properties provided in the supplied payload will override the existing draft properties without any complex merging logic. For this reason, when updating nested properties such as those within the widgets, widgetContainers, or layoutSections of the page, one must include the full definition of the object. Partial updates are not supported.

Publish Draft (Immediate)

The draft version of a page can be published via a POST request to the {objectId}/draft/push-live endpoint. This endpoint accepts no payload and simply updates the live version of the target page to match the current draft version. See this help article for more general information on publishing pages.

Publish Draft (Scheduled)

The draft version of a page can be scheduled for publication at a future time via a POST request to the schedule endpoint. This endpoint accepts a JSON payload containing the id of the target page and a publishDate. See this help article for more general information on scheduling publication of pages.

Reset Draft

The draft version of a page can be reset to the current live version via a POST request to the {objectId}/draft/reset endpoint. This endpoint accepts no payload and simply reverts the draft version of the target page to match the current live version.

Running A/B Tests

A/B tests can be used to tune and optimize content by splitting traffic to a page across two variants of differing formats. Conversion rate of each page is monitored over time so that a “winner” can be chosen based on the relative success of each variant. Please see this help article for more details on running A/B tests in HubSpot.

The following properties will be populated on pages with active or completed A/B tests:

• abTestId: Unique identifier for the page’s associated A/B test
• abStatus: Indicates whether the page is an A/B primary, variant, or loser variant

Create Test

An A/B test variant can be created via a POST request to the ab-test/create-variation endpoint. This endpoint accepts a JSON payload containing the contentId of the page to test and a variationName for the variant to be created.

Upon creation, the new test variant can be updated and published in the same manner as a standard page.

End Test

Once enough traffic has been monitored across each variant and a clear “winner” has been determined, an A/B test can be terminated via a POST request to the ab-test/end endpoint. This endpoint accepts a JSON payload containing the abTestId of the target A/B test and the winnerId of the content deemed the “winner.”

Multi-Language Management

To ease the burden of maintaining multiple languages for each page, HubSpot’s CMS allows users to group together language variants of the same content. See this help article for more details on working with multi-language pages.

The following properties will be populated on pages within a multi-language group:

• translatedFromId: Unique identifier for the primary language page of the multi-language group (Will be null on the primary page itself)
• language: The ISO 639 code representing the language of the page
• translations: A map of ISO 639 codes to variant page objects within the multi-language group

Create a New Language Variant

A new language variant of an existing page can be created via a POST request to the multi-language/create-language-variant endpoint. This endpoint accepts a JSON payload containing the id of the page to clone and the language identifier of the new variant.

Attach a Page to an Existing Multi-Language Group

A page can be added to an existing multi-language group via a POST request to the multi-language/attach-to-lang-group endpoint. This endpoint accepts a JSON payload containing the id of the target page, the language identifier of the page being added, and the primaryId of the page designated as the primary page in the target multi-language group.

Detach a Page from a Multi-Language Group

A page can be removed from a multi-languages group via a POST request to the multi-language/detach-from-lang-group endpoint. This endpoint accepts a JSON payload containing the id of the target page.