Skip to main content

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.

Use the preference page URL API to generate URLs for a contact’s specific email preference pages, which allows them to manage their email preferences from within authenticated areas of your website.
Please note:
  • This API is currently in beta and is subject to change based on testing and feedback. By using these endpoints you agree to adhere to HubSpot’s Developer Terms & Developer Beta Terms. You also acknowledge and understand the risk associated with testing an unstable API.
  • Each set of URLs is generated for a specific contact to edit their own preferences. Ensure each link is only shared securely with the owner of the associated email address.
To generate subscription preferences URLs, ensure that your app has authorized the scopes listed below:
  • communication_preferences.read_write OR
  • communication_preferences.read AND communication_preferences.write

​
Generate subscription preference page URLs

Please note:The API described in this article references business units, which is the former name for brands. This change does not impact the businessUnitId parameter.
To generate preference page URLs for a contact, make a POST request to /communication-preferences/v4/links/generate and provide the following query parameters:
  • channel (required): communication channel, required to be EMAIL.
  • businessUnitId: you can optionally include the ID of a specific brand, which results in the links that take contacts to pages customized for that brand. On these pages, only subscriptions within that brand will be displayed.
In the request body, you can also include the following properties:
  • subscriberIdString (required): email address of the contact for whom the subscription preferences page is being generated.
  • language: language for the preferences page. For translations to work as expected, you should select a language associated with a subscription type. If no language is specified, the system may default to your account’s default language or English.
  • subscriptionId: ID of a specific subscription type, which may result in that subscription type being highlighted on the preferences page. This parameter must be included to return an unsubscribeSingleUrl link.
The preference page URLs will be returned within the results field of the response. For example, if you wanted to generate a unique email preference page for bh@hubspot.com associated with a businessUnitId of 887987898, you’d make a POST to https://api.hubapi.com/communication-preferences/v4/links/generate?businessUnitId=887987898&channel=EMAIL, then include a request body that resembled the following: 
{
  "subscriptionId": 123,
  "subscriberIdString": "bh@hubspot.com",
  "language": "es"
}
The resulting response will look like the following: 
{
  "status": "SUCCESS",
  "results": {
    "subscriberIdString": "bh@hubspot.com",
    "managePreferencesUrl": "https://www.hubspot.com/hs/preferences-center/es/page?data=W2nXS...",
    "unsubscribeAllUrl": "https://www.hubspot.com/hs/preferences-center/es/direct?data=W2nXS...",
  }
}

​
Troubleshoot errors

If your request returns an error, review the error message and code, then follow the troubleshooting steps for that error.

​
Understand error messages

Most errors follow the following format: 
{
  "status": "error",
  "message": "Human-readable error description",
  "correlationId": "unique-request-id",
  "errorCode": "ERROR_CODE_CONSTANT",
  "category": "ERROR_CATEGORY",
  "context": {
    "subscriberIdString": ["user@example.com"],
    "language": ["en"],
    "subscriptionId": ["123"]
  }
}
The information you will find in each property is listed below:
Property nameDescription
statusOutcome of the request; for errors, this will always return “error”.
messageDescription of what went wrong.
correlationIdUnique identifier for this request.
errorCodeMachine-readable code identifying the specific error type.
categoryHigh-level error classification, such as VALIDATION_ERROR.
contextObject containing request parameters that may have caused the error.
subscriberIdStringEmail address (subscriber identifier) from the request
languageLanguage parameter from the request, if provided.
subscriptionIdSubscription ID from the request, if provided.
businessUnitIdBusiness unit ID from the request, if provided.

​
Troubleshoot common errors

Learn more about the errors that can occur when generating a subscription preferences page URL.

​
Language not configured

  • Error code: LANGUAGE_NOT_CONFIGURED
  • Description: the provided language parameter is invalid.
  • Troubleshooting steps: assign one of the languages listed in the error property “message” to a subscription type, then wait several minutes to try again.

​
Subscription type not found

  • Error code: SUBSCRIPTION_TYPE_NOT_FOUND
  • Description: the provided subscriptionId parameter is invalid.
  • Troubleshooting steps: get all subscription types, then confirm that one of them uses the subscriptionId included in the request.

​
Subscription type & brand mismatch

  • Error code: SUBSCRIPTION_TYPE_BUSINESS_UNIT_MISMATCH
  • Description: the provided subscriptionId belongs to a different brand than specified in businessUnitId.
  • Troubleshooting steps: to resolve this error, try the following:
    • Use a subscription type that belongs to the specified brand.
    • Omit the businessUnitId parameter.
    • Get all subscription types and confirm which subscription types are used for each brand.

​
Contact not found

  • Error code: CONTACT_NOT_FOUND
  • Description: the provided email address is not associated with a contact record in the HubSpot account.
  • Troubleshooting steps: to resolve this error, try the following:
    • Verify the email address belongs to a contact in the HubSpot account.
    • Create a contact associated with this email address, then try again.

​
Invalid channel

  • Description: the channel parameter contains a value other than EMAIL.
  • Troubleshooting steps: use channel=EMAIL as the query parameter.
Last modified on March 30, 2026