Skip to main content
Version: v72

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


ParametersTypeExampleDescription
"channel"string"email"Channel type
("email" / "sms" / "push" / "notify" / "viber" / "whatsapp" / "telegram_bot")
"db_id"int1Database 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"int1Subscription 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"int1Resource 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

{
"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
}

Object example

{
"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"
}
}
]
}

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 valueDescriptionNumber value
subscribedReady for messaging0
unsubscribedUnsubscribed1
complainedReported spam2
hardbouncedHard bounce, email probably invalid3
unconfirmedSubscription unconfirmed4
suspendedTemporarily unsubscribed5
invalidInvalid for a variety of reasons6

*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.