Subscription object

Description

The subscription object contains data about a profile's subscription to communication channels. The structure of the object varies depending on the channel type and API context

Basic Structure

Parameters	Type	Example	Description
"channel"	string	"email"	Channel type ("email" / "sms" / "push" / "notify" / "viber" / "whatsapp" / "telegram_bot")
"db_id"	int	1	Database identifier
"email"	string	"john@example.com"	Email address
"phone"	string	"+79000000000"	Phone number (For SMS subscriptions)
"provider"	string	"Firefox"	Provider type (For Push subscriptions)
"subscription_id"	string	"abcdefghijklmnqrstuvwxyz"	Subscription identifier (For Push subscriptions)
"cc_data"	object	{   "id": 1 }	Chat ID in Telegram bot
		{   "phone": "+79000000000" }	Profile phone in WhatsApp*/ Viber™ / Notify
"priority"	int	1	Subscription priority (optional field). If the subscription priority is passed in the request, the "Increase priority for new subscriptions" option in the resource will not work.
"profile_id"	string	"54759eb3c090d83494e2d804"	Profile identifier
"resource_id"	int	1	Resource identifier
"custom_fields"	object	"subscribed"	Standard and additional subscription fields (optional field). You can get information about available subscription fields in the resource via the /v1.1/resources/fields_get method
"status"	string	"subscribed"	Subscription status Learn more
"cats"	array	[ "category_1", "category_2" ]	Resource categories to which the profile is subscribed (optional field).

Extended structure when querying the profile through the handler /api/v1.1/profiles/get/

When querying the profile through the /api/v1.1/profiles/get/ handler, the subscription object contains additional metadata:

• Channel data is stored in separate objects:

  • "email_data" - for Email subscriptions
  • "phone_data" - for SMS/Viber/WhatsApp
  • "cc_data" - for Telegram

• Technical fields

  • "hash_id" - unique subscription hash
  • "is_delete" - delete flag (soft delete)

• History:

  • "reg_info" - subscription registration date

Example structure

JSON

{
  "resource_id": 4,
  "channel": "email",
  "email_data": {
        "email": "user@example.com",
        "domain": "example.com",
        "md5": "d922b1da12193df553aad2bee61da46b"
  },
  "status": "subscribed",
  "reg_info": {
    "date": "2025-07-23T11:27:05.487Z"
  },
  "hash_id": "7641c5c5",
  "is_delete": false
}

XML

<xml>
<subscription>
    <resource_id>4</resource_id>
    <channel>email</channel>
    <email_data>
        <email>user@example.com</email>
        <domain>example.com</domain>
        <md5>d922b1da12193df553aad2bee61da46b</md5>
    </email_data>
    <status>subscribed</status>
    <reg_info>
        <date>2025-07-23T11:27:05.487Z</date>
    </reg_info>
    <hash_id>7641c5c5</hash_id>
    <is_delete>false</is_delete>
</subscription>
</xml>

Object example

JSON

{
  "subscriptions": [
    {
      "resource_id": 1,
      "channel": "email",
      "email": "example@example.com"
    },
    {
      "resource_id": 2,
      "channel": "sms",
      "phone": "+79000000000"
    },
    {
      "resource_id": 1,
      "channel": "push",
      "subscription_id": "a81c264a938b475",
      "provider": "android-firebase",
      "custom_fields": {
        "_browser_name": "Firefox",
        "_device_type": "web",
        "custom_field_1": "test value"
      },
      "cats": [
        "category_1",
        "category_2"
      ]
    },
    {
      "resource_id": 1,
      "channel": "whatsapp",
      "cc_data": {
        "phone": "+79000000000"
      }
    },
    {
      "resource_id": 1,
      "channel": "viber",
      "cc_data": {
        "phone": "+79000000000"
      }
    },
    {
      "resource_id": 1,
      "channel": "telegram_bot",
      "cc_data": {
        "id": 12345
      }
    },
    {
      "resource_id": 1,
      "channel": "notify",
      "cc_data": {
        "phone": "+79000000000"
      }
    }
  ]
}

XML

<xml>
<subscriptions>
  <subscription>
    <resource_id>1</resource_id>
    <channel>email</channel>
    <email>example@example.com</email>
  </subscription>
  
  <subscription>
    <resource_id>2</resource_id>
    <channel>sms</channel>
    <phone>+79000000000</phone>
  </subscription>
  
  <subscription>
    <resource_id>1</resource_id>
    <channel>push</channel>
    <subscription_id>a81c264a938b475</subscription_id>
    <provider>android-firebase</provider>
    <custom_fields>
      <_browser_name>Firefox</_browser_name>
      <_device_type>web</_device_type>
      <custom_field_1>test value</custom_field_1>
    </custom_fields>
    <cats>
      <category>category_1</category>
      <category>category_2</category>
    </cats>
  </subscription>
  
  <subscription>
    <resource_id>1</resource_id>
    <channel>whatsapp</channel>
    <cc_data>
      <phone>+79000000000</phone>
    </cc_data>
  </subscription>
  
  <subscription>
    <resource_id>1</resource_id>
    <channel>viber</channel>
    <cc_data>
      <phone>+79000000000</phone>
    </cc_data>
  </subscription>
  
  <subscription>
    <resource_id>1</resource_id>
    <channel>telegram_bot</channel>
    <cc_data>
      <id>12345</id>
    </cc_data>
  </subscription>
  
  <subscription>
    <resource_id>1</resource_id>
    <channel>notify</channel>
    <cc_data>
      <phone>+79000000000</phone>
    </cc_data>
  </subscription>
</subscriptions>

Subscription status

Description

The status parameter in the subscription object overwrites the subscription status. It is recommended to pass it only when there is a need to update the status.

Both string and numeric status representations can be used.

Word value	Description	Number value
subscribed	Ready for messaging	0
unsubscribed	Unsubscribed	1
complained	Reported spam	2
hardbounced	Hard bounce, email probably invalid	3
unconfirmed	Subscription unconfirmed	4
suspended	Temporarily unsubscribed	5
invalid	Invalid for a variety of reasons	6

---

*Meta organization, which owns Instagram, Facebook, and WhatsApp products, is recognized as extremist and is banned in the Russian Federation.

** Viber™ is a trademark of Rakuten Group, Inc. Blocked in the Russian Federation.