URL redirects API - HubSpot docs

Scope requirements

URL redirects allow you to redirect traffic from a HubSpot-hosted page to any URL. In HubSpot, you can also update URL redirects in bulk and use a flexible pattern redirect to dynamically update the structure of URLs.

Retrieve redirects

You can retrieve URL redirects either individually by ID or by retrieving all redirects:

To retrieve all redirects, make a GET request to /cms/v3/url-redirects.
To retrieve an individual redirect, make a GET request to /cms/v3/url-redirects/{urlRedirectId}.

Retrieve all redirects

When retrieving all redirects, you can filter and sort the returned results using query parameters. For example, the following request would retrieve the first 10 redirects created after January 1, 2024:

curl https://api.hubapi.com/cms/v3/url-redirects?createdAfter=2024-01-01T00:00:00Z&limit=10 \
  --request GET \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN"

The following query parameters are available:

Parameter	Type	Description
`after`	String	The paging cursor token of the last successfully read resource. Available from `paging.next.after` in paginated responses.
`archived`	Boolean	Whether to return only results that have been archived.
`createdAfter`	String	Only return redirects created after this date (ISO 8601 format).
`createdAt`	String	Only return redirects created on exactly this date (ISO 8601 format).
`createdBefore`	String	Only return redirects created before this date (ISO 8601 format).
`limit`	Integer	Maximum number of results per page.
`sort`	Array	Specify the order in which the URL redirects are returned.
`updatedAfter`	String	Only return redirects last updated after this date (ISO 8601 format).
`updatedAt`	String	Only return redirects last updated on exactly this date (ISO 8601 format).
`updatedBefore`	String	Only return redirects last updated before this date (ISO 8601 format).

The response includes a total count and an array of redirect objects:

{
  "total": 2,
  "results": [
    {
      "id": "3212223134",
      "createdAt": "2017-07-24T17:24:09.141Z",
      "updatedAt": "2017-07-24T17:24:09.141Z",
      "routePrefix": "http://test.hs-sites.com/(?P<page_slug>.*)",
      "destination": "http://www.example.online/{page_slug}",
      "redirectStyle": 301,
      "isOnlyAfterNotFound": true,
      "isMatchFullUrl": true,
      "isMatchQueryString": false,
      "isPattern": false,
      "isTrailingSlashOptional": true,
      "isProtocolAgnostic": true,
      "precedence": 3
    }
  ],
  "paging": {
    "next": {
      "after": "Mg%3D%3D",
      "link": "https://api.hubspot.com/cms/v3/url-redirects?after=Mg%3D%3D"
    }
  }
}

Retrieve a single redirect

To retrieve details for a specific redirect, make a GET request to /cms/v3/url-redirects/{urlRedirectId}. For example, the request below would retrieve the details for the redirect with ID 3212223134:

curl https://api.hubapi.com/cms/v3/url-redirects/3212223134 \
  --request GET \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN"

Create a redirect

To create a new URL redirect, make a POST request to /cms/v3/url-redirects. For example, the request below would create a permanent redirect from /old-page to /new-page:

curl https://api.hubapi.com/cms/v3/url-redirects \
  --request POST \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "routePrefix": "/old-page",
    "destination": "/new-page",
    "redirectStyle": 301
  }'

The following request body parameters are available:

Parameter	Type	Description
`routePrefix`	String	The target incoming URL, path, or pattern to match for redirection.
`destination`	String	The location that the target URL should be redirected to if it matches the `routePrefix`.
`redirectStyle`	Integer	The type of redirect to create. Options include: `301` (permanent), `302` (temporary), or `305` (proxy).
`isOnlyAfterNotFound`	Boolean	Whether the URL redirect mapping should apply only if a live page on the URL isn’t found. If `false`, the URL redirect mapping will take precedence over any existing page.
`isMatchFullUrl`	Boolean	Whether the `routePrefix` should match on the entire URL, including the domain.
`isMatchQueryString`	Boolean	Whether the `routePrefix` should match on the entire URL path, including the query string.
`isPattern`	Boolean	Whether the `routePrefix` should match based on pattern.
`isProtocolAgnostic`	Boolean	Whether the `routePrefix` should match both HTTP and HTTPS protocols.
`isTrailingSlashOptional`	Boolean	Whether a trailing slash will be ignored.
`precedence`	Integer	Used to prioritize URL redirection. If a given URL matches more than one redirect, the one with the lower precedence will be used.

Update a redirect

To update an existing URL redirect, make a PATCH request to /cms/v3/url-redirects/{urlRedirectId}. For example, the request below would update the redirect with ID 3212223134 to change the destination URL:

curl https://api.hubapi.com/cms/v3/url-redirects/3212223134 \
  --request PATCH \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "destination": "/updated-page"
  }'

The following request body parameters are available:

Parameter	Type	Description
`routePrefix`	String	The target incoming URL, path, or pattern to match for redirection.
`destination`	String	The location that the target URL should be redirected to if it matches the `routePrefix`.
`redirectStyle`	Integer	The type of redirect to create. Options include: `301` (permanent), `302` (temporary), or `305` (proxy).
`isOnlyAfterNotFound`	Boolean	Whether the URL redirect mapping should apply only if a live page on the URL isn’t found. If `false`, the URL redirect mapping will take precedence over any existing page.
`isMatchFullUrl`	Boolean	Whether the `routePrefix` should match on the entire URL, including the domain.
`isMatchQueryString`	Boolean	Whether the `routePrefix` should match on the entire URL path, including the query string.
`isPattern`	Boolean	Whether the `routePrefix` should match based on pattern.
`isProtocolAgnostic`	Boolean	Whether the `routePrefix` should match both HTTP and HTTPS protocols.
`isTrailingSlashOptional`	Boolean	Whether a trailing slash will be ignored.
`precedence`	Integer	Used to prioritize URL redirection. If a given URL matches more than one redirect, the one with the lower precedence will be used.

Delete a redirect

To delete an existing URL redirect, make a DELETE request to /cms/v3/url-redirects/{urlRedirectId}. For example, the request below would delete the redirect with ID 3212223134:

curl https://api.hubapi.com/cms/v3/url-redirects/3212223134 \
  --request DELETE \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN"

A successful deletion returns a 204 No Content response with no body.

​Retrieve redirects

​Retrieve all redirects

​Retrieve a single redirect

​Create a redirect

​Update a redirect

​Delete a redirect