HubSpot: Communication preferences schemas

← Communication preferences operations · All schemas

Batch retrieve contacts who have opted out of all communications — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING results item

Field	Type	Presence	Description and constraints
$	object	Root
subscriberIdString	string	Required within parent	The contact's email address.
wideStatuses	array	Required within parent	An array containing the wide status results for the operation.
wideStatuses[]	Model	Each item	Expand Retrieve a contact's unsubscribed status — response body — results item

Referenced models: Retrieve a contact's unsubscribed status — response body — results item

Batch retrieve contacts who have opted out of all communications — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING — Batch Response Public Wide Status Bulk Response

Field	Type	Presence	Description and constraints
$	object	Root
completedAt	string	Required within parent	The date and time when the batch process was completed. Format: date-time
links	object	Optional	A collection of related links associated with the batch response. Additional keys: see wildcard field
links.*	string	Additional keys
requestedAt	string	Optional	The date and time when the batch request was made. Format: date-time
results	array	Required within parent	The array of results from the batch process, each containing subscription status information.
results[]	Model	Each item	Expand Batch retrieve contacts who have opted out of all communications — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING results item
startedAt	string	Required within parent	The date and time when the batch process began. Format: date-time
status	string	Required within parent	The current status of the batch process, with possible values: PENDING, PROCESSING, CANCELED, COMPLETE. Known values: CANCELED, COMPLETE, PENDING, PROCESSING

Referenced models: Batch retrieve contacts who have opted out of all communications — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING results item

Batch retrieve contacts who have opted out of all communications — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING — Batch Response Public Wide Status Bulk Response With Errors

