There's a new version of the HubSpot API

Check out the new API

As of November 30, 2022, HubSpot API keys are no longer a supported authentication method for accessing HubSpot APIs. Instead, you should use a private app access token or OAuth to authenticate API calls. Learn more about this change and how to migrate an API key integration to use a private app instead.

List url mappings

Last updated May 31, 2023

GET /url-mappings/v3/url-mappings

Method Details

HTTP Methods:

GET

Response Format:

json

Requires Authentication?

Yes

Rate Limited?

Yes

Headers

User-Agent

Products:

Marketing

Get all URL mappings. Supports paging and filtering.

Required Parameters How to use Description
OAuth access token or private app access token Authorization: Bearer {token} header Used to authenticate the request. Please see this page for more details about authentication.

Optional query string filters & options

Some parameters support "range" filters via double-underscored param suffixes, like '__gt'. If a parameter supports a filter type of 'gt', that means you can append a double-underscore and 'gt' to the parameter name to find all items greater than a specified value.

For example, the following query will find all items with the 'updated' time greater than 1364424600000: https://api.hubapi.com/url-mappings/v3/url-mappings?updated__gt=1364424600000

Parameter name Description
id Search for mappings by id. Supports exact value matching and the 'in' range filter (e.g. id__in=348109009,348109019)
routePrefix Search for mappings with a specific routePrefix string value. Must be an exact value match.
destination Search for mappings with a specific destination string value. Must be an exact value match.
contentGroupId Search for mappings created for a specific content group ID (aka blog ID). Must be an exact value match.
name Search for mappings by internal name. Supports exact value matching and the 'in' range filter (e.g. name__in=list-by-author,list-by-topic)
isOnlyAfterNotFound Filter results by this boolean field's value (true, false)
isRegex Filter results by this boolean field's value (true, false)
isMatchFullUrl Filter results by this boolean field's value (true, false)
isPattern Filter results by this boolean field's value (true, false)
created Filter results by creation date, in milliseconds since the epoch. Supports exact value matching and the following range filters: range, gt, gte, lt, lte
updated Filter results by last update date, in milliseconds since the epoch. Supports exact value matching and the following range filters: range, gt, gte, lt, lte
deletedAt Filter results by deletion date, in milliseconds since the epoch. Supports exact value matching and the following range filters: range, gt, gte, lt, lte. Note: Deleted mappings are excluded from results unless this filter is specified.
limit The maximum number of items to return. Defaults to 20.
offset The offset from the beginning of the result set from which to start returning results. Used for paging. Defaults to 0.
casing Use the casing=snake parameter to change the API's casing for all query parameters (including those above) and JSON fields (below) to snake_case, rather than camelCase, which is the default. This option is provided for backwards-compatibility and ease of migration from Content v2 APIs, which used snake_case.

JSON Fields returned in the response

Field name Type Description
id string The unique id of the url mapping
portalId string The hub id
created long When the url mapping was first created, in milliseconds since the epoch
updated long When the url mapping was last updated, in milliseconds since the epoch
routePrefix string The incoming URL, path, or pattern to match
destination string The URL to redirect to
redirectStyle int The type of redirect this mapping creates: 301 (permanent) or 302 (temporary)
contentGroupId long The ID of the content group (aka blog) that this url mapping exists for, if any. Otherwise null.
isOnlyAfterNotFound boolean If true, the URL mapping will only be applied if a live page matching the URL is not found. If false, the URL mapping will take precedence over any existing page.
isRegex boolean Deprecated. Indicates whether this mapping was created as a regular expression pattern (this option is no longer supported for new mappings)
isMatchFullUrl boolean If true, the 'routePrefix' should match on the entire URL including the domain
isMatchQueryString boolean If true, the 'routePrefix' should match on the entire URL path including the query string
isPattern boolean If true, this is a flexible pattern based URL Mapping.
name string An name used to identify the type of pattern this is. Used mostly for blog and other internally-created mappings.
precedence integer If a URL matches more than one mapping, the one with the lower precedence applies
deletedAt long When the url mapping was deleted, in milliseconds since the epoch. Zero if the url mapping was never deleted. Use a DELETE request to properly soft delete a url mapping - do not set this value directly.

About

Jobs

Learn Inbound

Support

Locations

