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
- XML
{
"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>
<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
- XML
{
"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>
<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.