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 Element	Type	Description
`person`	Object	An object containing person reference information for the subscriber.
`subscription_list`	Object	An object contained the reference information for the subscription list being subscribed to.
`opt_in_date`	Timestamp	Time reference of when the Subscription was entered. It should be in the ISO 8601 format - for example: 2017-01-15T15:34Z.
`opt_out_date`	Timestamp	Time reference of when the Subscription was ended. It should be in the ISO 8601 format - for example: 2017-01-15T15:34Z.
`opt_out_reason`	String	The 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”.
`url`	String	A 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.

{
   "person":{
      "id":"ABC123",
      "url":"/companies/:company_key/mobiledb/persons/:person_id"
   },
   "subscription_list":{
      "id":"1234",
      "url":"/companies/:company_key/mobiledb/subscription_lists/:id"
   },
   "opt_in_date":"2017-01-15T15:34Z",
   "url":"/companies/:company_key/mobiledb/persons/:person_id/subscriptions/:subscription_list_id"
}