Account & Settings
App Management
Authentication
Automation
Communication preferences
Conversations
Events
Files
Marketing
Scheduler
Webhooks
Webhooks journal
curl --request POST \
--url https://api.hubapi.com/url-mappings/2026-03/url-mappings \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: */*' \
--data '
{
"cdnPurgeEmbargoTime": 123,
"contentGroupId": 123,
"cosObjectType": "ACCESS_GROUP_MEMBERSHIP",
"created": 123,
"createdById": 123,
"deletedAt": 123,
"destination": "<string>",
"id": 123,
"internallyCreated": true,
"isActive": true,
"isMatchFullUrl": true,
"isMatchQueryString": true,
"isOnlyAfterNotFound": true,
"isPattern": true,
"isProtocolAgnostic": true,
"isRegex": true,
"isTrailingSlashOptional": true,
"label": "<string>",
"lastUsedAt": 123,
"name": "<string>",
"note": "<string>",
"portalId": 123,
"precedence": 123,
"redirectStyle": 123,
"routePrefix": "<string>",
"updated": 123,
"updatedById": 123
}
'{
"message": "Invalid input (details will vary based on the error)",
"correlationId": "aeb5f871-7f07-4993-9211-075dc63e7cbf",
"category": "VALIDATION_ERROR",
"links": {
"knowledge-base": "https://www.hubspot.com/products/service/knowledge-base"
}
}Create a mapping
Create a new URL mapping in your HubSpot account. This endpoint allows you to define URL redirections and mappings, which can be useful for managing site navigation and SEO. The request body must include all required properties of the UrlMapping schema.
curl --request POST \
--url https://api.hubapi.com/url-mappings/2026-03/url-mappings \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: */*' \
--data '
{
"cdnPurgeEmbargoTime": 123,
"contentGroupId": 123,
"cosObjectType": "ACCESS_GROUP_MEMBERSHIP",
"created": 123,
"createdById": 123,
"deletedAt": 123,
"destination": "<string>",
"id": 123,
"internallyCreated": true,
"isActive": true,
"isMatchFullUrl": true,
"isMatchQueryString": true,
"isOnlyAfterNotFound": true,
"isPattern": true,
"isProtocolAgnostic": true,
"isRegex": true,
"isTrailingSlashOptional": true,
"label": "<string>",
"lastUsedAt": 123,
"name": "<string>",
"note": "<string>",
"portalId": 123,
"precedence": 123,
"redirectStyle": 123,
"routePrefix": "<string>",
"updated": 123,
"updatedById": 123
}
'{
"message": "Invalid input (details will vary based on the error)",
"correlationId": "aeb5f871-7f07-4993-9211-075dc63e7cbf",
"category": "VALIDATION_ERROR",
"links": {
"knowledge-base": "https://www.hubspot.com/products/service/knowledge-base"
}
}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.
Supported products
Supported products
Required Scopes
Required Scopes
Authorizations
The access token received from the authorization server in the OAuth 2.0 flow.
Body
A Unix timestamp in milliseconds indicating the embargo time for CDN purge related to the URL mapping.
A 64-bit integer representing the content group associated with the URL mapping.
A string representing the type of content object associated with the URL mapping. Valid values include various content types such as 'CONTENT', 'LAYOUT', 'FILE', etc.
ACCESS_GROUP_MEMBERSHIP, APP_PAGE, BLOCK, BLOG, BLOG_AUTHOR, BRAND_BUSINESS_UNIT, BRAND_SETTINGS, CONTACT_MEMBERSHIP, CONTENT, CONTENT_EMBED, CONTENT_FOLDER, CONTENT_GROUP, CRM_OBJECT, CRM_OBJECT_TYPE, CUSTOM_WIDGET, CUSTOMER_PORTAL, DATA_QUERY, DESIGN_FOLDER, DOMAIN, DOMAIN_SETTINGS, EMAIL_ADDRESS, EXTENSION_RESOURCE, FILE, FOLDER, FOLLOW_ME, FORM, GLOBAL_CONTENT, HUBDB_TABLE, HUBDB_TABLE_ROW, IMAGE, JS_PROJECT_COMPONENT, KNOWLEDGE_BASE, KNOWLEDGE_CATEGORY, KNOWLEDGE_CATEGORY_TRANSLATION, KNOWLEDGE_HOMEPAGE_CATEGORY, LAYOUT, LAYOUT_SECTION, LIST_MEMBERSHIP, MARKETPLACE_LISTING, PASSWORD_PROTECTED, PAYMENT, PERSONALIZATION_TOKEN, PLACEMENT, PROJECT, QUOTE_TEMPLATE, RAW_ASSET, REDIRECT_URL, SECTION, SERVERLESS_FUNCTION, SITE_MAP, SITE_MENU, SITE_SETTINGS, SUBSCRIPTIONS_SETTINGS, TAG, THEME, THEME_SETTINGS, UNRESTRICTED_ACCESS, URL_MAPPING, VIDEO_PLAYER, WIDGET, WORKFLOW A Unix timestamp in milliseconds indicating when the URL mapping was created.
The identifier of the user who created the URL mapping.
A Unix timestamp in milliseconds indicating when the URL mapping was deleted.
The destination URL to which the routePrefix is redirected.
The unique identifier for the URL mapping, represented as a 64-bit integer.
A boolean indicating if the URL mapping was created internally by the system.
A boolean indicating if the URL mapping is currently active.
A boolean indicating if the full URL should be matched.
A boolean indicating if the query string should be matched.
A boolean indicating if the mapping should only be applied after a 404 Not Found response.
A boolean indicating if the routePrefix is a pattern.
A boolean indicating if the mapping should ignore the URL protocol (http/https).
A boolean indicating if the routePrefix should be treated as a regular expression.
A boolean indicating if the trailing slash in the URL is optional.
A label for the URL mapping.
The name of the URL mapping.
A string containing notes about the URL mapping.
The identifier for the HubSpot portal associated with this URL mapping.
An integer representing the precedence of the URL mapping, used to determine order of evaluation.
An integer representing the style of redirection used.
The prefix of the URL path that is being mapped.
A Unix timestamp in milliseconds indicating when the URL mapping was last updated.
The identifier of the user who last updated the URL mapping.
Response
The error category
A unique identifier for the request. Include this value with any error reports or support tickets
"aeb5f871-7f07-4993-9211-075dc63e7cbf"
A human readable message describing the error along with remediation steps where appropriate
"An error occurred"
Context about the error condition
Show child attributes
Show child attributes
"{invalidPropertyName=[propertyValue], missingScopes=[scope1, scope2]}"
further information about the error
Show child attributes
Show child attributes
A map of link names to associated URIs containing documentation about the error or recommended remediation steps
Show child attributes
Show child attributes
A specific category that contains more specific detail about the error
Was this page helpful?