API at a glance
Description: Retrieve all topics a customer has subscribed to using any customer identifier. Returns a list of topic names the customer is following for interest-based alerts.
Authentication & testing
Testing the API on this page
How to try it here
- Use your User API Key as the Username (leave Password blank).
- Select the appropriate API endpoint based on your Blueshift region.
- Enter the necessary parameters and click Try It to run the request.
Authentication using Base64 encoding
Note for developers
API requests require authentication using HTTP Basic Authentication with an API key.
The API key serves as the username, while the password field should be left empty.
The format to encode is: your_api_key: (note the trailing colon).
This string must be Base64-encoded and included in the request's Authorization header as follows:
Authorization: Basic encoded_valueYou can generate the encoded value using a trusted Base64 encoder.
Postman collection
Try it with Postman: Explore the API using Blueshift's Postman collection.
Things to know before you start
- Customer identification: You must provide at least one identifier:
email,uuid,customer_id,phone_number, ordevice_id.
Finding the customer UUID > >You can find the customer UUID in the URL when viewing a customer profile in the Blueshift app. For example, if you open a customer profile in the Blueshift app, its URL looks like
https://app.getblueshift.com/dashboard#/app/customer/<CUSTOMER_UUID>/show/overview.
- Multiple identifiers: If multiple identifiers are provided, the API uses them to find the customer (any matching identifier works).
- Empty response: Returns an empty topics array if the customer has no subscriptions or is not found.
- Phone number format: Must follow E.164 standard with country code (e.g.,
+14155553467).
Request parameters
Check out the request parameters
Query parameters
NoteYou must provide at least one identifier:
uuid,customer_id,phone_number, ordevice_id.
| Parameter | Type | Required | Description |
|---|---|---|---|
email | string | No* | Customer's email address. Example: [email protected] |
uuid | string | No* | Customer's unique identifier. Example: e909605f-3eb3-4e2a-a666-648dedae5b89 |
customer_id | string | No* | Customer ID from your system. Example: 812123 |
phone_number | string | No* | Customer's phone number in E.164 format (with country code, starts with +, 6-14 chars). Example: +14155553467 |
device_id | string | No* | Device UUID. Example: 8abe3faa-d48d-4e4a-00ca-beae01f1c987 |
*At least one identifier is required
Example requests & responses
Get subscriptions by email
GET /api/v1/interests/[email protected]{
"topics": [
"Politics",
"Sports",
"Technology"
]
}Get subscriptions by UUID
GET /api/v1/interests/user_subscriptions?uuid=e909605f-3eb3-4e2a-a666-648dedae5b89{
"topics": [
"Sports"
]
}No subscriptions
GET /api/v1/interests/[email protected]{
"topics": []
}Resource not found. Ensure that you are using the correct API endpoint. This can happen due to resource conflicts. Retry with exponential backoff. If the issue persists, contact Blueshift.
Unprocessable Entity - Some/all of the products have invalid data, please check the response for more information on.
Rate limit exceeded - Too many requests
Internal Server Error - Please contact blueshift for more information
Service unavailable, please retry - Bad Gateway, re-try with exponential backoff
Service unavailable, please retry - Service Unavailable, re-try with exponential backoff
Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff