Log inTry for free
Back to all APIs

Create subscription

This method will create a new subscription. You can provide an ID of an existing profile, or submit a full definition of a profile and security settings if you want to create new ones.

Please log in to see full path URL. Learn why.
post
/subscriptions/1/subscription/{channel}
Authorizations:
API Key Header
Basic
IBSSO Token Header
OAuth 2
Scopes:
subscriptions:manage
path Parameters
channel
required
string
Enum: "BLOCKLIST" "CUSTOMER_ENGAGEMENT" "EMAIL" "FACEBOOK" "KAKAO_ALIM" "KAKAO_CHINGU" "LINE" "MMS" "MOBILE_IDENTITY" "MOBILE_PUSH" "NUMBER_LOOKUP" "OPEN_CHANNEL" "RCS" "REGISTRATION" "SMS" "VIBER" "VOICE_VIDEO" "WHATSAPP" "ZALO"

Channel name. A separate subscription is needed for each channel.

Request Body schema:
application/json
collapse all -
One of
  • Blocklist
  • Customer Engagement
  • Email
  • Facebook
  • Kakao Alim
  • Kakao Chingu
  • Line
  • MMS
  • Mobile Identity
  • Mobile Push
  • Number Lookup
  • Open Channel
  • RCS
  • Registration
  • SMS
  • Viber
  • Voice and Video
  • Whatsapp
  • Zalo

Subscription group.

subscriptionId
required
string [ 1 .. 255 ] characters

Subscription ID. Used as part of a URL path and must not include any characters that require URL encoding. You cannot change the ID once a subscription is created.

name
string [ 1 .. 255 ] characters

A human-readable description for your subscription, can be changed at a later point.

events
required
Array of strings [ 0 .. 255 ] items
Items Enum: "BLOCK" "UNBLOCK"

List of events available for a subscription. Note that a set of events available for each channel is different; subscription to events that are unavailable for a certain channel will be ignored. For more details, see the availability table. In case you are configuring inbound Subscription please check all the details available here.

criteria
Array of objects [ 0 .. 255 ] items

Application and Entity pair to match. You can set the rule to match only Application or only Entity if necessary, omitting the other item.

Array
applicationId
string [ 0 .. 255 ] characters

CPaaS X property identifying an application, an use case or an environment on your system. Should only be set if you are using CPaaS X Applications with your traffic.

entityId
string [ 0 .. 255 ] characters

CPaaS X property identifying an unique actor on your system. Should only be set if you are using CPaaS X Applications with your traffic.

callsConfigurationId
string [ 0 .. 255 ] characters

CPaaS X calls configuration identifier. Should only be set if you are using CPaaS X Applications with your traffic.

resources
Array of strings [ 0 .. 255 ] items

List of resources to match. At the moment, this could only be a sender name (whether numeric or alpha) used on message submit.

users
Array of strings [ 0 .. 255 ] items

List of users to match. You can provide usernames from your account.

profile
required
object

Notification profile object holding the settings for your webhook URL and a reference to security settings. You can provide full definition of a notification profile and security settings if you want to create new items, or provide an ID of an existing profile to reuse it. If you want to reuse an existing profile, do not provide any other notification profile and security settings properties.

profileId
required
string [ 1 .. 255 ] characters

ID of a notification profile. This identifier will be used as part of a URL path and must not include any characters that require URL encoding. You cannot change the ID once an item is created.

webhook
object

Webhook configuration.

contentType
string [ 0 .. 255 ] characters
notifyUrl
required
string [ 0 .. 512 ] characters

Your webhook URL, where the notifications will be sent to.

security
object

Security settings object holding the authentication settings necessary to access your webhook. Should only be provided if you are creating a new profile and settings; otherwise it will be ignored.

authId
required
string [ 1 .. 255 ] characters

Unique security setting ID. Used as part of a URL path and must not include any characters that require URL encoding. You cannot change the ID once an item is created.

type
string
Enum: "BASIC" "HMAC" "OAUTH"

Credentials type.

credentials
BasicCredentials (object) or HmacCredentials (object) or OauthCredentials (object)

Webhook security credentials.

One of
  • BasicCredentials
  • HmacCredentials
  • OauthCredentials

Basic credentials.

username
required
string [ 1 .. 255 ] characters

Username.

password
required
string [ 1 .. 255 ] characters

Password.

clientCertificateId
string [ 0 .. 255 ] characters

Client certificate ID.

maxBucketSize
integer <int32> [ 1 .. 2000 ]

Specifies a maximum number of messages to be sent within a single request.

windowSize
integer <int32> [ 20 .. 10000 ]

A maximum number of concurrent connections (active requests) per client.

connectTimeout
integer <int32> [ 300 .. 30000 ]

Time in milliseconds sender system waits for connection acknowledgement until the connection is closed.

readTimeout
integer <int32> [ 1000 .. 90000 ]

A maximum period of inactivity in milliseconds between two consecutive data packets.

enabledSSLProtocols
Array of strings
Items Enum: "TLSv1.2" "TLSv1.3"

Specifies which security protocols should be used to send a HTTP request. Multiple options can be used.

headers
object

Set of key:value pairs that will be sent in a HTTP request as headers.Note: 'Authorization' header (if configured here for any reason) can be overridden with one from security config.

property name*
string

Set of key:value pairs that will be sent in a HTTP request as headers.Note: 'Authorization' header (if configured here for any reason) can be overridden with one from security config.

responseRegex
string

Response regex.

responseBodyRegex
string

Response body regex.

rateLimit
integer <int32> [ 1 .. 5000 ]

Limits the number of requests per second.

Responses

201

Created.

400

Bad request.

401

Unauthorized

403

Forbidden

404

Not found.

429

Too many requests.

500

Internal Server Error

Request samples

Content type
application/json
Copy
 Collapse all
{
  • "subscriptionId": "ABC-123-DEF",
  • "name": "Default group",
  • "events":
    [
    • "DELIVERY"
    ],
  • "criteria":
    [
    • {
      • "applicationId": "production",
      • "entityId": "entity1"
      },
    • {
      • "applicationId": "production",
      • "entityId": "entity2"
      },
    • {
      • "applicationId": "test",
      • "entityId": "entity1"
      }
    ],
  • "resources":
    [
    • "1234"
    ],
  • "users":
    [
    • "user1",
    • "user2"
    ],
  • "profile":
    {
    • "profileId": "NOTIF-32395",
    • "webhook":
      {},
    • "security":
      {
      • "authId": "NEWAUTH-9291",
      • "type": "BASIC",
      • "credentials":
        {
        • "username": "user1",
        • "password": "password1"
        }
      }
    }
}

Response samples

Content type
application/json
Copy
 Collapse all
{
  • "subscriptionId": "string",
  • "profile":
    {
    • "profileId": "string",
    • "security":
      {
      • "authId": "string"
      }
    }
}

Need assistance

Explore Infobip Tutorials

Encountering issues

Contact our support

What's new? Check out

Release Notes

Unsure about a term? See

Glossary

Research panel

Help shape the future of our products
Learn more
Service status

Copyright @ 2006-2025 Infobip ltd.

Privacy documentsTerms of use