> ## 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.

---
id: 4b9ef053-c562-42de-90e7-01dc8f29a6ff
---

# Generate preference page URLs

> Generate preference page URLs to allow marketing email recipients to manage their subscription preferences.

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.

<Warning>
  **Please note:**

  * This API is currently [in beta](https://app.hubspot.com/l/product-updates/?rollout=247887) and is subject to change based on testing and feedback. By using these endpoints you agree to adhere to HubSpot's [Developer Terms](https://legal.hubspot.com/hs-developer-terms) & [Developer Beta Terms](https://legal.hubspot.com/hubspot-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.
</Warning>

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

<Warning>
  **Please note:**

  The API described in this article references business units, which is the former name for [brands](https://knowledge.hubspot.com/branding/manage-your-brands-with-hubspot-brands). This change does <u>not</u> impact the `businessUnitId` parameter.
</Warning>

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](https://knowledge.hubspot.com/marketing-email/set-up-email-subscription-types). 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:

```json theme={null}
{
  "subscriptionId": 123,
  "subscriberIdString": "bh@hubspot.com",
  "language": "es"
}
```

The resulting response will look like the following:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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 name        | Description                                                          |
| -------------------- | -------------------------------------------------------------------- |
| `status`             | Outcome of the request; for errors, this will always return "error". |
| `message`            | Description of what went wrong.                                      |
| `correlationId`      | Unique identifier for this request.                                  |
| `errorCode`          | Machine-readable code identifying the specific error type.           |
| `category`           | High-level error classification, such as `VALIDATION_ERROR`.         |
| `context`            | Object containing request parameters that may have caused the error. |
| `subscriberIdString` | Email address (subscriber identifier) from the request               |
| `language`           | Language parameter from the request, if provided.                    |
| `subscriptionId`     | Subscription ID from the request, if provided.                       |
| `businessUnitId`     | Business 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](/api-reference/legacy/communication-preferences/guide#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](/api-reference/legacy/communication-preferences/guide#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.