HubSpot, Inc.
25 First Street, 2nd Floor
Cambridge, MA 02141
European Headquarters
Ground Floor, Two Dockland Central
Guild Street, Dublin 1
Asia/Pacific Office
20 Hunter St, Level 7
Sydney NSW 2000
View our other locations
Example GET URL: https://api.hubapi.com/url-mappings/v3/url-mappings Example response: { "objects": [ { "id": 25323248, "portalId": 62515, "created": 1364424600000, "updated": 1486728066193, "routePrefix": "http://demo-hubapi.sites.hubspot.com/(?P.*)", "destination": "/123456", "redirectStyle": 301, "contentGroupId": null, "isOnlyAfterNotFound": true, "isRegex": true, "isMatchFullUrl": true, "isMatchQueryString": false, "isPattern": false, "isTrailingSlashOptional": false, "isProtocolAgnostic": false, "name": "redirect-to-primary", "precedence": 1000000005, "deletedAt": 0 }, { "id": 3274869361, "portalId": 62515, "created": 1441133924669, "updated": 1441133924669, "routePrefix": "/about-us/contact-us", "destination": "/my-api-demo-page-slug", "redirectStyle": 301, "contentGroupId": null, "isOnlyAfterNotFound": true, "isRegex": false, "isMatchFullUrl": false, "isMatchQueryString": false, "isPattern": false, "isTrailingSlashOptional": false, "isProtocolAgnostic": false, "name": "", "precedence": 1000000010, "deletedAt": 0 }, { "id": 3670908280, "portalId": 62515, "created": 1446552486488, "updated": 1446552486488, "routePrefix": "http://62515.hs-sites.com/blog/author/hub-spot", "destination": "http://62515.hs-sites.com/blog/author/hub-spot", "redirectStyle": 301, "contentGroupId": 351076997, "isOnlyAfterNotFound": true, "isRegex": false, "isMatchFullUrl": true, "isMatchQueryString": false, "isPattern": false, "isTrailingSlashOptional": false, "isProtocolAgnostic": false, "name": "Author renamed and moved", "precedence": 2000000000, "deletedAt": 0 }, { "id": 4349637888, "portalId": 62515, "created": 1471912874076, "updated": 1471912874076, "routePrefix": "http://62515.hs-sites.com/blog/topic/test", "destination": "http://62515.hs-sites.com/blog/topic/merged-topdic", "redirectStyle": 301, "contentGroupId": null, "isOnlyAfterNotFound": true, "isRegex": false, "isMatchFullUrl": true, "isMatchQueryString": false, "isPattern": false, "isTrailingSlashOptional": true, "isProtocolAgnostic": true, "name": "topic-renamed-or-moved", "precedence": 2000000000, "deletedAt": 0 }, { "id": 4776068243, "portalId": 62515, "created": 1487255328957, "updated": 1487255328957, "routePrefix": "https?://62515.hs-sites.com/(?P.*)", "destination": "http://ww1.photosi.com/{page_slug}", "redirectStyle": 301, "contentGroupId": null, "isOnlyAfterNotFound": true, "isRegex": true, "isMatchFullUrl": true, "isMatchQueryString": false, "isPattern": false, "isTrailingSlashOptional": true, "isProtocolAgnostic": true, "name": "initial-primary-domain", "precedence": 2000000002, "deletedAt": 0 }, { "id": 4887023810, "portalId": 62515, "created": 1488365940939, "updated": 1488365940939, "routePrefix": "http://demo-hubapi.hs-sites.com/blog/topic/tester9", "destination": "http://demo-hubapi.hs-sites.com/blog/topic/udpzegqdvkf", "redirectStyle": 301, "contentGroupId": null, "isOnlyAfterNotFound": true, "isRegex": false, "isMatchFullUrl": true, "isMatchQueryString": false, "isPattern": false, "isTrailingSlashOptional": true, "isProtocolAgnostic": true, "name": "topic-renamed-or-moved", "precedence": 2000000000, "deletedAt": 0 }, { "id": 5425198869, "portalId": 62515, "created": 1510140093185, "updated": 1510140093185, "routePrefix": "/2017/11/08/first-blog-post", "destination": "/blog/2017/11/08/first-blog-post", "redirectStyle": 301, "contentGroupId": 351076997, "isOnlyAfterNotFound": true, "isRegex": false, "isMatchFullUrl": false, "isMatchQueryString": false, "isPattern": false, "isTrailingSlashOptional": true, "isProtocolAgnostic": true, "name": "blog-import-redirect", "precedence": 100000041, "deletedAt": 0 } ], "total": 7, "limit": 20, "offset": 0, "message": null, "totalCount": 7 }