You can also use this API endpoint to update subscription details: /lookup/subscriptions?{queryParams}
This API allows updating (opt-in or opt-out) subscription status of transactional and bulk messaging services for a customer.
- Transaction Messages: These are personalized messages sent to a customer instantly. For example, a new transaction details, points or coupon redeemed, send birthday or anniversary wishes and so on.
- Bulk Messages: These are promotion messages sent to a list of customers. For example, through campaigns.
NoteMake sure communication channels like Mobile and Email are configured in InTouch for subscription.

API Endpoint example
https://eu.api.capillarytech.com/v2/customers/565039505/subscriptions?format=json
curl --location --globoff 'https://eu.api.capillarytech.com/v2/customers/{userId}/subscriptions?format=json' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Basic cnV0dWphX2NhcGlsbGFyeTpkMTNlMmEyYmY4OWRkNDAxN2U0Y2EwOTk1MGI0NzZjNg==' \
--header 'Cookie: _cfuvid=rxRpkG0ZaHhqCspOGoNMJ1Zw3B.833ToyoOw1GvD6HU-1750747343765-0.0.1.1-604800000' \
--data '
{
"communicationId": -1,
"campaignId": -1,
"reason": "This is V2 subscription api",
"scope": {
"scope": "USER",
"subScope": "NONE"
},
"subscriptions": [
{
"channel": "EMAIL",
"priority": "BULK",
"type": "OPTOUT",
"orgUnitId": 200031782,
"sourceName": "FACEBOOK",
"accountId": "01"
},
{
"channel": "MOBILE",
"accountId": "01",
"priority": "BULK",
"type": "OPTIN",
"orgUnitId": 200031782,
"sourceName": "FACEBOOK"
},
{
"channel": "EMAIL",
"accountId": "01",
"priority": "TRANS",
"type": "OPTIN",
"orgUnitId": 200031782,
"sourceName": "FACEBOOK"
},
{
"channel": "MOBILE",
"accountId": "01",
"priority": "TRANS",
"type": "OPTOUT",
"orgUnitId": 200031782,
"sourceName": "FACEBOOK"
}
]
}
'
Request Body Parameters
Parameter (Parameters marked with * are mandatory) | Datatype | Description |
---|---|---|
communicationId | long | Communication ID. Pass |
campaignId | long | Campaign ID. Pass |
reason | string | Reason for updating the subscription. |
scope | object | Scope details for the subscription update. |
| string | Main scope of the subscription. Example: |
| string | Sub-scope of the subscription. Example: |
subscriptions* | array | List of subscription objects defining detailed preferences. At least one object is required. |
| enum | Communication channel. Values: |
| string | Account identifier for the given channel. |
| enum | Type of message. |
| enum | Subscription type. |
| long | Org unit or concept ID where the subscription should be updated. |
| enum | Source in which the identifier is registered. Values: |
Response Parameter
Parameter | Type | Description |
---|---|---|
scope.scope | String | The scope of the subscription (e.g., "USER"). |
scope.subScope | String | The sub-scope of the subscription (e.g., "NONE"). |
subscriptions | Array of Objects | A list of subscription objects. |
campaignId | Integer | The ID of the campaign associated with the subscription. |
communicationId | Integer | The ID of the communication associated with the subscription. |
reason | String | A description or reason for the response. |
warnings | Array | A list of warnings, if any. |
Subscription Object Details:
Each object in the subscriptions
array has the following parameters:
Parameter | Type | Description |
---|---|---|
channel | String | The communication channel (e.g., "EMAIL", "MOBILE"). |
accountId | String | The account ID associated with the subscription. |
priority | String | The priority level of the subscription (e.g., "BULK", "TRANS"). |
type | String | The subscription type (e.g., "OPTOUT", "OPTIN"). |
orgUnitId | Integer | The organizational unit ID associated with the subscription. |
sourceName | String | The source of the subscription (e.g., "FACEBOOK"). |
Note: An update to the subscription status of a customer doesn’t generate or trigger event notifications.
{
"scope": {
"scope": "USER",
"subScope": "NONE"
},
"subscriptions": [
{
"channel": "EMAIL",
"accountId": "01",
"priority": "BULK",
"type": "OPTOUT",
"orgUnitId": 200031782,
"sourceName": "FACEBOOK"
},
{
"channel": "MOBILE",
"accountId": "01",
"priority": "BULK",
"type": "OPTIN",
"orgUnitId": 200031782,
"sourceName": "FACEBOOK"
},
{
"channel": "EMAIL",
"accountId": "01",
"priority": "TRANS",
"type": "OPTIN",
"orgUnitId": 200031782,
"sourceName": "FACEBOOK"
},
{
"channel": "MOBILE",
"accountId": "01",
"priority": "TRANS",
"type": "OPTOUT",
"orgUnitId": 200031782,
"sourceName": "FACEBOOK"
}
],
"campaignId": -1,
"communicationId": -1,
"reason": "This is V2 subscription api",
"warnings": []
}
API specific error code
Error code | Description | Reason |
---|---|---|
1012 | Cannot find customer for provided mobile/external-id/e-mail/id | Mobile/Email id/External-id invalid |
1000 | Customer Subscriptions could not be added | Invalid customer details or missing data |
400 | Bad Request | The request is malformed or missing required parameters (e.g., invalid format). |
401 | Unauthorized | Authentication failed or the user lacks valid credentials. |
500 | Internal Server Error | An unexpected server error occurred. |