Pages

OverviewEndpoints

In HubSpot, you can create and edit website and landing pages. Learn more about creating and customizing pages within HubSpot. The documentation below details what you can accomplish with the Pages v3 API.

Limits

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

Search pages

To retrieve an account's pages, make a GET request to cms/v3/pages/{landing-pages|site-pages}. You can filter and sort the authors returned in the response using the operators and properties described below. You can also use standard filters using the createdAt and updatedAt dates.

Filtering

Filters are applied as query parameters, by adding the property name, followed by two underscores, 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 specified filters will be applied to narrow down results.

You can use the filters below to filter results by values within specified properties.

Use this table to describe parameters / fields
OperatorDescription
eq

Filters for results that are equal to the specified value.

Synonyms: exact, is

ne

Filters for results that are not equal to the specified value.

Synonyms: neq, not

contains

Filters for results that contain the specified, case-sensitive value. Not accepted for the name property.

Synonym: like.

icontains

Filters for results by the specified value, not case sensitive. 

Synonym: ilike.

not_like

Filters for results that don't contain a specified value.

Synonym: nlike

lt

Filters for results that are less than a specified number value, such as a unix timestamp in milliseconds.

lte

Filters for results that are less than or equal to a specified value.

gt

Filters for results that are greater than a specified value.

gte

Filters for results that are greater than or equal to a specified value.

is_null

Filters for results that do not have a value for the specified property.

not_null

Filters for results that have any value for the specified property.

startswith

Filters for results that start with a specified value.

in

In

nin

Not in

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

Use this table to describe parameters / fields
OperatorDescription
id

eq, in, not_in

slug

eq, in, nin, icontains

campaign

eq, in

state

eq, ne, in, nin, contains

See available states for filtering options.

publishDate

eq, gt, gte, lt, lte

createdAt

eq, gt, gte, lt, lte

updatedAt

eq, gt, gte, lt, lte

templatePath

eq, contains, startswith

name

eq, in, icontains

mabExperimentId

eq, in

abTestId

eq, in

archivedAt

eq, gt, gte, lt, lte

createdById

eq

updatedById

eq

domain

eq, not_like, contains

subcategory

eq, ne, in, nin

folderId

eq, in, null, not_null

language

in, not_null

translatedFromId

null, not_null

dynamicPageHubDbTableId

eq, not_null

Note: the domain parameter will display as blank for content published on a domain that is primary for that content type. 

Filtering: state values

To retrieve pages with a given publish state, include the state__in= query parameter with the following values:

Draft: DRAFT, DRAFT_AB, DRAFT_AB_VARIANT, LOSER_AB_VARIANT

Scheduled: PUBLISHED_OR_SCHEDULED, PUBLISHED_AB, PUBLISHED_AB_VARIANT, 

Published: PUBLISHED

 

Publish State

Query Params 

Draft

state__in=DRAFT, DRAFT_AB, DRAFT_AB_VARIANT, LOSER_AB_VARIANT

Scheduled

state__in=SCHEDULED, SCHEDULED_AB, PUBLISHED_OR_SCHEDULED, PUBLISHED_AB, PUBLISHED_AB_VARIANT & publishDate__gt={currentTime}

Published

state__in=PUBLISHED, PUBLISHED_OR_SCHEDULED,PUBLISHED_AB, PUBLISHED_AB_VARIANT & publishDate__lt={currentTime}

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

Filtering: A/B 

Description

Query Params 

Active A page or winning variant of a completed A/B test

abStatus__eq=MASTER

Active B page

abStatus__eq=VARIANT

Losing variant of a completed A/B test

abStatus__eq=LOSER_VARIANT

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 have been selected, i.e. there isn’t an active B page.

Filtering: Multi-language 

Description

Query Params 

Primary page in a multi-language group

translatedFromId__is_null

Variation page in a multi-language group

translatedFromId__not_null

Page with specific Language* (German)

language__in=de

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

Sorting

You can also apply sorting to query parameters.  You can specify the property name as a value to the query parameter `sort` to return pages sorted by the specified property. You can reverse the sort by adding a - to the property name. For example: sort=-publishDate. 


By combining query parameters for filtering, sorting and paging, you can retrieve the pages that 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.

Shell script 
curl https://api.hubapi.com/cms/v3/pages/landing-pages?sort=-updatedAt&&language__not_null&limit=10&offset=10 \
  --request POST \
  --header "Content-Type: application/json"

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, set the domain and slug fields. Note that the url field is generated and cannot be updated. Learn more about creating and customizing pages within HubSpot.

Editing Pages

Pages in HubSpot have both draft and live versions. The draft version may be updated without affecting the live page content. Drafts can be reviewed and then published by a user working in HubSpot. They may also be scheduled for publication at a future time via the /schedule endpoint. Draft changes can be discarded via the /reset endpoint, allowing users to go back to the current live version of the page without disruption. 

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 content editor in HubSpot is the simplest way to modify website content.

You can modify the widgets, widgetContainers, and layoutSections properties 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).

The properties provided in the supplied payload will override the existing draft properties without any complex merging logic. Consequently, when updating nested properties such as those within the widgets, widgetContainers, or layoutSections of the page, you must include the full definition of the object. Partial updates are not supported.

Publishes Changes to Live Content

Unpublished changes to a published page can be pushed live via a POST request to the {objectId}/draft/push-live endpoint. This endpoint accepts no payload and will only update an already published page, not publish a drafted page.

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. Learn more about scheduling page publication. 

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.

Run 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. Learn more about 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

In HubSpot, you can group together language variants of the same content. Learn more about working with multi-language pages in HubSpot. 

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. This property 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.

Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.