Field	Type	Presence	Description and constraints
$	object	Root
completedAt	string	Required within parent	The date and time when the operation was completed. Format: date-time
errors	array	Optional	An array of error objects detailing any issues encountered during the operation.
errors[]	Model	Each item	Expand Batch update subscription status — response body — errors item
links	object	Optional	An object containing related links, where each key is a link name and each value is a URL. Additional keys: see wildcard field
links.*	string	Additional keys
numErrors	JSON	Optional
numErrors (anyOf 1)	integer	Alternative	The number of errors encountered during the operation. Format: int32
numErrors (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
requestedAt	string	Optional	The date and time when the operation was requested. Format: date-time
results	array	Required within parent	An array containing the results of the operation.
results[]	Model	Each item	Expand Batch retrieve contacts who have opted out of all communications — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING results item
startedAt	string	Required within parent	The date and time when the operation started. Format: date-time
status	string	Required within parent	The current status of the operation, which can be PENDING, PROCESSING, CANCELED, or COMPLETE. Known values: CANCELED, COMPLETE, PENDING, PROCESSING

Referenced models: Batch update subscription status — response body — errors item, Batch retrieve contacts who have opted out of all communications — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING results item

Batch retrieve subscription statuses — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
inputs	array	Required within parent	A list of strings representing the inputs for batch operations.
inputs[]	string	Each item

Batch retrieve subscription statuses — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING results item

Field	Type	Presence	Description and constraints
$	object	Root
statuses	array	Required within parent	An array of subscription status objects for the contact.
statuses[]	Model	Each item	Expand Batch update subscription status — response body — results item
subscriberIdString	string	Required within parent	The email address of the contact.

Referenced models: Batch update subscription status — response body — results item

Batch retrieve subscription statuses — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING — Batch Response Public Status Bulk Response

Field	Type	Presence	Description and constraints
$	object	Root
completedAt	string	Required within parent	The date and time when the batch process was completed. Format: date-time
links	object	Optional	A collection of related links associated with the batch response. Additional keys: see wildcard field
links.*	string	Additional keys
requestedAt	string	Optional	The date and time when the batch request was made. Format: date-time
results	array	Required within parent	The array of results from the batch process, each containing subscription status information.
results[]	Model	Each item	Expand Batch retrieve subscription statuses — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING results item
startedAt	string	Required within parent	The date and time when the batch process began. Format: date-time
status	string	Required within parent	The current status of the batch process, with possible values: PENDING, PROCESSING, CANCELED, COMPLETE. Known values: CANCELED, COMPLETE, PENDING, PROCESSING

Referenced models: Batch retrieve subscription statuses — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING results item

Batch retrieve subscription statuses — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING — Batch Response Public Status Bulk Response With Errors

Field	Type	Presence	Description and constraints
$	object	Root
completedAt	string	Required within parent	The date and time when the operation was completed. Format: date-time
errors	array	Optional	An array of error objects detailing any issues encountered during the operation.
errors[]	Model	Each item	Expand Batch update subscription status — response body — errors item
links	object	Optional	An object containing related links, where each key is a link name and each value is a URL. Additional keys: see wildcard field
links.*	string	Additional keys
numErrors	JSON	Optional
numErrors (anyOf 1)	integer	Alternative	The number of errors encountered during the operation. Format: int32
numErrors (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
requestedAt	string	Optional	The date and time when the request was made. Format: date-time
results	array	Required within parent	An array containing the results of the operation.
results[]	Model	Each item	Expand Batch retrieve subscription statuses — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING results item
startedAt	string	Required within parent	The date and time when the operation started. Format: date-time
status	string	Required within parent	The current status of the operation, which can be PENDING, PROCESSING, CANCELED, or COMPLETE. Known values: CANCELED, COMPLETE, PENDING, PROCESSING

Referenced models: Batch update subscription status — response body — errors item, Batch retrieve subscription statuses — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING results item

Batch unsubscribe contacts from all subscriptions — response body

Field	Type	Presence	Description and constraints
$	object	Root
completedAt	string	Required within parent	The date and time when the bulk opt-out operation was completed. Format: date-time
errors	array	Optional	An array of error objects detailing any issues encountered during the bulk opt-out operation.
errors[]	Model	Each item	Expand Batch update subscription status — response body — errors item
links	object	Optional	A collection of URLs linking to related resources or documentation. Additional keys: see wildcard field
links.*	string	Additional keys
numErrors	JSON	Optional
numErrors (anyOf 1)	integer	Alternative	The total number of errors encountered during the bulk opt-out operation. Format: int32
numErrors (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
requestedAt	string	Optional	The date and time when the bulk opt-out request was made. Format: date-time
results	array	Required within parent	An array containing the results of the bulk opt-out from all communications operation.
results[]	Model	Each item	Expand Batch unsubscribe contacts from all subscriptions — response body — results item
startedAt	string	Required within parent	The date and time when the bulk opt-out operation began. Format: date-time
status	string	Required within parent	The current status of the bulk opt-out operation, which can be PENDING, PROCESSING, CANCELED, or COMPLETE. Known values: CANCELED, COMPLETE, PENDING, PROCESSING

Referenced models: Batch update subscription status — response body — errors item, Batch unsubscribe contacts from all subscriptions — response body — results item

Batch unsubscribe contacts from all subscriptions — response body — results item

Field	Type	Presence	Description and constraints
$	object	Root
statuses	array	Optional	An array of subscription status objects for the contact.
statuses[]	Model	Each item	Expand Batch update subscription status — response body — results item
subscriberIdString	string	Required within parent	The email address of the contact.

Referenced models: Batch update subscription status — response body — results item

Batch update subscription status — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
inputs	array	Required within parent	An array of PublicStatusRequest objects, each representing a subscription status update request. This property is required.
inputs[]	Model	Each item	Expand Batch update subscription status — request body — body inputs item

Referenced models: Batch update subscription status — request body — body inputs item

Batch update subscription status — request body — body inputs item

Field	Type	Presence	Description and constraints
$	object	Root
channel	string	Required within parent	The type of communication channel. Currently, only `EMAIL` is supported. One of: EMAIL
legalBasis	string	Optional	The legal basis for communication. One of: CONSENT_WITH_NOTICE, LEGITIMATE_INTEREST_CLIENT, LEGITIMATE_INTEREST_OTHER, LEGITIMATE_INTEREST_PQL, NON_GDPR, PERFORMANCE_OF_CONTRACT, PROCESS_AND_STORE
legalBasisExplanation	string	Optional	The explanation for the legal basis.
statusState	string	Required within parent	The status of the contact's subscription. One of: NOT_SPECIFIED, SUBSCRIBED, UNSUBSCRIBED
subscriberIdString	string	Required within parent	The contact's email address.
subscriptionId	integer	Required within parent	The ID of the subscription to update. Format: int64

Batch update subscription status — response body

Field	Type	Presence	Description and constraints
$	object	Root
completedAt	string	Required within parent	The date and time when the batch operation was completed. Format: date-time
errors	array	Optional	An array of error objects detailing any issues encountered.
errors[]	Model	Each item	Expand Batch update subscription status — response body — errors item
links	object	Optional	URLs linking to related resources or documentation. Additional keys: see wildcard field
links.*	string	Additional keys
numErrors	JSON	Optional
numErrors (anyOf 1)	integer	Alternative	The number of errors encountered during the batch operation. Format: int32
numErrors (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
requestedAt	string	Optional	The date and time when the request was made. Format: date-time
results	array	Required within parent	An array containing the results of the batch operation.
results[]	Model	Each item	Expand Batch update subscription status — response body — results item
startedAt	string	Required within parent	The date and time when the batch operation started. Format: date-time
status	string	Required within parent	The current status of the batch operation, which can be PENDING, PROCESSING, CANCELED, or COMPLETE. Known values: CANCELED, COMPLETE, PENDING, PROCESSING

Referenced models: Batch update subscription status — response body — errors item, Batch update subscription status — response body — results item

Batch update subscription status — response body — errors item

Field	Type	Presence	Description and constraints
$	object	Root	Ye olde error
category	string	Required within parent	A string that categorizes the type of error.
context	object	Required within parent	An object containing additional context about the error condition, with keys as context names and values as arrays of strings. Additional keys: see wildcard field
context.*	array	Additional keys
context.*[]	string	Each item
errors	array	Required within parent	An array of ErrorDetail objects providing further information about the error.
errors[]	Model	Each item	Expand Batch insert events — response body — errors item errors item
id	string	Optional	A string representing the unique identifier of the error.
links	object	Required within parent	An object mapping link names to associated URIs that contain documentation about the error or recommended remediation steps. Additional keys: see wildcard field
links.*	string	Additional keys
message	string	Required within parent	A string containing a human-readable message describing the error.
status	string	Required within parent	A string indicating the status of the error.
subCategory	object	Optional	An object providing more specific categorization of the error.

Referenced models: Batch insert events — response body — errors item errors item

Batch update subscription status — response body — results item

Field	Type	Presence	Description and constraints
$	object	Root
businessUnitId	JSON	Optional
businessUnitId (anyOf 1)	integer	Alternative	The ID of the business unit associated with the subscription. Format: int64
businessUnitId (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
channel	string	Required within parent	The type of communication channel, with 'EMAIL' as the only supported option. Known values: EMAIL
legalBasis	string	Optional	The legal basis for communication, with options including 'LEGITIMATE_INTEREST_PQL', 'LEGITIMATE_INTEREST_CLIENT', 'PERFORMANCE_OF_CONTRACT', 'CONSENT_WITH_NOTICE', 'NON_GDPR', 'PROCESS_AND_STORE', and 'LEGITIMATE_INTEREST_OTHER'. Known values: CONSENT_WITH_NOTICE, LEGITIMATE_INTEREST_CLIENT, LEGITIMATE_INTEREST_OTHER, LEGITIMATE_INTEREST_PQL, NON_GDPR, PERFORMANCE_OF_CONTRACT, PROCESS_AND_STORE
legalBasisExplanation	string	Optional	An explanation for the legal basis used for communication.
setStatusSuccessReason	string	Optional	The reason for the successful change in subscription status, such as 'RESUBSCRIBE_OCCURRED' or 'NO_STATUS_CHANGE'. Known values: NO_STATUS_CHANGE, REQUESTED_CHANGE_OCCURRED, RESUBSCRIBE_OCCURRED, UNSUBSCRIBE_FROM_ALL_OCCURRED
source	string	Required within parent	The origin or method through which the subscription status was set.
status	string	Required within parent	The current subscription status of the contact, which can be 'SUBSCRIBED', 'UNSUBSCRIBED', or 'NOT_SPECIFIED'. Known values: NOT_SPECIFIED, SUBSCRIBED, UNSUBSCRIBED
subscriberIdString	string	Required within parent	The contact's email address.
subscriptionId	JSON	Required within parent
subscriptionId (anyOf 1)	integer	Alternative	The unique identifier of the subscription. Format: int64
subscriptionId (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
subscriptionName	string	Optional	The name of the subscription.
timestamp	string	Required within parent	The date and time when the subscription status was last updated. Format: date-time

Generate subscription links — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
language	string	Optional	The language in which the generated link should be presented, represented as a string.
subscriberIdString	string	Required within parent	A string representing the unique identifier of the subscriber. This property is required.
subscriptionId	integer	Optional	The unique identifier for the subscription, represented as an integer in int64 format. Format: int64

Generate subscription links — response body

Field	Type	Presence	Description and constraints
$	object	Root
managePreferencesUrl	string	Required within parent	The URL where the subscriber can manage their communication preferences.
subscriberIdString	string	Required within parent	A string representing the unique identifier of the subscriber.
unsubscribeAllUrl	string	Required within parent	A string containing the URL for unsubscribing the subscriber from all communications.
unsubscribeSingleUrl	string	Optional	A string containing the URL to unsubscribe the subscriber from a single communication.

Retrieve a contact's unsubscribed status — response body

Field	Type	Presence	Description and constraints
$	object	Root
completedAt	string	Required within parent	The date and time when the operation was completed. Format: date-time
errors	array	Optional	An array of error objects detailing any issues encountered during the operation.
errors[]	Model	Each item	Expand Batch update subscription status — response body — errors item
links	object	Optional	An object containing related links, where each key is a link name and each value is a URL. Additional keys: see wildcard field
links.*	string	Additional keys
numErrors	JSON	Optional
numErrors (anyOf 1)	integer	Alternative	The number of errors encountered during the operation. Format: int32
numErrors (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
requestedAt	string	Optional	The date and time when the request was made. Format: date-time
results	array	Required within parent	An array containing the results of the operation.
results[]	Model	Each item	Expand Retrieve a contact's unsubscribed status — response body — results item
startedAt	string	Required within parent	The date and time when the operation started. Format: date-time
status	string	Required within parent	The current status of the operation, which can be PENDING, PROCESSING, CANCELED, or COMPLETE. Known values: CANCELED, COMPLETE, PENDING, PROCESSING

Referenced models: Batch update subscription status — response body — errors item, Retrieve a contact's unsubscribed status — response body — results item

Retrieve a contact's unsubscribed status — response body — results item

Field	Type	Presence	Description and constraints
$	object	Root
businessUnitId	JSON	Optional
businessUnitId (anyOf 1)	integer	Alternative	The ID of the business unit associated with the status. Format: int64
businessUnitId (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
channel	string	Required within parent	The type of communication channel, with 'EMAIL' as the only supported option. Known values: EMAIL
status	string	Required within parent	The subscription status of the contact, which can be 'SUBSCRIBED', 'UNSUBSCRIBED', or 'NOT_SPECIFIED'. Known values: NOT_SPECIFIED, SUBSCRIBED, UNSUBSCRIBED
subscriberIdString	string	Required within parent	The email address of the contact.
timestamp	string	Required within parent	The date and time when the status was recorded. Format: date-time
wideStatusType	string	Required within parent	The type of wide status, which can be 'PORTAL_WIDE' or 'BUSINESS_UNIT_WIDE'. Known values: BUSINESS_UNIT_WIDE, PORTAL_WIDE

Retrieve all subscription status definitions — response body

Field	Type	Presence	Description and constraints
$	object	Root
completedAt	string	Required within parent	The date and time when the operation was completed. Format: date-time
errors	array	Optional	An array of errors that occurred during the operation.
errors[]	Model	Each item	Expand Batch update subscription status — response body — errors item
links	object	Optional	A collection of related links associated with the operation. Additional keys: see wildcard field
links.*	string	Additional keys
numErrors	JSON	Optional
numErrors (anyOf 1)	integer	Alternative	The number of errors encountered during the operation. Format: int32
numErrors (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
requestedAt	string	Optional	The date and time when the operation was requested. Format: date-time
results	array	Required within parent	An array containing the results of the operation.
results[]	Model	Each item	Expand Retrieve all subscription status definitions — response body — results item
startedAt	string	Required within parent	The date and time when the operation started. Format: date-time
status	string	Required within parent	The current status of the operation, which can be PENDING, PROCESSING, CANCELED, or COMPLETE. Known values: CANCELED, COMPLETE, PENDING, PROCESSING

Referenced models: Batch update subscription status — response body — errors item, Retrieve all subscription status definitions — response body — results item

Retrieve all subscription status definitions — response body — results item

Field	Type	Presence	Description and constraints
$	object	Root
businessUnitId	JSON	Optional
businessUnitId (anyOf 1)	integer	Alternative	The ID of the business unit associated with the subscription. Format: int64
businessUnitId (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
communicationMethod	string	Optional	The method of communication for the subscription.
createdAt	string	Required within parent	The date and time when the subscription was created. Format: date-time
description	string	Required within parent	A description of the subscription.
id	string	Required within parent	The unique identifier for the subscription.
isActive	boolean	Required within parent	Indicates whether the subscription is active.
isDefault	boolean	Required within parent	Indicates whether the subscription is the default option.
isInternal	boolean	Required within parent	Indicates whether the subscription is internal.
name	string	Required within parent	The name of the subscription.
purpose	string	Optional	The purpose of the subscription.
subscriptionTranslations	array	Optional	A list of translations associated with the subscription.
subscriptionTranslations[]	Model	Each item	Expand Retrieve all subscription status definitions — response body — results item subscription Translations item
updatedAt	string	Required within parent	The date and time when the subscription was last updated. Format: date-time

Referenced models: Retrieve all subscription status definitions — response body — results item subscription Translations item

Retrieve all subscription status definitions — response body — results item subscription Translations item

Field	Type	Presence	Description and constraints
$	object	Root
createdAt	JSON	Required within parent
createdAt (anyOf 1)	integer	Alternative	The timestamp indicating when the subscription translation was created. Format: int64
createdAt (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
description	string	Required within parent	A text description of the subscription translation.
languageCode	string	Required within parent	The code representing the language of the subscription translation.
name	string	Required within parent	The name of the subscription translation.
subscriptionId	JSON	Required within parent
subscriptionId (anyOf 1)	integer	Alternative	The unique identifier for the subscription associated with the translation. Format: int64
subscriptionId (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
updatedAt	JSON	Required within parent
updatedAt (anyOf 1)	integer	Alternative	The timestamp indicating when the subscription translation was last updated. Format: int64
updatedAt (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Update a contact's subscription status — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
channel	string	Required within parent	The type of communication channel, with 'EMAIL' as the only supported option. One of: EMAIL
legalBasis	string	Optional	The legal basis for communication, with options including 'LEGITIMATE_INTEREST_PQL', 'LEGITIMATE_INTEREST_CLIENT', 'PERFORMANCE_OF_CONTRACT', 'CONSENT_WITH_NOTICE', 'NON_GDPR', 'PROCESS_AND_STORE', and 'LEGITIMATE_INTEREST_OTHER'. One of: CONSENT_WITH_NOTICE, LEGITIMATE_INTEREST_CLIENT, LEGITIMATE_INTEREST_OTHER, LEGITIMATE_INTEREST_PQL, NON_GDPR, PERFORMANCE_OF_CONTRACT, PROCESS_AND_STORE
legalBasisExplanation	string	Optional	An explanation for the legal basis used for communication.
statusState	string	Required within parent	The current subscription status of the contact, which can be 'SUBSCRIBED', 'UNSUBSCRIBED', or 'NOT_SPECIFIED'. One of: NOT_SPECIFIED, SUBSCRIBED, UNSUBSCRIBED
subscriptionId	integer	Required within parent	The unique identifier of the subscription to be updated. Format: int64

Update a contact's subscription status — response body

Field	Type	Presence	Description and constraints
$	object	Root
completedAt	string	Required within parent	The date and time when the operation was completed. Format: date-time
errors	array	Optional	A list of errors that occurred during the operation.
errors[]	Model	Each item	Expand Batch update subscription status — response body — errors item
links	object	Optional	Contains URLs related to the response, such as documentation or resources. Additional keys: see wildcard field
links.*	string	Additional keys
numErrors	JSON	Optional
numErrors (anyOf 1)	integer	Alternative	The number of errors that occurred during the operation. Format: int32
numErrors (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
requestedAt	string	Optional	The date and time when the request was made. Format: date-time
results	array	Required within parent	An array of results from the operation.
results[]	Model	Each item	Expand Batch update subscription status — response body — results item
startedAt	string	Required within parent	The date and time when the operation started. Format: date-time
status	string	Required within parent	Indicates the current status of the operation, with possible values: PENDING, PROCESSING, CANCELED, COMPLETE. Known values: CANCELED, COMPLETE, PENDING, PROCESSING

Referenced models: Batch update subscription status — response body — errors item, Batch update subscription status — response body — results item