Get Users’ Subscription Group Status
/subscription/status/get
Use the endpoints below to get the subscription state of a user in a subscription group. These groups will be available on the Subscription Group page. The response from this endpoint will include the external ID and either subscribed, unsubscribed, or unknown for the specific subscription group requested in the API call. This can be used to update the subscription group state in subsequent API calls or to be displayed on a hosted web page.
If you want to see examples or test this endpoint for Email Subscription Groups:
If you want to see examples or test this endpoint for SMS Subscription Groups:
Looking for the api_key
parameter?
As of May 2020, Braze has changed how we read API keys to be more secure. Now API keys must be passed as a request header, please see YOUR_REST_API_KEY
within the Example Request below.
Braze will continue to support the api_key
being passed through the request body and URL parameters, but will eventually be sunset. Please update your API calls accordingly.
Request Parameters
Parameter | Required | Data Type | Description |
---|---|---|---|
subscription_group_id |
Yes | String | The id of your subscription group. |
external_id |
Yes* | String | The external_id of the user (must include at least one and at most 50 external_ids ). When both an external_id and email/phone are submitted, only the external_id(s) provided will be applied to the result query. |
email |
Yes* | String | The email address of the user. It can be passed as an array of string with a max of 50. Submitting both an email address and phone number (with no external_id) will result in an error |
phone |
No* | String | The phone number of the user. You must include at least one phone number (if email is not included) and at most 50 phone numbers. The recommendation is to provide this in the E.164 format . Submitting both an email address and phone number (with no external_id) will result in an error |
- One of
external_id
oremail
orphone
is required for each user. - For SMS subscription groups, either
external_id
orphone
is required. When both are submitted, only the external_id is used for querying and the phone number is applied to that user. - For EMAIL subscription groups, either
external_id
oremail
is required. When both are submitted, only the external_id is used for the query and the email address is applied to that user. - Your request must include
phone
oremail
value, but not both
Example Request
1
https://rest.iad-03.braze.com/subscription/status/get?subscription_group_id=1f3-33203-3dd3-d323d3&external_id=12345&email=example.email@braze.com&phone=+11112223333
Example Request for multiple users
1
https://rest.iad-03.braze.com/subscription/status/get?subscription_group_id=1f3-33203-3dd3-d323d3&external_id[]=1&external_id[]=2
Example Request for SMS
1
2
curl --location --request GET 'https://rest.iad-01.braze.com/subscription/status/get?subscription_group_id=1f3-33203-3dd3-d323d3&external_id=12345&email=example.email@braze.com&phone=+11112223333' \
--header 'Authorization: Bearer YOUR_REST_API_KEY'
Example Request for Email
1
2
curl --location --request GET 'https://rest.iad-01.braze.com/subscription/status/get?subscription_group_id=1f3-33203-3dd3-d323d3&external_id=1234&email=example.email@braze.com' \
--header 'Authorization: Bearer YOUR_REST_API_KEY'
Response
All successful responses will return subscribed
, unsubscribed
, or unknown
depending on status and user history with the subscription group.
1
2
3
4
5
6
7
8
9
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY
{
"status": {
"1": "Unsubscribed",
"2": "Subscribed"
},
"message": "success"
}