Subscription API

The Subscription API stores all information and metadata about each time a person has subscribed to a subscription list. Using this API, you can manage subscription status, see all subscription events for a specific user, and retrieve a user’s subscription status for a specified list.

Please note that you cannot manually subscribe a user to a list using this API. To ensure compliance with federal laws, new subscriptions must be added/created using an acquisition campaign. See our Acquisition Campaign API for more information.

Person Record vs. Subscription Record – What’s the difference?

Though they might seem similar, it’s important to know the difference between person records and subscription records. A person record is unique for each end user and contains information that is unique to that person, such as their first name and zip code. A subscription record, however, is only unique to each time a person subscribes to a list. For example, one person record may have multiple subscription records if they are subscribed to multiple lists. Additionally, if one person unsubscribes and resubscribes to a list, there will be two subscription records created.

Available API Methods

Available Callbacks

Elements & Attributes

Data ElementTypeDescription
personObjectAn object containing person reference information for the subscriber.
subscription_listObjectAn object contained the reference information for the subscription list being subscribed to.
opt_in_dateTimestampTime reference of when the Subscription was entered. It should be in the ISO 8601 format - for example: 2017-01-15T15:34Z.
opt_out_dateTimestampTime reference of when the Subscription was ended. It should be in the ISO 8601 format - for example: 2017-01-15T15:34Z.
opt_out_reasonStringThe reason why the person was opted-out. The reason will be one of: “user_opt_out”, “disconnect”, “list_archived”, “bulk_opt_out”, “failed_at_carrier”, “obsolete_carrier”, “platform_opt_out”, “keyword_opt_out”, “api_opt_out”, “button_opt_out”.
urlStringA reference URL to the existing object, as a relative URL to the existing domain.

Example Entity

The following shows the JSON representation of a subscription entity within the APIs.