openapi: 3.0.0 info: description: These APIs will help you manage different workflows in Blueshift. Our powerful REST APIs provide an easy way to integrate your data and third party applications with Blueshift. version: 1.0.0 title: Blueshift APIs contact: email: support@getblueshift.com servers: - url: https://api.getblueshift.com - url: https://api.eu.getblueshift.com tags: - name: Adapters description: Adapters are entities that provide integration to various services with Blueshift. For example, we provide adapters for various services such as Mailgun, Sendgrid, and Sparkpost for sending emails, and Infobip and Attentive adapters for SMSes. Similarly, we provide adapters for various channels and integrations. - name: Campaigns description: Manage your campaigns in Blueshift. - name: Catalog description: A catalog is a list of items which may include content or products. - name: Custom user lists description: A custom user list contains information about the users of your site such as name, email, phone number, and location. You can use this list as a segment and run campaigns for them. - name: Customer description: Blueshift hosts 360 degree customer profile for each of your users to represent all of their demographic, behavioral and engagement activity. - name: Customer groups description: Customer groups link multiple customer profiles to a common parent entity with shared attributes. Use these endpoints to delete a group or remove a user from a group. - name: Email template description: Email template lifecycle management - name: Email validation description: Validate single or bulk email addresses to assess deliverability and risk. - name: Event description: Use the event APIs to send events from your servers. - name: External fetch description: External fetch is a Blueshift capability that lets you include dynamic content from external servers that is fetched “just in time” before sending a message. - name: Interest alerts description: Interest alerts store information about users' interests. When an event occurs in an area or topic in which multiple users are interested, you can trigger a single API call to send a notification to all the users who are interested in that topic. - name: Live Activities - name: Live content description: Use the Live content API endpoint to insert content recommendations in your website and mobile apps. - name: Promotions description: Promotions allows you to manage promo codes that you may wish to send to your customers through Blueshift Campaigns - name: Push template description: Push template lifecycle management - name: SMS template description: SMS template lifecycle management - name: Search description: You can use the `customer_search` API to search for events associated with a customer. - name: Segments description: A segment is a list of users that satisfy a criteria. For example, you can create a segment for users who are located in the San Francisco area and run campaigns for them. - name: Shared assets description: Manage reusable assets such as HTML, rich text, subject lines, and visual editor content. - name: Subscription groups description: Retrieve subscription groups and view detailed information for each subscription group. - name: Tags description: Tags are folder-based entities that you can use to organize your resources. Each tag folder contains its own isolated set of tags. paths: /api/v1/account_adapters: get: tags: - Adapters summary: List adapters description: Use this endpoint to list all adapters in your Blueshift account. Adapters connect your account to third-party services (e.g., Mailgun for email, Infobip for SMS), and you may have multiple per channel. security: - user_api_auth: [] parameters: - name: channel_name description: 'Specify the channel type to filter adapters: • `Email` - Email service providers (e.g., Sendgrid, Mailgun) • `SMS` - SMS service providers (e.g., Twilio, 46elks) • `Push Message` - Push notification providers • `Webhook` - Webhook integrations • `InApp` - In-app message providers • `Segment Report` - Segment reporting integrations' required: true in: query schema: type: string enum: - Email - SMS - Push Message - Webhook - InApp - Segment Report example: SMS - name: adapter_name description: Filter results by adapter provider name (e.g., `sendgrid`, `sparkpost`, `46elks`, `twilio`). in: query schema: type: string example: 46elks responses: '200': description: OK content: application/json: schema: type: array items: type: object properties: id: type: integer description: The unique ID of the adapter. example: 8147 name: type: string description: The provider name of the adapter (e.g., Sendgrid, 46elks). example: 46elks primary_name: type: string description: The alias name of the adapter that you enter when you create it. example: test-1 uuid: type: string description: The unique UUID of the adapter. example: aafcf5a4-556f-4334-8cfc-4dfd2a61c691 from_name: type: string nullable: true description: The sender name for the adapter (applicable for Email channel). example: null from_address: type: string nullable: true description: The sender email address for the adapter (applicable for Email channel). example: null reply_to_address: type: string nullable: true description: The reply-to email address for the adapter (applicable for Email channel). example: null created_at: type: string format: date-time description: The date and time when the adapter was created. example: '2022-04-20T06:29:46.000Z' updated_at: type: string format: date-time description: The date and time when the adapter was last updated. example: '2022-04-20T06:29:46.000Z' is_active: type: boolean description: Indicates if the adapter is actively in use. example: false cname_record: type: string nullable: true description: The CNAME record pointing to the domain used for sending (applicable for Email channel). example: null bypass_suppression_list: type: boolean description: Indicates whether to bypass the suppression list when sending messages. example: false channel: type: string description: The channel type for this adapter (e.g., Sms, Email, Push). example: Sms '400': description: The request was invalid or cannot be otherwise served. An accompanying error message will explain further. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - No adapters found matching the criteria. content: application/json: schema: type: array items: {} maxItems: 0 example: [] '409': description: Conflict error, please retry. The request could not be completed due to a conflict with the current state of the target resource. Re-try with exponential backoff. '413': description: You can upload up to 50 users in an API call. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Rate limit exceeded. Too many requests. Contact us on support@blueshift.com for recommended throughput. '500': description: Internal server error. Contact Blueshift for more information. '502': description: Service unavailable, please retry. Bad gateway. Retry with exponential backoff. '503': description: Service unavailable, please retry. Service unavailable. Retry with exponential backoff. '504': description: Service unavailable, please retry. Gateway timeout. Retry with exponential backoff. /api/v1/bulkevents: post: summary: Send bulk events description: Use this endpoint to send multiple events from your server or use javascript events that call the API. tags: - Event security: - event_api_auth: [] requestBody: content: application/json: schema: type: object properties: events: type: array items: type: object additionalProperties: true required: - event properties: customer_id: type: string description: 'Specify the customer ID. You must atleast specify this value, or one or more of the following: event/device_id/email.' example: '48759893' event: type: string description: 'Specify the name of the event. For example, view (product view), add_to_cart, remove_from_cart, checkout, purchase, search, your_custom_event_name (custom event) etc. You must atleast specify this value, or one or more of the following: customer_id/device_id/email.' example: add_to_cart device_type: type: string description: Specify the type of the device. For example, ios or android. example: android device_tokens: type: string description: Specify the token of the device. example: 12d34a5ccf37db694d48d89740bbc1f94da08e25930fc773d2af2aefdd98989c9 device_id: type: string description: 'Specify the UUID of the device. You must atleast specify this value, or one or more of the following: event/customer_id/email.' example: 8abe3faa-d48d-4e4a-00ca-beae01f1c987 device_idfa: type: string description: Sepcify the advertising identifier (idfa) on the device. example: 39c20522-2ce9-4466-9876-7677b89e4d3b device_idfv: type: string description: Specify the identfier for vendor (idfv) on the device. example: 6d031ec8-e40c-47d4-9c99-b3e308d8ed78 device_manufacturer: type: string description: Specify the manufacturer of the device. example: apple os_name: type: string description: Specify the OS name. example: ios network_carrier: type: string description: Specify the carrier on the mobile device. example: verizon ip: type: string description: Specify the IP address of the device. example: 192.0.2.1 email: type: string description: 'Specify the user''s email address. You must atleast specify this value, or one or more of the following: event/device_id/customer_id.' example: janedoe@acme.com latitude: type: string description: Specify the latitude of the user's location. example: '212.99333' longitude: type: string description: Specify the longitude of the user's location. example: '-12.39334' subscription_groups: type: array description: Specify the user's subscription preferences. items: type: object properties: id: type: string description: The ID of the subscription group. subscribed: type: boolean description: Enter `true` if the user is subscribed, or `false` if unsubscribed. example: - id: newsletter subscribed: true - id: weekly_promo subscribed: false example: - customer_id: abc812122 event: identify device_type: ios device_tokens: '49244924492449244924492449244924492449244924' device_id: 8abe3faa-d48d-4e4a-00ca-beae01f1c987 device_idfa: 4d031ed8-c40e-57d4-9c99-a3e308d8cd78 device_idfv: 6d031ec8-e40c-47d4-9c99-b3e308d8ed78 device_manufacturer: apple os_name: ios network_carrier: verizon ip: 201.44.11.21 email: jane.doe@acme.com latitude: '212.99333' longitude: '-12.39334' subscription_groups: - id: newsletter subscribed: true - id: weekly_promo subscribed: false - customer_id: '812123' event: purchase ip: 201.44.11.22 email: jane.doe@acme.com revenue: '31.24' description: Specify device_id. The device_id is the mobile specific (iOS or Android) device identifier to uniquely identify the mobile device. responses: '200': description: OK content: application/json: schema: type: object properties: status: type: string description: ok or bad request example: ok count: type: integer description: The count of events sent example: 0 '400': description: Bad Request - The request was invalid or cannot be otherwise served. An accompanying error message will explain further. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: customer_id: type: string example: can't be blank '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '413': description: "You can upload maximum 100 products in one api call\t- The server is refusing\ \ to process a request because the request payload is larger than the server is willing or\ \ able to process." '422': description: Unprocessable Entity - Some/all of the products have invalid data, please check the response for more information on. '429': description: Rate limit exceeded - Too many requests '500': description: "Internal Server Error\t- Please contact blueshift for more information" '502': description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff '503': description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff '504': description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff /api/v1/campaigns.json: get: tags: - Campaigns summary: Performance summary description: Use this endpoint to export the performance data of all the campaigns for a given date range. security: - user_api_auth: [] parameters: - name: start_time description: Specify a timestamp in the ISO 8601 format to filter the performance data of the campaigns that ran after it. example: '2023-05-05T20:41:21.000Z' in: query required: true schema: type: string format: date-time - in: query name: end_time description: Specify a timestamp in the ISO 8601 format to filter the performance data of the campaigns that ran before it. example: '2023-10-06T20:41:21.000Z' required: true schema: type: string format: date-time - name: status description: Specify a status to filter the campaigns. example: launched in: query schema: type: string enum: - launched - draft - paused - completed - name: tag_data description: Specify tags to filter the campaigns. example: Regions:NA,EU,APAC,LATAM,GreaterChina in: query schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: campaigns: type: array items: type: object properties: campaign_executing: type: boolean example: false campaign_execution_ended_at: type: string format: date-time example: '2024-10-03T04:57:24.000Z' campaign_execution_started_at: type: string format: date-time example: '2023-10-05T04:57:24.000Z' created_at: type: string format: date-time example: '2023-10-03T04:57:24.000Z' currency: type: string example: USD enddate: type: string format: date example: '2024-05-03T04:57:24.000Z' exec_term: type: string enum: - on_going example: on_going name: type: string example: Daily market tips recurring_number: type: number example: '1' recurring_schedule: type: string example: continuously recurring_time: type: number description: Schedule a recurring campaign to execute sends at a specific time of a day. The system tracks the campaign's last execution time (`last_recurring_execution_started_at`) and uses it to determine the next scheduled run. example: '2024-01-03T14:45:00.000Z' recurring_unit: type: string example: day segment_name: type: string example: Daily market tips segment description: The segment for which the campaign is running segment_uuid: type: string example: 9dfd5cdc-fedc-40b5-8c65-ba533c57c8bf startdate: type: string format: date-time example: '2024-01-02T14:45:00.000Z' statistics: type: object properties: activations: type: number add_to_carts: type: number assigns: type: number attributions: type: object bounces: type: number checkouts: type: number clicks: type: number deliveries: type: number end_time: type: string format: date-time media_spent: type: number opens: type: number example: 20 pageloads: type: number example: 5 purchases: type: number example: 75 revenue: type: number example: 19618 sends: type: number example: 110 spam_reports: type: number example: 2 start_time: type: string format: date-time timezone: type: string example: Pacific/Los_Angeles unique_clicks: type: number example: 150 unique_opens: type: number example: 250 unsubscribes: type: number example: 2 visits: type: number example: 2160 status: type: string enum: - launched - draft - paused example: paused updated_at: type: string format: date-time example: '2024-05-05T20:41:21.000Z' uuid: type: string '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: message: type: string example: Bad Request '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout /api/v1/campaigns/bulk_archive: put: summary: Bulk archive campaigns description: Use this endpoint to archive multiple campaigns by providing an array of UUIDs. tags: - Campaigns security: - user_api_auth: [] requestBody: required: true content: application/json: schema: type: object properties: uuid: type: array items: type: string description: List of campaign UUIDs to archive. example: - uuid1 - uuid2 - uuid3 - uuid4 - uuid5 responses: '200': description: Campaigns archived successfully. content: application/json: schema: type: object properties: no_change: type: array items: type: string description: List of UUIDs for campaigns that were already archived. example: [] blocked: type: array items: type: string description: List of UUIDs for campaigns that could not be archived due to restrictions. example: [] successful: type: array items: type: object properties: uuid: type: string description: UUID of the successfully archived campaign. name: type: string description: Name of the successfully archived campaign. description: List of campaigns that were successfully archived. example: - uuid: 1a2b3c4d-5678-90ab-cdef-1234567890ab name: Holiday Season Campaign - uuid: 2b3c4d5e-6789-01bc-def0-2345678901cd name: Spring Sale Campaign - uuid: 3c4d5e6f-7890-12cd-ef01-3456789012de name: Summer Offers Campaign - uuid: 4d5e6f7g-8901-23de-f012-4567890123ef name: Autumn Clearance Sale - uuid: 5e6f7g8h-9012-34ef-0123-5678901234fg name: Winter Discounts Campaign failed: type: array items: type: string description: List of UUIDs for campaigns that could not be archived. example: [] '400': description: Bad request - Invalid parameters or request conditions. '401': description: Unauthorized - Invalid or missing API key. '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found - One or more campaigns not found. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout /api/v1/campaigns/bulk_execute: post: tags: - Campaigns summary: Bulk trigger campaigns description: Use this endpoint to trigger multiple campaigns. security: - user_api_auth: [] requestBody: content: application/json: schema: type: object properties: payloads: type: array items: type: object additionalProperties: true properties: email: description: Specify the email address of the user for whom you want to trigger the campaign. type: string example: john.doe@blueshift.com campaign_uuid: description: Specify the UUID of the campaign that needs to be triggered. You can copy the UUID from the URL of the campaign on the Blueshift app. For example, if you open a campaign in the Blueshift app, its URL looks like `https://app.getblueshift.com/dashboard#/app/campaigns//details`. type: string example: 857ad5a5-1cd1-4c8a-bd9b-b2cdbb6595cc email_attachments: type: array description: Specify the URLs of the files that you want to send as an attachment along with the email. example: - '{https://cdn.getblueshift.com/examples/sample.pdf}' - '{https://cdn.getblueshift.com/static/csv/test.csv}' items: type: string _bsft_high_priority: type: boolean description: Set to true if the campaign must be processed as a high priority campaign. Blueshift first processes all high priority campaigns in a first in first out order. This is followed by all other campaigns in a first in first out order. The default value is false. default: false example: false transaction_uuid: type: string description: Optionally include the transaction UUID (must be a well formed UUID) to avoid duplicate messages. The API returns a 200 status code for a duplicate request along with a message noting that a request with the given transaction UUID was already processed. example: a0d1a0f3-6596-4e1c-b487-3639e05b6d2f example: campaign_uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890 trigger_at: '2024-03-15T10:30:00Z' users: - customer_id: user123 email: user1@acme.com transaction_uuid: txn_001 _bsft_high_priority: true - customer_id: user456 email: user2@acme.com transaction_uuid: txn_002 _bsft_high_priority: false description: List of required parameters to trigger a campaign. responses: '200': description: OK content: application/json: schema: type: array items: type: object properties: success: type: boolean '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: message: type: string example: Bad Request '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout /api/v1/campaigns/bulk_unarchive: put: summary: Bulk unarchive campaigns description: Use this endpoint to unarchive multiple campaigns by providing an array of UUIDs. tags: - Campaigns security: - user_api_auth: [] requestBody: required: true content: application/json: schema: type: object properties: uuid: type: array items: type: string description: List of campaign UUIDs to unarchive. example: - uuid1 - uuid2 - uuid3 - uuid4 - uuid5 responses: '200': description: Campaigns unarchived successfully. content: application/json: schema: type: object properties: no_change: type: array items: type: string description: List of UUIDs for campaigns that were already unarchived. example: [] blocked: type: array items: type: string description: List of UUIDs for campaigns that could not be unarchived due to restrictions. example: [] successful: type: array items: type: object properties: uuid: type: string description: UUID of the successfully unarchived campaign. name: type: string description: Name of the successfully unarchived campaign. description: List of campaigns that were successfully unarchived. example: - uuid: 7e3a2d1e-df8a-4d9c-95f2-a12f4d2f8e19 name: Holiday Sale Campaign - uuid: c15f84be-a5d4-4a3c-8096-4c8de82b0df3 name: Back-to-School Promotion - uuid: f29d2345-4a6b-432d-a1de-5c3490f74f52 name: Summer Discounts Campaign - uuid: 1b5e9876-5c4d-476f-91a8-b43c9ad2e4d1 name: Winter Clearance Sale - uuid: e5d2a4f3-d5b4-44a6-803e-8d547c3cdb78 name: Black Friday Deals failed: type: array items: type: string description: List of UUIDs for campaigns that could not be unarchived. example: [] '400': description: Bad request - Invalid parameters or request conditions. '401': description: Unauthorized - Invalid or missing API key. '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found - One or more campaigns not found. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout /api/v1/campaigns/execute: post: tags: - Campaigns summary: Trigger a campaign description: Use this endpoint to trigger an event-triggered or API-triggered campaign for a specific user. security: - user_api_auth: [] requestBody: content: application/json: schema: type: object additionalProperties: true required: - email - campaign_uuid properties: email: description: Specify the email address of the user for whom you want to trigger the campaign. type: string example: janedoe@acme.com campaign_uuid: description: Specify the UUID of the campaign that you want to trigger. You can copy the UUID from the URL of the campaign on the Blueshift app. For example, if you open a campaign in the Blueshift app, its URL looks like `https://app.getblueshift.com/dashboard#/app/campaigns//details`. type: string example: a43b685d-65e3-5303-64d8-d4b4ab075b5f email_attachments: type: array description: Specify the URLs of the files that you want to send as an attachment along with the email. example: - https://cdn.getblueshift.com/examples/sample.pdf - https://cdn.getblueshift.com/static/csv/test.csv items: type: string _bsft_high_priority: description: Set to true if the campaign must be processed as a high priority campaign. Blueshift first processes all high priority campaigns in a first in first out order. This is followed by all other campaigns in a first in first out order. The default value is false. type: boolean default: false example: false transaction_uuid: description: Optionally include the transaction UUID (must be a well formed UUID) to avoid duplicate messages. The API returns a 200 status code for a duplicate request along with a message noting that a request with the given transaction UUID was already processed. type: string example: a0d1a0f3-6596-4e1c-b487-3639e05b6d2f description: Required parameters to trigger a campaign. responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean example: true '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Invalid request parameters '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The specified campaign was not found. Verify the campaign UUID. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: 'Unprocessable Entity - Request validation failed. Common reasons include: campaign is not event/API triggered (error_code: 101), campaign cannot be triggered through this endpoint (error_code: 102), or a valid user identifier is missing (error_code: 102).' content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: campaign is not event/API triggered error_code: type: integer example: 101 '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout /api/v1/campaigns/{campaign_type}: post: tags: - Campaigns summary: Create a campaign description: Use this endpoint to create a campaign and specify its attributes. security: - user_api_auth: [] parameters: - in: path required: true name: campaign_type description: Specify how the campaign is triggered. Choose an option from the list. schema: type: string enum: - event_triggered - one_time requestBody: content: application/json: schema: type: object required: - name - startdate properties: name: type: string description: The name of the campaign. example: Spring_Sale_2025_EMAIL author: type: string description: Email address of the campaign author. example: marketing_manager@company.com launch: type: boolean description: "Determines if the campaign should be launched immediately (`true`) or\ \ saved as a draft (`false`). \n\n**Default**: `true`." default: true example: true startdate: type: string format: date-time description: "Campaign start time in ISO 8601 format. \n\n**Default**: current time." example: '2025-03-15T12:00:00Z' enddate: type: string format: date-time description: "Campaign end time in ISO 8601 format. \n\n**Default**: Runs indefinitely.\ \ \n\n**Applicable only for event-triggered campaigns.**" example: '2025-04-15T12:00:00Z' segment_uuid: type: string description: "UUID of the segment associated with this campaign. \n\n**Required only\ \ for one-time campaigns.**" example: 89abc123-d456-789e-0123-45678f9a0123 triggering_event_name: type: string description: "The event that triggers this campaign. Must match an **Event Attribute**\ \ in the Events dashboard. \n\nIf left blank, the campaign is **API triggered** and\ \ can only be triggered via the **Campaign Execute API**. \n\n**Applicable only for\ \ event-triggered campaigns.**" example: user_signup_confirmation bypass_message_limits: type: boolean description: "Whether to bypass messaging limits. \n\n**Default**: `false`." default: false example: false bypass_global_inclusion_segment: type: boolean description: "Whether to send messages to users outside the global inclusion segment.\ \ \n\n**Default**: `false`." default: false example: false skip_incrementing_user_message_limits: type: boolean description: "Controls whether sent messages are excluded from the user’s message counts.\ \ \n\nWhen set to `true`, messages do not count towards the user’s message limits.\ \ \n\n**Default**: `false`." default: false example: false remove_unsubscribe_from_email_headers: type: boolean description: "Whether to exclude unsubscribe headers from emails. \n\n**Default**: `false`." default: false example: false send_summary_emails: type: string description: "Email address to receive the campaign execution summary. \n\n**Applicable\ \ only for one-time campaigns.**" example: campaign_summary@company.com send_to_unsubscribed: type: boolean description: "Whether to send messages to unsubscribed users. \n\n**Default**: `false`." default: false example: false journey_concurrency: type: string description: "Defines how often a user can enter the journey. \n\n**Options:** `once_per_lifetime`,\ \ `once_at_any_time`, `multiple`. \n\n**Default**: `multiple`." enum: - once_per_lifetime - once_at_any_time - multiple default: multiple example: multiple seed_list_uuids: type: array description: An array of seed list UUIDs for testing campaigns. example: - 123e4567-e89b-12d3-a456-426614174000 - 123e4567-e89b-12d3-a456-426614174001 - 123e4567-e89b-12d3-a456-426614174002 items: type: string tag_data: type: string description: "Tags associated with the campaign. \n\n**Format**: `folder_name: tag1,\ \ tag2, tag3`. \n\n**Example**: `Regions:USA,Canada|Products:Electronics,Apparel`." example: Regions:USA,Canada|Products:Electronics,Apparel triggers: type: array description: You can add only one trigger at a time. If you add multiple triggers, the endpoint returns an error. items: type: object properties: trigger_name: type: string description: Name of the trigger for reference. example: Welcome Email Trigger template_uuid: type: string description: UUID of the template linked to this trigger (email, push, SMS, etc.). example: 8da0744e-141d-4c9d-85d7-c89a54ac745a utm_source: type: string description: "UTM Source for tracking. \n\n**Default**: Set based on the account's\ \ backend configuration." example: blueshift utm_campaign: type: string description: "UTM Campaign name. \n\n**Default**: Set based on the account's backend\ \ configuration." example: spring_sale_2025 utm_medium: type: string description: "UTM Medium (e.g., email, push). \n\n**Default**: Set based on the\ \ account's backend configuration." example: email utm_content: type: string description: "Identifies specific content variations within the campaign. \n\n\ **Default**: Set based on the account's backend configuration." example: discount_offer_banner utm_term: type: string description: "UTM Term for keyword tracking. \n\n**Default**: Set based on the\ \ account's backend configuration." example: exclusive_deal account_adapter_uuid: type: string description: "UUID of the adapter for message sending. If left blank, the trigger\ \ uses the default adapter for the channel. \n\nNot applicable for cloud app\ \ triggers. \n\n**Leave blank if using `account_adapter_liquid_expression`**." example: c2102111-e660-47df-aa3e-678d71a93644 account_adapter_liquid_expression: type: string description: "Liquid expression to dynamically assign an adapter UUID. \n\n**Leave\ \ `account_adapter_uuid` blank when using this**." example: '{% case user.country %}{% when ''US'' %}c2102111-e660-47df-aa3e-678d71a93644{% else %}fallback_uuid{% endcase %}' from_name: type: string description: Sender's name for email campaigns. example: Blueshift Marketing from_address: type: string description: Sender's email address. It must match the adapter domain. example: marketing@blueshift.com reply_to_address: type: string description: Email address where replies are sent. example: support@blueshift.com custom_url_params: type: array description: Custom tracking parameters added to links. items: type: object properties: name: type: string description: Specify the name of the property. example: region value: type: string description: Specify the value of the property. example: North America description: Specifications for the campaign to be created. responses: '200': description: OK content: application/json: schema: type: object properties: campaign: type: object properties: uuid: type: string description: The unique ID of the created campaign. example: 21a5b6c7-8901-4d2e-9f3g-45678abcdef name: type: string description: The name of the created campaign. example: Spring Sale 2025 startdate: type: string format: date-time description: The date and time when the campaign starts in ISO 8601 format. example: '2025-03-01T09:00:00.000Z' enddate: type: string format: date-time description: The date and time when the campaign ends in ISO 8601 format. example: '2025-03-15T23:59:59.000Z' status: type: string description: The current status of the campaign. example: launched triggering_event_name: type: string description: Specify the event that triggers this campaign. example: cart_abandonment journey_concurrency: type: string description: The number of times a campaign runs for a user. example: once_at_any_time author: type: string description: The author of the campaign. example: John Doe tag_data: type: string description: Tags associated with the campaign. example: Region:US,EU,APAC '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. '404': description: Not Found - The specified campaign was not found. Verify the campaign UUID. '422': description: Unprocessable Entity - The campaign cannot be paused due to its current status (e.g., already completed or archived). One or more scheduling parameters may be invalid (if applicable). '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. '502': description: Bad Gateway - The server received an invalid response. Retry the request. '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. /api/v1/campaigns/{campaign_uuid}.json: get: summary: Detailed report without stats description: Use this endpoint to get a detailed report of a specific campaign that does not include campaign statistics. tags: - Campaigns security: - user_api_auth: [] parameters: - name: campaign_uuid description: Specify the UUID of the campaign for which you want a detailed report. You can copy the UUID from the URL of the campaign on dashboard. For example, if you open a campaign in the Blueshift app, its URL looks like `https://app.getblueshift.com/dashboard#/app/campaigns//details`. example: a43b685d-65e3-5303-64d8-d4b4ab075b5f in: path required: true schema: type: string responses: '200': description: OK '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: message: type: string example: Bad Request '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout /api/v1/campaigns/{campaign_uuid}/archive: put: summary: Archive a single campaign description: Use this endpoint to archive a specific campaign by its UUID. tags: - Campaigns security: - user_api_auth: [] parameters: - in: path name: campaign_uuid required: true description: Specify the UUID of the campaign to archive. schema: type: string responses: '200': description: Campaign archived successfully. content: application/json: schema: type: object properties: archived: type: boolean description: Indicates whether the campaign was successfully archived. example: true example: archived: true '400': description: Bad request - Invalid parameters or request conditions. '401': description: Unauthorized - Invalid or missing API key. '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found - The specified campaign UUID was not found. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout /api/v1/campaigns/{campaign_uuid}/detail.json: get: summary: Detailed report with stats description: Use this endpoint to get a detailed report of a specific campaign. tags: - Campaigns security: - user_api_auth: [] parameters: - name: campaign_uuid description: 'Specify the UUID of the campaign for which you want a detailed report. For example, if you open an campaign in the Blueshift app, its URL looks like: `https://app.getblueshift.com/dashboard#/app/campaigns//details`. You can copy the UUID from the URL of the campaign on dashboard.' example: a43b685d-65e3-5303-64d8-d4b4ab075b5f in: path required: true schema: type: string - name: end_time description: Specify a timestamp in the ISO 8601 format to filter the report of the campaign upto it. example: '2023-08-05T07:05:38.000Z' required: true in: query schema: type: string format: date-time - name: start_time description: Specify a timestamp in the ISO 8601 format to filter the report of the campaign after it. example: '2023-07-05T07:05:38.000Z' required: true in: query schema: type: string format: date-time responses: '200': description: OK '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: message: type: string example: Bad Request '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout /api/v1/campaigns/{campaign_uuid}/launch: patch: summary: Launch a campaign description: "Use this endpoint to immediately launch a campaign. \n\nCampaigns that are archived\ \ or already completed cannot be launched. The API returns validation errors similar to those\ \ shown on the campaign UI." tags: - Campaigns security: - user_api_auth: [] parameters: - in: path name: campaign_uuid required: true description: UUID of the campaign to be launched. schema: type: string requestBody: description: No request body is required to launch a campaign. content: {} responses: '200': description: Campaign launched successfully. content: application/json: schema: type: object properties: uuid: type: string description: Unique identifier for the launched campaign. example: 09d6d2b1-684b-41c7-80d5-7001ce2653ac status: type: string description: Status of the campaign after launch. example: launched updated_at: type: string format: date-time description: Timestamp when the campaign was launched. example: '2025-06-18T08:11:04.498Z' '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. '404': description: Not Found - The specified campaign was not found. Verify the campaign UUID. '422': description: Unprocessable Entity - The campaign cannot be paused due to its current status (e.g., already completed or archived). One or more scheduling parameters may be invalid (if applicable). '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. '502': description: Bad Gateway - The server received an invalid response. Retry the request. '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. /api/v1/campaigns/{campaign_uuid}/pause: patch: tags: - Campaigns summary: Pause a campaign description: Use this endpoint to pause a campaign that is currently running or scheduled. This action is not applicable to campaigns that are completed or archived. security: - user_api_auth: [] parameters: - in: path required: true name: campaign_uuid description: UUID of the campaign to pause. schema: type: string requestBody: description: No additional parameters are required in the request body. content: {} responses: '200': description: OK content: application/json: schema: type: object properties: uuid: type: string description: The unique ID of the paused campaign. example: e3cd9c06-aaad-4102-84e7-03d708890695 status: type: string description: The current status of the campaign. example: paused updated_at: type: string format: date-time description: The timestamp when the campaign was paused. example: '2025-07-20T11:08:27.981Z' '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. '404': description: Not Found - The specified campaign was not found. Verify the campaign UUID. '422': description: Unprocessable Entity - The campaign cannot be paused due to its current status (e.g., already completed or archived). One or more scheduling parameters may be invalid (if applicable). '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. '502': description: Bad Gateway - The server received an invalid response. Retry the request. '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. /api/v1/campaigns/{campaign_uuid}/unarchive: put: summary: Unarchive a single campaign description: Use this endpoint to unarchive a specific campaign by its UUID. tags: - Campaigns security: - user_api_auth: [] parameters: - in: path name: campaign_uuid required: true description: Specify the UUID of the campaign to unarchive. schema: type: string responses: '200': description: Campaign unarchived successfully. content: application/json: schema: type: object properties: archived: type: boolean description: Indicates whether the campaign is archived. `false` means the campaign is unarchived. example: false example: archived: false '400': description: Bad request - Invalid parameters or request conditions. '401': description: Unauthorized - Invalid or missing API key. '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found - The specified campaign UUID was not found. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout /api/v1/campaigns/{campaign_uuid}/update_schedule: patch: summary: Update campaign schedule description: Use this endpoint to update the schedule of an existing campaign. tags: - Campaigns security: - user_api_auth: [] parameters: - in: path name: campaign_uuid required: true description: Specify the UUID of the campaign to update. schema: type: string requestBody: description: Specify the schedule details for the campaign. content: application/json: schema: type: object required: - startdate properties: startdate: type: string format: date-time description: 'Specify the campaign start time in ISO 8601 format. Default: current time (the campaign is launched immediately).' example: '2024-11-01T14:02:36.000Z' enddate: type: string format: date-time description: 'Specify the campaign end time in ISO 8601 format. Default: null (the campaign runs forever).' example: '2024-11-15T14:02:36.000Z' recurring_schedule: type: string description: 'Applicable to segment-triggered campaigns. Options: daily, continuously.' example: daily repeating_schedule_attributes: type: object description: For recurring campaigns. Contains recurrence config. properties: interval_size: type: integer description: Interval size for recurrence. example: 1 interval_unit: type: string description: 'Unit for the interval. Options: day, week, month.' example: day day_of_month: type: string description: 'Monthly recurrence type. Options: nth_day, nth_weekday, last_day.' example: nth_day days_of_week: type: array items: type: string description: Array of weekdays for recurrence. e.g. ["mon", "wed"]. example: - mon - wed responses: '200': description: The schedule has been successfully updated. content: application/json: schema: type: object properties: success: type: boolean example: true '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. '404': description: Not Found - The specified campaign was not found. Verify the campaign UUID. '422': description: Unprocessable Entity - The campaign cannot be paused due to its current status (e.g., already completed or archived). One or more scheduling parameters may be invalid (if applicable). '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. '502': description: Bad Gateway - The server received an invalid response. Retry the request. '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. /api/v1/catalogs: get: summary: Get list of catalogs description: Use this endpoint to get a list of all catalogs. tags: - Catalog security: - user_api_auth: [] responses: '200': description: OK content: application/json: schema: type: object properties: catalogs: type: array items: type: object properties: uuid: type: string description: The catalog's UUID. example: dd0d2987-9e57-47d4-9380-8a3e959cbe8e name: type: string description: The name of the catalog. example: Books catalog_type: type: string description: The type of the catalog. example: ecommerce upload_method: type: string description: The method that you use to upload the catalog to our platform. example: file url: type: string description: The URL of the catalog on your site. example: https://www.example.com/catalog/books update_frequency: type: string description: The frequency at which our platform receives data from your service to update the catalog. example: daily product_price_column_name: type: string description: The name of the column in the database that lists the products' prices. example: price product_name_column_name: type: string description: The name of the column in the database that lists the products' names. example: title product_id_column_name: type: string description: The name of the column in the database that lists the products' IDs. example: sku product_image_column_name: type: string description: The name of the column in the database that lists the URLs of the products' images. example: image_url product_msrp_column_name: type: string description: The name of the column in the database that lists the products' maximum selling price. example: msrp product_url_column_name: type: string description: The name of the column in the database that lists the products' URLs. example: product_url last_processed: type: string format: date-time description: The timestamp when the catalog was last updated in ISO 8601 format. example: '2024-10-03T04:58:34.000Z' catalog_headers: type: array example: '"title", "price", "image_url", "author", "isbn", "on_sale_date", "url", "sku", "itemformat", "language", "saleStatus", "consumerImprint", "formatFamily", "pages", "subject"' items: type: string status: type: string example: success product_count: type: integer description: The number of items in the catalog. example: 9882 product_category_column_name: type: array example: '"subject"' items: type: string file_settings: type: array items: type: string example: '' category_options: type: array items: type: string example: '' product_tag_column_name: type: array items: type: string example: tags tag_options: type: string example: '' product_brand_column_name: type: string description: The name of the column in the database that lists the product brand. example: author is_passive: type: boolean description: Indicates the availability of the product. example: true is_active: type: boolean description: Indicates the availability of the product. example: true product_start_date_column_name: type: string description: The name of the column in the database that indicates the start date on which a product will be available. example: on_sale_date product_end_date_column_name: type: string description: The name of the column in the database that indicates the last date on which a product will be available. example: on_sale_end_date parent_sku_column_name: type: string description: The name of the column in the database that lists the parent sku that ties all variants or child products together. example: parent_sku product_inventory_column_name: type: string description: The name of the column in the database that lists the product inventory. default_root_category: type: string description: The default root category for the catalog. start_at: type: string format: date-time description: The date and time at which the catalog becomes available. end_at: type: string format: date-time description: The date and time at which the catalog in no longer available. archived: type: boolean description: Indicates if the catalog is archived. example: false author: type: string description: The user who created the catalog. example: John Doe access_key: type: string description: The access key used to create the catalog. example: your_secure_access_key_here file_options: type: object properties: format: type: string description: The format of the catalog file. example: csv col_sep: type: string description: The separator used in the csv file. example: '|' encoding: type: string description: The encoding for the csv file. example: utf-8 error_access_key: type: string description: The access key for errors. catalog_file_name: type: string description: The filename of the uploaded catalog file. example: products.csv login: type: string description: The user login for the catalog. password: type: string description: The password for the catalog. host: type: string path: type: string port: type: string s3_access_key: type: string description: The access key for the S3 bucket from which the catalog is uploaded. example: ABCDEFPLOI7NY4NP5KON secret_access_key: type: string description: The secret access key for the S3 bucket from which the catalog is uploaded. bucket: type: string description: The name of the S3 bucket from which the catalog is uploaded. s3_path: type: string description: The path for the S3 bucket from which the catalog is uploaded. s3_aws_region: type: string description: The region for the S3 bucket from which the catalog is uploaded. example: us-west-2 sftp_login: type: string description: The region for the S3 bucket from which the catalog is uploaded. sftp_password: type: string description: The sftp password for the location from which the catalog is uploaded. sftp_port: type: string description: The sftp port for the location from which the catalog is uploaded. sftp_path: type: string description: The sftp folder path for the location from which the catalog is uploaded. sftp_host: type: string description: The sftp host for the location from which the catalog is uploaded. last_catalog_file: type: object description: Last catalog upload details for recurring catalog uploads. properties: id: type: string description: The ID for the file last uploaded for the catalog. example: '332983' uuid: type: string description: The catalog's UUID. example: 7fbea614-c257-4745-a1cb-22f6d7b87f74 catalog_id: type: string description: The catalog ID. example: '2151' file_name: type: string description: The file name of the file last uploaded for the catalog. example: products.csv total_records: type: string description: Total number of records in uploaded file. example: '9882' processed_records: type: string description: Total number of records processed. example: '9882' errored_records: type: string description: Number of records that resulted in an error. example: '0' status: type: string description: The status of the file upload. example: success created_at: type: string format: date-time description: The date and time for the upload. example: '2018-10-03T04:57:24.000Z' updated_at: type: string format: date-time description: The date and time for the upload. example: '2018-10-03T04:58:34.000Z' s3_key: type: string description: The access key ID to access your S3 folder. example: your_secure_access_key_here error_file_s3_key: type: string '400': description: Bad request - The request was invalid or cannot be otherwise served. An accompanying error message will explain further. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found - Can happen due to resource conflicts. Re-try with exponential backoff. Contact us on support@blueshift.com if the issue persists. '409': description: Conflict error, please retry - The request could not be completed due to a conflict with the current state of the target resource, re-try with exponential backoff. '413': description: "You can upload maximum 50 users in one api call\t- The server is refusing to process\ \ a request because the request payload is larger than the server is willing or able to process." '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: "Rate limit exceeded\t- Too many requests. Contact us on support@blueshift.com\ \ for recommended throughput." '500': description: "Internal Server Error\t- Please contact blueshift for more information." '502': description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff. '503': description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff. '504': description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff. post: summary: Create a catalog description: Create a catalog in Blueshift. tags: - Catalog security: - user_api_auth: [] requestBody: content: application/json: schema: type: object properties: catalog: type: object properties: name: type: string description: Specify a name for the catalog that you want to create. Ensure that the value that provide in this field is unique. example: Winter Collection responses: '200': description: OK content: application/json: schema: type: object properties: catalog_uuid: type: string description: The UUID of the catalog that got created. example: 0215377e-71c2-4a4f-8ec2-3a7d04ad0461 '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: message: type: string example: Bad Request '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout /api/v1/catalogs/{catalog_uuid}.json: get: summary: Get catalog details description: Use this endpoint to get the details of one catalog at a time. tags: - Catalog security: - user_api_auth: [] parameters: - in: path required: true name: catalog_uuid description: Specify the UUID of the catalog. You can get the catalog's UUID from its URL. For example, if you open a catalog on the Blueshift app, its URL looks like `https://app.getblueshift.com/dashboard#/app/catalogs//details`. schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: uuid: type: string description: The catalog's UUID. example: 1234asdfjh-asdfjh123425-asdjk1234 name: type: string description: The name of the catalog. catalog_type: type: string description: The type of the catalog for example, `e-commerce`. url: type: string description: The URL of the catalog on your site. upload_method: type: string description: The method that you use to upload the catalog to our platform. For example, `api`, `file`. example: api update_frequency: type: integer description: The frequency at which our platform receives data from your service to update the catalog. product_price_column_name: type: string description: The name of the column in the database that lists the products' prices. product_name_column_name: type: string description: The name of the column in the database that lists the products' names. product_id_column_name: type: string description: The name of the column in the database that lists the products' IDs. product_image_column_name: type: string description: The name of the column in the database that lists the URLs of the products' images. product_msrp_column_name: type: string description: The name of the column in the database that lists the products' maximum selling price. product_url_column_name: type: string description: The name of the column in the database that lists the products' URLs. last_processed: type: string format: date-time description: The timestamp when the catalog was last updated in ISO 8601 format. '400': description: Bad Request - The request was invalid or cannot be otherwise served. An accompanying error message will explain further. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: product_id: type: string description: can't be blank '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '413': description: "You can upload maximum 100 products in one api call\t- The server is refusing\ \ to process a request because the request payload is larger than the server is willing or\ \ able to process." '422': description: Unprocessable Entity - Some/all of the products have invalid data, please check the response for more information on. '429': description: "Rate limit exceeded\t- Too many requests" '500': description: "Internal Server Error\t- Please contact blueshift for more information" '502': description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff '503': description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff '504': description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff put: summary: Add items to a catalog description: Use this endpoint to add items to a catalog. tags: - Catalog security: - user_api_auth: [] parameters: - in: path required: true name: catalog_uuid description: Specify the UUID of the catalog to which you want to add the items. You can get the catalog's UUID from its URL. For example, if you open a catalog on the Blueshift app, its URL looks like `https://app.getblueshift.com/dashboard#/app/catalogs//details`. schema: type: string example: 89ee8378-a887-474b-8afe-e2369cc9297c - name: syncUpdateWithProductData description: Optional query parameter. When set to `true`, the API returns the product_id and UUID for products that are added successfully. When set to `false` or not provided, returns a simple status response. in: query schema: type: boolean example: true requestBody: content: application/json: schema: type: object properties: catalog: type: object properties: products: type: array description: Specify the items that you want to add to the catalog. items: type: object required: - image - product_id - title - web_link - availability - category additionalProperties: true properties: brand: type: string description: Specify the brand name of the item. example: TechBrand category: type: array items: type: string description: Specify the category identifiers starting from the root of the taxonomy. example: - Electronics - Electronics > Laptops image: type: string description: Specify the link to the image of the item. Ensure that the URL that you provide in this field does not contain more than 500 characters. example: https://example.com/images/product.jpg msrp: type: string description: Specify the maximum suggested retail price of the item (numeric value without currency symbol). example: '999.99' price: type: string description: Specify the selling price of an item (numeric value without currency symbol). example: '899.99' product_id: type: string description: Specify the unique identifier of the item. This is what you pass in the product_ids in your events, and the values specified here must be the same. Ensure that the value that you provide in this field does not contain more than 64 characters. example: PROD123456 availability: type: string description: Specify the availability of the item. example: in_stock tags: type: array description: Specify an array of strings denoting grouping of similar products into collections or groups. items: type: string example: - bestseller - premium parent_sku: type: string description: Provide the SKU to tie all variants or child products together. example: SKU-PARENT-001 title: type: string description: Specify the title of the item. Ensure that the title that you provide in this field does not contain more than 255 characters. example: Premium Laptop 15-inch web_link: type: string description: Specify the URL of the item on your website. Ensure that the URL that you provide in this field does not contain more than 500 characters. example: https://example.com/products/laptop-001 latitude: type: string description: Specify the latitude of the product location (must be between -90 and 90). example: '40.7128' longitude: type: string description: Specify the longitude of the product location (must be between -180 and 180). example: '-74.0060' example: catalog: products: - image: https://example.com/images/product.jpg product_id: PROD123456 title: Premium Laptop 15-inch web_link: https://example.com/products/laptop-001 availability: in_stock category: - Electronics - Electronics > Laptops brand: TechBrand msrp: '999.99' price: '899.99' tags: - bestseller - premium parent_sku: SKU-PARENT-001 latitude: '40.7128' longitude: '-74.0060' responses: '200': description: Products added successfully. Response format varies based on the `syncUpdateWithProductData` query parameter. content: application/json: schema: oneOf: - type: object description: Response when `syncUpdateWithProductData` is not provided or set to `false`. properties: status: type: string example: ok - type: object description: Response when `syncUpdateWithProductData=true`. properties: success: type: object properties: products: type: array items: type: object properties: product_id: type: string description: The unique identifier of the item that was successfully added. uuid: type: string description: The UUID of the item in Blueshift. failure: type: array description: Array of items that failed to be added. items: type: object properties: errors: type: array items: type: object additionalProperties: type: array items: type: string product: type: object description: The product details that failed validation. properties: brand: type: string category: type: array items: type: string image: type: string msrp: type: string price: type: string product_id: type: string availability: type: string tags: type: array items: type: string parent_sku: type: string title: type: string web_link: type: string catalog_uuid: type: string sku: type: string latitude: type: string longitude: type: string examples: without_sync_param: summary: Response without syncUpdateWithProductData or when set to false value: status: ok with_sync_param: summary: Response when syncUpdateWithProductData=true value: success: products: - product_id: PROD123456 uuid: 8da44313-e540-449d-9513-6eb36285bfe3 failure: [] '400': description: Bad Request - The request was invalid or cannot be otherwise served. content: application/json: schema: type: object properties: status: type: integer error: type: string example: status: 400 error: 'Json Parse error: unexpected character at line 10, column 11 [parse.c:671]' '401': description: Unauthorized - API authentication failed. content: application/json: schema: type: object properties: message: type: string example: message: Not authorized '404': description: Not Found - The catalog was not found. content: application/json: schema: type: object properties: status: type: string error: type: string example: status: '404' error: Not Found '413': description: Payload Too Large - You can upload maximum 100 products in one API call. '422': description: Unprocessable Entity - Some/all of the products have invalid data. content: application/json: schema: type: object properties: errors: type: array description: Array of error objects with field-level validation errors. items: type: object additionalProperties: type: array items: type: string products: type: array description: Array of products that failed validation. items: type: object properties: brand: type: string category: type: array items: type: string image: type: string msrp: type: string price: type: string sku: type: string availability: type: string tags: type: array items: type: string parent_sku: type: string title: type: string web_link: type: string catalog_uuid: type: string latitude: type: string longitude: type: string example: errors: - msrp: - is not a number price: - is not a number latitude: - Must be between -90 and 90 products: - image: https://example.com/images/product.jpg title: Premium Laptop 15-inch web_link: https://example.com/products/laptop-001 category: - Electronics - Electronics > Laptops msrp: '999.99' price: '899.99' tags: - bestseller - premium parent_sku: SKU-PARENT-001 catalog_uuid: 89ee8378-a887-474b-8afe-e2369cc9297c sku: PROD123456 availability: in_stock brand: TechBrand latitude: '40.7128' longitude: '-74.0060' '429': description: Too Many Requests - Rate limit exceeded. '500': description: Internal Server Error - Please contact Blueshift support. '502': description: Bad Gateway - Service unavailable, please retry with exponential backoff. '503': description: Service Unavailable - Please retry with exponential backoff. '504': description: Gateway Timeout - Please retry with exponential backoff. /api/v1/custom_user_lists/add_user_to_list/{list_id}: put: summary: Add user to list description: Use this endpoint to add a user to a custom list. tags: - Custom user lists security: - user_api_auth: [] parameters: - in: path name: list_id required: true description: 'Specify the ID of the custom user list to which you want to add a user. You can find the list ID in the URL when viewing the list in the Blueshift app. For example: `https://app.getblueshift.com/dashboard#/app/custom_list/41148/edit` - the list ID here is `41148`.' schema: type: integer example: 41148 requestBody: content: application/json: schema: type: object properties: identifier_key: type: string description: 'Specify how you want to identify the user: • Use `email` to identify by email address • Use `customer_id` to identify by customer ID This must match the source type configured when the list was created.' example: email enum: - email - customer_id identifier_value: type: string description: 'Specify the actual identifier value: • If `identifier_key` is `email`: provide the user''s email address (e.g., `john.doe@example.com`) • If `identifier_key` is `customer_id`: provide the customer ID (e.g., `23a1fae1-2103-4e18-b58c-9db0ea9f7bf7`) You can find the customer ID in the URL when viewing a customer profile: `https://app.getblueshift.com/dashboard#/app/customer//show/overview`' example: john.doe@example.com required: - identifier_key - identifier_value description: Specify the details of the user that you want to add to the list. responses: '200': description: OK '400': description: Bad request - The request was invalid or cannot be otherwise served. An accompanying error message will explain further. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found - Can happen due to resource conflicts. Re-try with exponential backoff. Contact us on support@blueshift.com if the issue persists. '409': description: Conflict error, please retry - The request could not be completed due to a conflict with the current state of the target resource, re-try with exponential backoff. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: "Rate limit exceeded\t- Too many requests. Contact us on support@blueshift.com\ \ for recommended throughput." '500': description: "Internal Server Error\t- Please contact blueshift for more information." '502': description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff. '503': description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff. '504': description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff. /api/v1/custom_user_lists/bulk_add_users_to_list/{list_id}: put: summary: Bulk add users to list description: Bulk add users to a custom list — up to 25 per call, or 500 with `async=true`. tags: - Custom user lists security: - user_api_auth: [] parameters: - in: path name: list_id required: true description: Specify the ID of the list to which you want to add users in bulk. schema: type: integer - in: query name: async required: false description: Set this parameter to `true` to add users to the list asynchronously. In async mode, you can send up to 500 identifier values in one API call, and the request runs in the background after it is accepted. Omit this parameter or set it to `false` to add users synchronously, where you can send up to 25 identifier values in one API call. The response format is the same in both modes. schema: type: boolean default: false requestBody: content: application/json: schema: type: object properties: identifier_key: type: string description: Specify the key that you use to identify the users. This field can either take `customer_id` or `email`. identifier_values: type: array items: type: string description: Specify the values of the identifier key. For example, if you specify `customer_id` in the `identifier_key` field, specify the users' alphanumeric customer IDs in this field. Such as [`abcd1234`]. If you specify `email` in the `identifier_key`, specify the email address of the users you want to add to the list. Such as, [`johndoe@blueshift.com`]. You can send a maximum of 25 values in sync mode and 500 values in async mode. required: - identifier_key - identifier_values description: Specify the details of the users that you want to add to the list. responses: '200': description: OK - The request was successful. In sync mode, the users are added to the list. In async mode, the request is accepted and runs in the background. The response format is the same in both modes. content: application/json: schema: type: object properties: status: type: string example: ok errors: type: array items: type: object example: [] example: status: ok errors: [] '400': description: Input params not valid - The request contains an invalid parameter, such as an unsupported `identifier_key`. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: detail: type: string example: Input params not valid example: errors: - detail: Input params not valid '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: The list has been deleted. '413': description: 'Request Entity Too Large - The number of identifier values exceeds the limit: 25 in sync mode (`async` omitted or `false`), 500 in async mode (`async=true`).' content: application/json: schema: type: object properties: error: type: string example: You can add maximum 25 users in one api call examples: sync_limit_exceeded: summary: Sync mode - more than 25 values value: error: You can add maximum 25 users in one api call async_limit_exceeded: summary: Async mode - more than 500 values value: error: You can add maximum 500 users in one async api call '422': description: Functionality not supported for old list. '429': description: "Rate limit exceeded\t- Too many requests" '500': description: "Internal Server Error\t- Please contact blueshift for more information" '502': description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff '503': description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff '504': description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff /api/v1/custom_user_lists/bulk_remove_users_from_list/{list_id}: put: summary: Bulk remove users from list description: Bulk remove users from a custom list — up to 25 per call, or 500 with `async=true`. tags: - Custom user lists security: - user_api_auth: [] parameters: - in: path name: list_id required: true description: Specify the ID of the list from which you want to remove users in bulk. schema: type: integer - in: query name: async required: false description: Set this parameter to `true` to remove users from the list asynchronously. In async mode, you can send up to 500 identifier values in one API call, and the request runs in the background after it is accepted. Omit this parameter or set it to `false` to remove users synchronously, where you can send up to 25 identifier values in one API call. The response format is the same in both modes. schema: type: boolean default: false requestBody: content: application/json: schema: type: object properties: identifier_key: type: string description: Specify the key that you use to identify the users. This field can either take `customer_id` or `email`. identifier_values: type: array items: type: string description: Specify the values of the identifier key. For example, if you specify `customer_id` in the `identifier_key` field, specify the users' alphanumeric customer IDs in this field. Such as [`abcd1234`]. If you specify `email` in the `identifier_key`, specify the email address of the users you want to remove from the list. Such as, [`johndoe@blueshift.com`]. You can send a maximum of 25 values in sync mode and 500 values in async mode. required: - identifier_key - identifier_values description: Specify the details of the users that you want to bulk remove from the list. responses: '200': description: OK - The request was successful. In sync mode, the users are removed from the list. In async mode, the request is accepted and runs in the background. The response format is the same in both modes. content: application/json: schema: type: object properties: status: type: string example: ok errors: type: array items: type: object example: [] example: status: ok errors: [] '400': description: Input params not valid - The request contains an invalid parameter, such as an unsupported `identifier_key`. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: detail: type: string example: Input params not valid example: errors: - detail: Input params not valid '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: The list has been deleted. '413': description: 'Request Entity Too Large - The number of identifier values exceeds the limit: 25 in sync mode (`async` omitted or `false`), 500 in async mode (`async=true`).' content: application/json: schema: type: object properties: error: type: string example: You can remove maximum 25 users in one api call examples: sync_limit_exceeded: summary: Sync mode - more than 25 values value: error: You can remove maximum 25 users in one api call async_limit_exceeded: summary: Async mode - more than 500 values value: error: You can remove maximum 500 users in one async api call '422': description: Functionality not supported for old list. '429': description: "Rate limit exceeded\t- Too many requests" '500': description: "Internal Server Error\t- Please contact blueshift for more information" '502': description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff '503': description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff '504': description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff /api/v1/custom_user_lists/create: post: summary: Create empty list description: Use this endpoint to create an empty user list. tags: - Custom user lists security: - user_api_auth: [] requestBody: content: application/json: schema: type: object properties: name: type: string example: SF user list description: Specify a name for the list. You can identify the list that you create using this name on the dashboard. Ensure that the name that you specify is unique. description: type: string example: The list of users who are based in San Francisco. description: Specify an appropirate description of that provides context on what the list contains. is_seed_list: type: integer example: 0 description: Specify if this list is a seed list or not. Specify '0' if this is not a seed list. If it is, specify '1'. A seed list is a list of users -- such as internal users -- who should receive a copy of the message that you send in a campaign. You can choose a seed list in either a one-time or a recurring campaign. source: type: string example: email description: "Specify the source that you want to use to add customers to this list.\ \ You can specify either `email` or `customer_id`. If you leave this field empty,\ \ `email` is automatically selected for the list. \n" required: - name - description description: Specify the details about the custom list. responses: '200': description: OK content: application/json: schema: type: object properties: id: type: integer account_id: type: integer example: 182 filename: type: string description: type: string user_count: type: integer status: type: string created_at: type: string format: date-time example: '2024-10-03T04:57:24.000Z' updated_at: type: string format: date-time is_exporting: type: boolean user_id: type: string example: 4981 source: type: string uuid: type: string is_seed_list: type: boolean deleted_at: type: string format: date-time import_method: type: string version: type: string author: type: string example: - id: 48 account_id: 15 filename: f4 description: description filesize: null user_count: 0 status: ready created_at: '2021-08-25T06:06:59.411Z' updated_at: '2021-08-25T06:06:59.411Z' is_exporting: false user_id: 4981 source: email uuid: 35cb281b-efd6-46b8-8f95-90921e4b1d1f is_seed_list: false deleted_at: null import_method: api version: v2 author: John Doe '400': description: Bad request - The request was invalid or cannot be otherwise served. An accompanying error message will explain further. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found - Can happen due to resource conflicts. Re-try with exponential backoff. Contact us on support@blueshift.com if the issue persists. '409': description: Conflict error, please retry - The request could not be completed due to a conflict with the current state of the target resource, re-try with exponential backoff. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: "Rate limit exceeded\t- Too many requests. Contact us on support@blueshift.com\ \ for recommended throughput." '500': description: "Internal Server Error\t- Please contact blueshift for more information." '502': description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff. '503': description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff. '504': description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff. /api/v1/custom_user_lists/id/{custom_user_list_id}: get: summary: Get customer list details description: Use this endpoint to get details of the specified customer list from your account. tags: - Custom user lists security: - user_api_auth: [] parameters: - in: path name: custom_user_list_id required: true description: Specify the ID of the list. schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: id: type: integer example: 6883 account_id: type: integer example: 182 filename: type: string description: The file that you used to import the seed list. example: dummy_push_upload.csv_2017-11-28:T10:11:38 description: type: string example: email,device_tokens,device_ids filesize: type: integer example: 159 user_count: type: integer example: 1000 status: type: string example: ready created_at: type: string format: date-time example: '2024-08-25T06:06:59.412Z' updated_at: type: string format: date-time example: '2021-08-25T06:06:59.412Z' is_exporting: type: boolean example: false user_id: type: integer example: 3808 source: type: string example: email uuid: type: string example: 5ab42b99-3332-4af7-8aad-91b6baa934fa is_seed_list: type: boolean example: true deleted_at: type: string format: date-time example: null version: type: string example: v1 import_method: type: string example: upload author: type: string example: John Doe '400': description: Bad request - The request was invalid or cannot be otherwise served. An accompanying error message will explain further. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found - The customer list you are looking for could not be found. '409': description: Conflict error, please retry - The request could not be completed due to a conflict with the current state of the target resource, re-try with exponential backoff. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: "Rate limit exceeded\t- Too many requests. Contact us on support@blueshift.com\ \ for recommended throughput." '500': description: "Internal Server Error\t- Please contact blueshift for more information." '502': description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff. '503': description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff. '504': description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff. /api/v1/custom_user_lists/overwrite_list/{list_id}: put: summary: Overwrite users in a list description: Use this endpoint to overwrite all users in a custom list. tags: - Custom user lists security: - user_api_auth: [] parameters: - in: path name: list_id required: true description: Specify the ID of the list to which you want to overwrite users. schema: type: integer requestBody: content: application/json: schema: type: object properties: s3_file_path: type: string description: Specify the S3 path of the file containing identifiers that will overwrite users in the custom user list. The recommendation is to upload the file to the import/custom_lists location under the Blueshift S3 bucket. required: - s3_file_path description: Specify the S3 file path with which you want to overwrite the user list responses: '200': description: OK '400': description: Bad request - The request was invalid or cannot be otherwise served. An accompanying error message will explain further. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found - Can happen due to resource conflicts. Re-try with exponential backoff. Contact us on support@blueshift.com if the issue persists. '409': description: Conflict error, please retry - The request could not be completed due to a conflict with the current state of the target resource, re-try with exponential backoff. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: "Rate limit exceeded\t- Too many requests. Contact us on support@blueshift.com\ \ for recommended throughput." '500': description: "Internal Server Error\t- Please contact blueshift for more information." '502': description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff. '503': description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff. '504': description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff. /api/v1/custom_user_lists/remove_user_from_list/{list_id}: put: summary: Remove user from list description: Use this endpoint to remove a user from a custom list. tags: - Custom user lists security: - user_api_auth: [] parameters: - in: path name: list_id required: true description: Specify the ID of the list from which you want to remove a user. schema: type: integer requestBody: content: application/json: schema: type: object properties: identifier_key: type: string description: Specify the key that you use to identify a user. This field can either take `customer_id` or `email`. example: janedoe@acme.com identifier_value: type: string description: Specify the value of the identifier key. For example, if you specify `customer_id` in the `identifier_key` field, specify the user's alphanumeric customer ID in this field. Such as `abcd1234`. If you specify `email` in the `identifier_key`, specify the user's email address. example: '48759893' required: - identifier_key - identifier_value description: Specify the details of the user that you want to remove from the list. responses: '200': description: OK '400': description: Bad request - The request was invalid or cannot be otherwise served. An accompanying error message will explain further. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found - Can happen due to resource conflicts. Re-try with exponential backoff. Contact us on support@blueshift.com if the issue persists. '409': description: Conflict error, please retry - The request could not be completed due to a conflict with the current state of the target resource, re-try with exponential backoff. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: "Rate limit exceeded\t- Too many requests. Contact us on support@blueshift.com\ \ for recommended throughput." '500': description: "Internal Server Error\t- Please contact blueshift for more information." '502': description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff. '503': description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff. '504': description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff. /api/v1/custom_user_lists/seed_lists: get: summary: Get seed lists from your account description: Use this endpoint to get the seed lists from your account. tags: - Custom user lists security: - user_api_auth: [] responses: '200': description: OK content: application/json: schema: type: array items: type: object properties: id: type: integer example: 6883 account_id: type: integer example: 182 filename: type: string description: The file that you used to import the seed list. example: dummy_push_upload.csv_2017-11-28:T10:11:38 description: type: string example: email,device_tokens,device_ids filesize: type: integer example: 159 user_count: type: integer example: 1000 status: type: string example: ready created_at: type: string format: date-time example: '2024-10-03T04:57:24.000Z' updated_at: type: string format: date-time example: '2021-08-25T06:06:59.412Z' is_exported: type: boolean example: false user_id: type: integer example: 3808 source: type: string example: email uuid: type: string example: 5ab42b99-3332-4af7-8aad-91b6baa934fa is_seed_list: type: boolean example: true deleted_at: type: string format: date-time example: null version: type: string example: v1 import_method: type: string example: upload author: type: string example: John Doe '400': description: Bad request - The request was invalid or cannot be otherwise served. An accompanying error message will explain further. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found - Can happen due to resource conflicts. Re-try with exponential backoff. Contact us on support@blueshift.com if the issue persists. '409': description: Conflict error, please retry - The request could not be completed due to a conflict with the current state of the target resource, re-try with exponential backoff. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: "Rate limit exceeded\t- Too many requests. Contact us on support@blueshift.com\ \ for recommended throughput." '500': description: "Internal Server Error\t- Please contact blueshift for more information." '502': description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff. '503': description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff. '504': description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff. /api/v1/customer_attributes/trigger_import: post: tags: - Customer summary: Trigger customer import description: Triggers a launched S3 customer attributes import task. security: - user_api_auth: [] requestBody: content: application/json: schema: type: object required: - uuid properties: uuid: type: string description: The UUID of the customer attributes import task. You can find the UUID in the import task URL on the Blueshift dashboard. For example, for the URL `https://app.getblueshift.com/dashboard#/app/customer/import_show/23114f03-5462-4de5-b112-d316e02650d1`, the UUID is `23114f03-5462-4de5-b112-d316e02650d1`. example: 23114f03-5462-4de5-b112-d316e02650d1 examples: trigger_import: summary: Trigger a customer attributes import value: uuid: 23114f03-5462-4de5-b112-d316e02650d1 description: Provide the UUID of the customer attributes import task that you want to trigger. responses: '200': description: The import was triggered successfully. content: application/json: schema: type: object properties: status: type: string example: ok examples: success: summary: Import triggered value: status: ok '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: example: message: Not authorized '404': description: Resource not found - The import task with the specified UUID was not found. content: application/json: example: errors: - title: error detail: 'Error: Resource not found' meta: combine_errors: false no_toast: false unformatted: error: - Resource not found '405': description: Method not allowed - The import cannot be triggered. This can occur if the import source is not Amazon S3, the import is not in launched state, or the import is already being processed. '429': description: Rate limit exceeded. Too many requests. Contact us at support@blueshift.com for recommended throughput. '500': description: Internal server error. Contact Blueshift for more information. '502': description: Service unavailable, please retry. Bad gateway. '503': description: Service unavailable, please retry. '504': description: Service unavailable, please retry. Gateway timeout. /api/v1/customer_group/{group_id}: delete: tags: - Customer groups summary: Delete customer group description: Deletes a customer group. Set `delete_users` to keep or remove the associated users. security: - user_api_auth: [] parameters: - in: path name: group_id required: true description: The ID of the customer group to delete. This is not the UUID. schema: type: string example: grp_orionretail - in: query name: delete_users required: false description: 'Determines whether the users associated with the group are also deleted. - `false` — Deletes the group and preserves all associated user records. - `true` — Deletes the group and permanently removes all associated users.' schema: type: boolean enum: - false - true default: false example: false responses: '200': description: OK — The group was deleted successfully. content: application/json: schema: type: object properties: group: type: object properties: account_uuid: type: string format: uuid created_at: type: string format: date-time extended_attributes: type: object group_id: type: string updated_at: type: string format: date-time user_count: type: integer user_uuids: type: array items: type: string format: uuid uuid: type: string format: uuid version: type: string email: type: string firstname: type: string lastname: type: string timestamp: type: string format: date-time _bsft_delete_status: type: string example: success examples: preserve_users: summary: Group deleted, users preserved (delete_users=false) value: group: account_uuid: 6352c279-69a2-4222-b988-b01a729a6d2c created_at: '2026-03-10T07:46:30.713Z' extended_attributes: _bsft_js_pipeline: true _bsft_ts: '2026-03-10T07:46:30.656Z' email: admin@orionretail.io firstname: Orion lastname: Retail timestamp: '2026-03-10T07:46:30.656Z' group_id: grp_orionretail updated_at: '2026-03-10T07:54:38.932Z' user_count: 4 user_uuids: - 062b6926-89d2-4dfd-945f-be61720b06ce - 41f446aa-43ca-4718-b45c-c68e575a371f - 81f19599-6fff-4012-8e0a-77941149b599 - ae2ded0f-19b6-4d93-b5f9-66acfd579698 uuid: 479b7071-997c-426e-94a5-387d97897d50 version: '1' email: admin@orionretail.io firstname: Orion lastname: Retail timestamp: '2026-03-10T07:46:30.656Z' _bsft_delete_status: success delete_users: summary: Group and associated users deleted (delete_users=true or omitted) value: group: account_uuid: 6352c279-69a2-4222-b988-b01a729a6d2c created_at: '2026-03-10T07:46:39.531Z' extended_attributes: _bsft_js_pipeline: true _bsft_ts: '2026-03-10T07:46:39.445Z' email: admin@veloxmedia.co firstname: Velox lastname: Media timestamp: '2026-03-10T07:46:39.445Z' group_id: grp_veloxmedia updated_at: '2026-03-10T07:49:07.179Z' user_count: 5 user_uuids: - 4fb30f34-154d-49fe-800d-7bfde5806f27 - 82f10575-5474-4fac-a45b-0d0b434e39e6 - b408e8f6-a011-4c3a-8a16-1d99c4480d61 - b5a1c08b-d2df-4da0-a63c-01f430d31ec3 - b5c77c44-f013-4a96-9df4-62e3b109265b uuid: d18225f5-3a74-443f-b21c-931457688281 version: '1' email: admin@veloxmedia.co firstname: Velox lastname: Media timestamp: '2026-03-10T07:46:39.445Z' _bsft_delete_status: success '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. '404': description: Not Found - The specified group ID was not found. Verify the value and try again. '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. '502': description: Bad Gateway - The server received an invalid response. Retry the request. '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. /api/v1/customer_group/{group_id}/user/{user_uuid}: delete: tags: - Customer groups summary: Remove user from customer group description: Removes a user from a customer group without deleting the user record. security: - user_api_auth: [] parameters: - in: path name: group_id required: true description: The ID of the customer group. This is not the UUID. schema: type: string example: grp_orionretail - in: path name: user_uuid required: true description: The UUID of the user to remove from the group. schema: type: string format: uuid example: 57fbca61-3eed-43ea-aaa6-c35307296035 responses: '200': description: OK — The user was removed from the group successfully. content: application/json: schema: type: object properties: status: type: string example: success message: type: string example: User removed from group successfully group_id: type: string example: grp_orionretail user_uuid: type: string format: uuid example: 57fbca61-3eed-43ea-aaa6-c35307296035 example: status: success message: User removed from group successfully group_id: grp_orionretail user_uuid: 57fbca61-3eed-43ea-aaa6-c35307296035 '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. '404': description: Not Found - The specified group ID or user UUID was not found. Verify the values and try again. '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. '502': description: Bad Gateway - The server received an invalid response. Retry the request. '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. /api/v1/customer_search/show_events: get: tags: - Search summary: Get customer events description: Use this endpoint to fetch the details of the events for a customer using the customer's UUID. security: - user_api_auth: [] parameters: - in: query required: true name: uuid description: Specify the uuid of the customer whose event details you want to fetch. schema: type: string responses: '200': description: OK content: application/json: schema: type: array items: type: object properties: _bsft_doc_type: type: string description: The type of object. example: events _bsft_ts: type: string description: The timestamp in ISO 8601 format when the object was created. example: '2021-08-25T06:06:59.415Z' _bsft_type: type: object properties: name: type: string description: The type of entity within Blueshift. Event in this case. example: events parent: type: integer description: The UUID of the customer who generated this event. example: 51aceb79-2cbc-4e2b-a132-b02de69bba15 _exp: type: string example: 1627204743378 account_uuid: type: string description: The ID of the account under which the user is created. example: 4b5b584f-fee7-44f3-ae3a-8ba90aa7d2d5 browser_platform: type: string description: The platform the used when the event occured. example: Windows browser_type: type: string description: The broswer used when the event occured. example: Firefox browser_version: type: string description: The version of the broswer used. example: '126.0' cookie: type: string description: The Blueshift cookie created during the browser session. example: b854bae6-6dc8-c80c-6133-c45d0ba0fdc4 email: type: string description: The user's email address. event: type: string description: The name of the event. For example, identify, view (product view), add_to_cart, remove_from_cart, checkout, purchase, search, your_custom_event_name (custom event) etc. example: identify event_uuid: type: string description: The unique identifier for the event. example: 3766f118-d4cd-11eb-a278-0242ac110006 ip: type: string description: The IP address of the device used. example: 201.33.19.3 referrer: type: string description: The URL of the page that referred the customer to the specific page on which the event occured. example: http://site.com santized_at: type: string description: The timestamp when our backend processed the event. example: '2021-08-25T06:06:59.415Z' session_uuid: type: string description: The unique identifier for the user session. example: null site: type: string description: The URL for the website accessed by the user. example: http://site.com timestamp: type: string description: The timestamp in ISO 8601 format. example: 2021-06-24T04:53:54Z", timestamp_epoch: type: string description: The number of seconds since January 1, 1970 that have passed since the occurrence of the event. example: 1624510434 url: type: string description: The URL of the page that indicates where the event occured. example: http://site.com user_agent: type: string description: The user-agent that indicates the data source of the API call. example: mozilla/5.0 (macintosh; intel mac os x 10_15_7) applewebkit/537.36 (khtml, like gecko) chrome/91.0.4472.77 safari/537.36 user_uuid: type: string description: The unique identifier for the customer whose events data is being searched. example: 51aceb79-2cbc-4e2b-a132-b02de69bba15 '400': description: The request was invalid or cannot be otherwise served. An accompanying error message will explain further. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found. This can happen due to resource conflicts. Retry with exponential backoff. If the issue persists, contact Blueshift. '409': description: Conflict error, please retry. The request could not be completed due to a conflict with the current state of the target resource. Re-try with exponential backoff. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Rate limit exceeded. Too many requests. Contact us on support@blueshift.com for recommended throughput. '500': description: Internal server error. Contact Blueshift for more information. '502': description: Service unavailable, please retry. Bad gateway. Retry with exponential backoff. '503': description: Service unavailable, please retry. Service unavailable. Retry with exponential backoff. '504': description: Service unavailable, please retry. Gateway timeout. Retry with exponential backoff. /api/v1/customers: get: tags: - Customer summary: Search customer description: Use this endpoint to search for a customer using the email ID that you added to our platform. security: - user_api_auth: [] parameters: - name: email description: Specify the email ID of the customer you want to search for. example: janedoe@acme.com in: query schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: users: type: array items: type: object properties: activated_at: type: string format: date-time example: '2023-01-04T21:51:09.457Z' created_at: type: string format: date-time description: The date and time when the email ID was created. example: '2023-01-04T21:49:32.247Z' custom_attributes: type: object description: Any user-specific information as custom attributes. customer_id: type: string example: '812123' device_ids: type: array example: - 4d031ed8-c40e-57d4-9c99-a3e308d8cd78, 4d031ed8-c40e-57d4-9c99-a3e308d8cd77, 4d031ed8-c40e-57d4-9c99-a3e308d8cd79 items: type: string device_tokens: type: array example: '49244924492449244924492449244924492449244924' items: type: string email: type: string example: janedoe@acme.com email_hash: type: string example: 2de9b640b9ceda26ce4c3d8a919eb42c facebook: type: string example: null first_lp_url: type: string example: null first_referrer: type: string example: null first_utm_campaign: type: string example: summer_sale first_utm_content: type: string example: cta first_utm_medium: type: string example: email first_utm_source: type: string example: blueshift first_utm_term: type: string example: abandoned-wishlist firstname: type: string example: Mike lastname: type: string description: The last name of the customer. example: Doel joined_at: type: string format: date-time example: '2011-10-11T19:58:17Z' last_browser_platform: type: string example: Mac OS X last_browser_type: type: string example: Chrome last_browser_version: type: string example: 17.4 last_ip: type: string example: 201.33.19.3 last_location_city: type: string example: San Francisco last_location_country: type: string example: USA last_location_country_code: type: string example: US last_location_geo_latitude: type: string example: null last_location_geo_longitude: type: string example: null last_location_pin_code: type: string example: '94536' last_location_state: type: string example: California last_location_timezone: type: string example: Pacific/Los_Angeles last_lp_url: type: string example: http://site.com last_pageview_url: type: string example: null last_purchase_at: type: string example: '2021-08-25T06:06:59.410Z' last_referrer: type: string example: null last_send_at: type: string format: date-time last_utm_campaign: type: string example: null last_utm_content: type: string example: null last_utm_medium: type: string example: email last_utm_source: type: string example: null last_utm_term: type: string example: null last_visit_at: type: string example: '2024-05-23T20:10:21Z' lifetime_orders: type: integer example: 535 lifetime_revenue: type: integer example: 490 lifetime_visits: type: integer example: 5 opt_out_of_ads: type: string example: false opted_out_of_ads_at: type: string example: null phone_number: type: string example: null predictive_engagement_percentile: type: integer example: 78 predictive_purchase_intent_percentile: type: integer example: 86 predictive_retention_percentile: type: integer example: 70 session_last_activity_at: type: string format: date-time example: 2017-06-07 01:50:17 +0000 subscribed_at: type: string example: null unsubscribed: type: string example: false unsubscribed_at: type: string example: null updated_at: type: string format: date-time uuid: type: string example: 06743da2-9589-4c01-afda-e3d85e487fa7 user: type: object properties: activated_at: type: string format: date-time example: '2022-09-17T17:03:25Z' created_at: type: string format: date-time example: '2024-10-03T04:57:24.000Z' custom_attributes: type: object description: Aside from standard attributes for user like phone number, email, and first name, you can create custom attributes if the data doesn't fit into standard categories. customer_id: type: string example: '11158123' device_ids: type: array example: - 4d031ed8-c40e-57d4-9c99-a3e308d8cd78, 4d031ed8-c40e-57d4-9c99-a3e308d8cd77, 4d031ed8-c40e-57d4-9c99-a3e308d8cd79 items: type: string device_tokens: type: array example: '49244924492449244924492449244924492449244924' items: type: string email: type: string example: test_api_user@acme.com email_hash: type: string example: e169b640b9ceda26ce4c3d8a919eb42c facebook: type: string example: null first_lp_url: type: string example: null first_referrer: type: string example: null first_utm_campaign: type: string example: retargeting first_utm_content: type: string example: post-purchase-cross-sell first_utm_medium: type: string example: partners first_utm_source: type: string example: criteo first_utm_term: type: string example: web firstname: type: string example: Mike lastname: type: string description: The last name of the customer. example: Doel joined_at: type: string format: date-time example: '2011-10-11T19:58:17Z' last_browser_platform: type: string example: Mac OS X last_browser_type: type: string example: Chrome last_browser_version: type: string example: 30 last_ip: type: string example: 201.33.19.3 last_location_city: type: string example: San Francisco last_location_country: type: string example: USA last_location_country_code: type: string example: US last_location_geo_latitude: type: string example: '16.6178379669105' last_location_geo_longitude: type: string example: '15.6178379669105' last_location_pin_code: type: string example: '94536' last_location_state: type: string example: California last_location_timezone: type: string example: Pacific/Los_Angeles last_lp_url: type: string example: http://site.com last_pageview_url: type: string example: null last_purchase_at: type: string example: '2021-08-25T06:06:59.410Z' last_referrer: type: string example: null last_send_at: type: string format: date-time last_utm_campaign: type: string example: null last_utm_content: type: string example: null last_utm_medium: type: string example: null last_utm_source: type: string example: null last_utm_term: type: string example: null last_visit_at: type: string example: '2024-05-23T20:10:21Z' lifetime_orders: type: integer example: 207 lifetime_revenue: type: integer example: 38612 lifetime_visits: type: integer example: 3158 opt_out_of_ads: type: string example: false opted_out_of_ads_at: type: string example: null phone_number: type: string example: null predictive_engagement_percentile: type: integer example: 78 predictive_purchase_intent_percentile: type: integer example: 86 predictive_retention_percentile: type: integer example: 70 session_last_activity_at: type: string format: date-time example: 2017-06-07 01:50:17 +0000 subscribed_at: type: string example: null unsubscribed: type: string example: false unsubscribed_at: type: string example: null updated_at: type: string format: date-time uuid: type: string example: 06743da2-9589-4c01-afda-e3d85e487fa7 '400': description: Bad request - The request was invalid or cannot be otherwise served. An accompanying error message will explain further. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found - Can happen due to resource conflicts. Re-try with exponential backoff. Contact us on support@blueshift.com if the issue persists. '409': description: Conflict error, please retry - The request could not be completed due to a conflict with the current state of the target resource, re-try with exponential backoff. '413': description: "You can upload maximum 50 users in one api call\t- The server is refusing to process\ \ a request because the request payload is larger than the server is willing or able to process." '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: "Rate limit exceeded\t- Too many requests. Contact us on support@blueshift.com\ \ for recommended throughput." '500': description: "Internal Server Error\t- Please contact blueshift for more information." '502': description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff. '503': description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff. '504': description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff. post: tags: - Customer summary: Create or update customer description: Use this endpoint to create a new customer or update an existing customer. security: - user_api_auth: [] requestBody: content: application/json: schema: type: object additionalProperties: true properties: email: type: string example: janedoe@acme.com description: Specify the email ID of the customer that you want to create or whose details you want to update. Ensure that the email that you provide in this field does not contain more than 64 characters. customer_id: type: string example: '38759877' description: Specify the customer ID of the customer that you want to create or whose details you want to update. phone_number: type: string description: Specify the phone number of the customer that you want to create or whose details you want to update. Ensure that it includes the country code, starts with a `+`, follows the [E.164 standard](https://en.wikipedia.org/wiki/E.164), does not start with a `0`, and contains 6 to 14 characters. example: '+919742888933' subscription_groups: type: array description: Specify the user's subscription preferences. items: type: object properties: id: type: string description: The ID of the subscription group. subscribed: type: boolean description: Enter `true` if the user is subscribed, or `false` if unsubscribed. example: - id: newsletter subscribed: true - id: weekly_promo subscribed: false firstname: type: string example: Mike description: Specify the firstname of the customer that you want to create or whose details you want to update. lastname: type: string example: Doel description: Specify the lastname of the customer that you want to create or whose details you want to update. gender: type: string example: male description: Specify the gender (if required) of the customer that you want to create or whose details you want to update. description: Create customer and update customer attributes responses: '200': description: OK content: application/json: schema: type: object properties: customer: type: object properties: email: type: string example: test_api_user@acme.com description: The email address of the user that you want to create or update. For example, `test_api_user@acme.com`. email_domain: type: string description: Email domain of the user. example: yahoo.com email_hard_bounced: type: boolean example: 'true' email_hash: type: string example: a58639ea568b694d6e056ee72d0b9531 email_spam_reported: type: string example: 'false' customer_id: type: string example: '812123' description: A customer ID to uniquely identify a customer. firstname: type: string example: Jane description: The first name of the customer. lastname: type: string example: Doe description: The last name of the customer. gender: type: string example: female phone_number: type: string example: null created_at: type: string format: date-time example: '2024-10-03T04:57:24.000Z' joined_at: type: string format: date-time example: '2011-10-11T19:58:17Z' updated_at: type: string format: date-time lifetime_orders: type: integer example: 2508 lifetime_revenue: type: integer example: 61008 lifetime_visits: type: integer example: 9299 lifetime_promotions_redeemed: type: integer example: 0 lifetime_referrals: type: integer example: 0 lifetime_reviews: type: integer example: 0 lifetime_sends: type: integer example: 0 lifetime_timespent: type: string format: date-time promotions: type: object bsft_control_bucket: type: string description: Each customer, identified or anonymous, is randomly assigned a control bucket number between 1 to 100. example: '31' custom_attributes: type: object description: Aside from standard attributes for user like phone number, email, and first name, you can create custom attributes if the data doesn't fit into standard categories. devices: type: array items: type: string predictive_engagement_percentile: type: integer example: 78 predictive_purchase_intent_percentile: type: integer example: 86 predictive_retention_percentile: type: integer example: 70 session_last_activity_at: type: string format: date-time example: 2017-06-07 01:50:17 +0000 user_at_home_location: type: string example: 'false' uuid: type: string description: A universally unique identifier to uniquely identify a customer. example: 06743da2-9589-4c01-afda-e3d85e487fa7 '400': description: Bad request - The request was invalid or cannot be otherwise served. An accompanying error message will explain further. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found - Can happen due to resource conflicts. Re-try with exponential backoff. Contact us on support@blueshift.com if the issue persists. '409': description: Conflict error, please retry - The request could not be completed due to a conflict with the current state of the target resource, re-try with exponential backoff. '413': description: "You can upload maximum 50 users in one api call\t- The server is refusing to process\ \ a request because the request payload is larger than the server is willing or able to process." '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: "Rate limit exceeded\t- Too many requests. Contact us on support@blueshift.com\ \ for recommended throughput." '500': description: "Internal Server Error\t- Please contact blueshift for more information." '502': description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff. '503': description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff. '504': description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff. /api/v1/customers/bulk: post: tags: - Customer summary: Bulk create/update customer description: Use this endpoint to create or update details of multiple customers. security: - user_api_auth: [] requestBody: content: application/json: schema: type: object properties: customers: type: array description: Specify the details of the customers that you want to create or of the customers whose details you want to update. items: type: object additionalProperties: true properties: email: type: string example: johndoe@acme.com description: Either email or customer ID are mandatory. Specify the email address of the customer that you want to create or whose details you want to update. Ensure that the email that you provide here contains less than 64 characters. customer_id: type: string example: '6769' description: Either email or customer ID are mandatory. Specify the customer ID of the customer that you want to create or whose details you want to update. firstname: type: string example: John description: Specify the firstname of the customer that you want to create or whose details you want to update. lastname: type: string example: doe description: Specify the lastname of the customer that you want to create or whose details you want to update. uuid: type: string example: 225e6b3b-31b3-4738-b21e-80d71ac6cecc description: Specify the UUID of the customer that you want to create or whose details you want to update. subscription_groups: type: array description: Specify the user's subscription preferences. items: type: object properties: id: type: string description: The ID of the subscription group. subscribed: type: boolean description: Enter `true` if the user is subscribed, or `false` if unsubscribed. example: - id: newsletter subscribed: true - id: weekly_promo subscribed: false responses: '200': description: OK - Request processed. Check the errors array to verify all customers succeeded. Even with 200 OK, individual customers can fail if identifiers are missing. content: application/json: schema: oneOf: - title: Success - All customers processed type: object properties: customers: type: array items: {} maxItems: 0 description: Empty array when all customers succeeded. errors: type: array items: {} maxItems: 0 description: Empty array when all customers succeeded. example: customers: [] errors: [] - title: Partial Failure - Some customers missing identifiers type: object properties: customers: type: array description: Contains customer objects that failed processing. items: type: object additionalProperties: true errors: type: array description: Contains error details for failed customers. items: type: object properties: status: type: integer example: 400 error_data: type: object properties: user_identifier_missing: type: array items: type: string example: - No valid identifier found example: customers: - lastname: Williams customer_id: null errors: - status: 400 error_data: user_identifier_missing: - No valid identifier found '400': description: Bad Request - Malformed request. content: application/json: schema: type: object properties: error: type: string example: bad_request '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found. This can happen due to resource conflicts. Retry with exponential backoff. If the issue persists, contact Blueshift. '409': description: Conflict error, please retry. The request could not be completed due to a conflict with the current state of the target resource. Re-try with exponential backoff. '413': description: You can upload up to 50 users in an API call. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Rate limit exceeded. Too many requests. Contact us on support@blueshift.com for recommended throughput. '500': description: Internal server error. Contact Blueshift for more information. '502': description: Service unavailable, please retry. Bad gateway. Retry with exponential backoff. '503': description: Service unavailable, please retry. Service unavailable. Retry with exponential backoff. '504': description: Service unavailable, please retry. Gateway timeout. Retry with exponential backoff. /api/v1/customers/delete: post: tags: - Customer summary: Delete a customer description: Use this endpoint to permanently delete all personal data of your customer. security: - user_api_auth: [] parameters: - in: query name: delete_all_matching_customers description: Specify this value to true if you want to delete all matching profiles of a customer. example: true schema: type: boolean requestBody: content: application/json: schema: type: object properties: email: type: string description: Specify the email address of the customer that you want to delete. example: janedoe@acme.com customer_id: type: string example: '48759893' description: Specify the customer ID of the customer that you want to delete. responses: '200': description: OK '400': description: The request was invalid or cannot be otherwise served. An accompanying error message will explain further. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found. This can happen due to resource conflicts. Retry with exponential backoff. If the issue persists, contact Blueshift. '409': description: Conflict error, please retry. The request could not be completed due to a conflict with the current state of the target resource. Re-try with exponential backoff. '413': description: You can upload up to 50 users in an API call. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Rate limit exceeded. Too many requests. Contact us on support@blueshift.com for recommended throughput. '500': description: Internal server error. Contact Blueshift for more information. '502': description: Service unavailable, please retry. Bad gateway. Retry with exponential backoff. '503': description: Service unavailable, please retry. Service unavailable. Retry with exponential backoff. '504': description: Service unavailable, please retry. Gateway timeout. Retry with exponential backoff. /api/v1/customers/forget: post: tags: - Customer summary: Stop tracking a customer description: Use this endpoint to permanently delete all personal data associated with a customer and remove them from tracking. security: - user_api_auth: [] requestBody: content: application/json: schema: type: object properties: email: description: Specify the email address of the customer you want to stop tracking. type: string example: janedoe@acme.com customer_id: description: Specify the ID of the customer you want to stop tracking. type: string example: '48759893' cookie: description: Specify the cookie ID assigned to the customer by your website to stop tracking them. type: string example: BSFT-COOKIE-9876543210 device_id: description: Specify the device ID linked to the customer's mobile or web device to stop tracking them. type: string example: AEBE52E7-03EE-455A-B3C4-E57283966239 description: Provide an email address, customer ID, cookie, or device ID to stop tracking a customer and remove their personal data. responses: '200': description: OK '400': description: The request was invalid or cannot be otherwise served. An accompanying error message will explain further. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found. This can happen due to resource conflicts. Retry with exponential backoff. If the issue persists, contact Blueshift. '409': description: Conflict error, please retry. The request could not be completed due to a conflict with the current state of the target resource. Retry with exponential backoff. '413': description: You can upload up to 50 users in an API call. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Rate limit exceeded. Too many requests. Contact us at support@blueshift.com for recommended throughput. '500': description: Internal server error. Contact Blueshift for more information. '502': description: Service unavailable, please retry. Bad gateway. '503': description: Service unavailable, please retry. '504': description: Service unavailable, please retry. Gateway timeout. /api/v1/customers/merge: post: tags: - Customer summary: Merge customers description: Use this endpoint to programmatically merge two duplicate customers, effectively unifying them as one. security: - user_api_auth: [] requestBody: content: application/json: schema: type: object properties: customer_id: description: Specify the customer_id of the duplicate customer. example: '48759893' type: string bsft_new_customer_id: description: Specify the customer_id of the customer that you want to use going forward. This is the ID to whom we will merge details of the duplicate customer. example: '18271400' type: string responses: '200': description: OK '400': description: The request was invalid or cannot be otherwise served. An accompanying error message will explain further. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found. This can happen due to resource conflicts. Retry with exponential backoff. If the issue persists, contact Blueshift. '409': description: Conflict error, please retry. The request could not be completed due to a conflict with the current state of the target resource. Re-try with exponential backoff. '413': description: You can upload up to 50 users in an API call. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Rate limit exceeded. Too many requests. Contact us on support@blueshift.com for recommended throughput. '500': description: Internal server error. Contact Blueshift for more information. '502': description: Service unavailable, please retry. Bad gateway. Retry with exponential backoff. '503': description: Service unavailable, please retry. Service unavailable. Retry with exponential backoff. '504': description: Service unavailable, please retry. Gateway timeout. Retry with exponential backoff. /api/v1/customers/unforget: post: tags: - Customer summary: Start tracking a customer description: Use this endpoint to start tracking a customer. After tracking is enabled, the customer becomes eligible for future campaigns. security: - user_api_auth: [] requestBody: content: application/json: schema: type: object properties: email: description: Specify the email address of the customer you want to start tracking. type: string example: janedoe@acme.com customer_id: description: Specify the ID of the customer you want to start tracking. type: string example: '48759893' cookie: description: Specify the cookie ID assigned to the customer by your website for tracking purposes. type: string example: BSFT-COOKIE-9876543210 device_id: description: Specify the device ID linked to the customer's mobile or web device. type: string example: AEBE52E7-03EE-455A-B3C4-E57283966239 description: Provide an email address, customer ID, cookie, or device ID to resume tracking for a customer whose tracking was stopped. responses: '200': description: OK '400': description: The request was invalid or cannot be otherwise served. An accompanying error message will explain further. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found. This can happen due to resource conflicts. Retry with exponential backoff. If the issue persists, contact Blueshift. '409': description: Conflict error, please retry. The request could not be completed due to a conflict with the current state of the target resource. Retry with exponential backoff. '413': description: You can upload up to 50 users in an API call. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Rate limit exceeded. Too many requests. Contact us at support@blueshift.com for recommended throughput. '500': description: Internal server error. Contact Blueshift for more information. '502': description: Service unavailable, please retry. Bad gateway. '503': description: Service unavailable, please retry. '504': description: Service unavailable, please retry. Gateway timeout. /api/v1/customers/{uuid}: get: tags: - Customer summary: Get customer description: Use this endpoint to get the details of a customer using the customer's UUID. security: - user_api_auth: [] parameters: - in: path required: true name: uuid description: Specify the UUID of the customer whose details you want to get. schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: customer: type: object properties: activated_at: type: string format: date-time example: '2022-09-17T17:03:25Z' created_at: type: string format: date-time example: '2024-10-03T04:57:24.000Z' custom_attributes: type: object description: Aside from standard attributes for user like phone number, email, and first name, you can create custom attributes if the data doesn't fit into standard categories. customer_id: type: string example: '812123' device_ids: type: array example: - 4d031ed8-c40e-57d4-9c99-a3e308d8cd78, 4d031ed8-c40e-57d4-9c99-a3e308d8cd77, 4d031ed8-c40e-57d4-9c99-a3e308d8cd79 items: type: string device_tokens: type: array example: '49244924492449244924492449244924492449244924' items: type: string email: type: string example: test_api_user@acme.com email_hash: type: string example: e169b640b9ceda26ce4c3d8a919eb42c facebook: type: string example: null first_lp_url: type: string example: null first_referrer: type: string example: https://www.example.com/Shopping/Checkout/SelectPayment first_utm_campaign: type: string example: granularremarketing first_utm_content: type: string example: ip-warming-campaign-2 first_utm_medium: type: string example: cpc first_utm_source: type: string example: google first_utm_term: type: string example: abandoned-wishlist firstname: type: string example: Mike lastname: type: string example: Doel description: The last name of the customer. joined_at: type: string format: date-time example: '2011-10-11T19:58:17Z' last_browser_platform: type: string example: Mac OS X last_browser_type: type: string example: Chrome last_browser_version: type: string example: '30' last_ip: type: string example: 201.33.19.3 last_location_city: type: string example: San Francisco last_location_country: type: string example: USA last_location_country_code: type: string example: US last_location_geo_latitude: type: string example: 'null' last_location_geo_longitude: type: string example: 'null' last_location_pin_code: type: string example: '94536' last_location_state: type: string example: California last_location_timezone: type: string example: Pacific/Los_Angeles last_lp_url: type: string example: http://site.com last_pageview_url: type: string example: null last_purchase_at: type: string example: '2021-08-25T06:06:59.410Z' last_referrer: type: string example: null last_send_at: type: string format: date-time last_utm_campaign: type: string example: null last_utm_content: type: string example: null last_utm_medium: type: string example: null last_utm_source: type: string example: null last_utm_term: type: string example: null last_visit_at: type: string example: '2024-05-23T20:10:21Z' lifetime_orders: type: integer example: 0 lifetime_revenue: type: integer example: 0 lifetime_visits: type: integer example: 5 opt_out_of_ads: type: string example: false opted_out_of_ads_at: type: string example: null phone_number: type: string example: null predictive_engagement_percentile: type: integer example: 78 predictive_purchase_intent_percentile: type: integer example: 86 predictive_retention_percentile: type: integer example: 70 session_last_activity_at: type: string format: date-time example: 2017-06-07 01:50:17 +0000 subscribed_at: type: string example: null unsubscribed: type: string example: false unsubscribed_at: type: string example: null updated_at: type: string format: date-time uuid: type: string example: 06743da2-9589-4c01-afda-e3d85e487fa7 '400': description: The request was invalid or cannot be otherwise served. An accompanying error message will explain further. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found. This can happen due to resource conflicts. Retry with exponential backoff. If the issue persists, contact Blueshift. '409': description: Conflict error, please retry. The request could not be completed due to a conflict with the current state of the target resource. Re-try with exponential backoff. '413': description: You can upload up to 50 users in an API call. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Rate limit exceeded. Too many requests. Contact us on support@blueshift.com for recommended throughput. '500': description: Internal server error. Contact Blueshift for more information. '502': description: Service unavailable, please retry. Bad gateway. Retry with exponential backoff. '503': description: Service unavailable, please retry. Service unavailable. Retry with exponential backoff. '504': description: Service unavailable, please retry. Gateway timeout. Retry with exponential backoff. /api/v1/data_connectors/{data_connector_uuid}/debug: get: summary: Debug event exports description: Use this endpoint to download the first 10 success and errored events in last 5 minutes. tags: - Event security: - event_api_auth: [] parameters: - in: path name: data_connector_uuid required: true description: Specify the UUID of the data connector (event export integration). schema: type: string example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 responses: '200': description: OK content: application/json: schema: type: object properties: success: type: array items: type: object description: Returns the success API request payload. properties: api_key: type: string description: Masked API key used in the payload. events: type: array items: type: object description: Array of event payloads which was sent to destination. failure: type: array items: type: object description: Returns the errored API request payload. properties: _bsft_outbound_data_error: type: string description: The error message for the errored API request. events: type: array items: type: object description: Array of event payloads which was sent to destination. '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: message: type: string example: Bad Request '401': description: Unauthorized - The User API key was incorrect or this feature is not enabled for your account. '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found. This can happen due to resource conflicts. Retry with exponential backoff. If the issue persists, contact Blueshift. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout /api/v1/email_templates.json: get: summary: List email templates description: Use this endpoint to get the list of email templates. tags: - Email template security: - user_api_auth: [] parameters: - name: name description: Search for email templates that contain the specified string in the name of the template. example: Support email in: query schema: type: string - name: archived description: Search for templates with specified archived status. Specify value as `0` to get a list of un-archived templates, or as `1` to get a list of archived templates. Leave blank to get a list of all templates. example: true in: query schema: type: integer - name: resource.editor_type description: Search for templates of the specified type. Specify value as `html` to get a list of HTML templates or `bee_editor` to get a list of Visual Editor templates. Leave blank to get a list of all templates. example: bee_editor in: query schema: type: string - name: per_page description: Specify the number of records to be returned per page example: 1 in: query schema: type: string - name: page description: Specify the page number for the search results. example: 1 in: query schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: template: type: array description: The list of email templates. items: type: object properties: name: type: string description: The name of the email template. example: Support email created_at: type: string format: date-time description: The date and time when the email template was created. example: '2024-05-22T15:27:16.000Z' updated_at: type: string format: date-time description: The date and time when the email template was last updated. example: '2024-05-24T05:01:54.000Z' uuid: type: string description: The UUID of the email template. example: 94d45bc8-3488-2002-cd9b-d6314445c545 author: type: string description: The author of the email template. example: Jane Doe resource: type: object properties: updated_at: type: string format: date-time description: The date and time when the resource (such as the template's subject or content) got updated. example: '2024-05-24T05:01:37.000Z' '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: message: type: string example: Bad Request '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout post: summary: Create email template description: Use this endpoint to create an email template. tags: - Email template security: - user_api_auth: [] requestBody: content: application/json: schema: type: object required: - name - resource - skip_user_on_external_fetch_error - template_properties properties: name: type: string example: My API Template description: Specify the name for the template. author: type: string example: john.doe@blueshift.com description: Specify the email address of the template's author. resource: type: object required: - subject - content properties: subject: type: string description: Specify the subject line of the template. example: Hey, {{user.firstname}}! preheader: type: string description: Specify the preheader line of the template. example: Here are few deals you don't want to miss! content: type: string description: Specify the body of the template with its HTML content. example: ' Hello ' skip_user_on_external_fetch_error: type: boolean default: true description: Message is not sent to user if the external fetch encounters an error or does not return any data) example: true template_properties: type: array maxItems: 1 description: Specify the campaign behavior properties for the template. items: type: object required: - skip_user_on_blank_products - skip_user_on_blank_event_products properties: skip_user_on_blank_products: type: boolean default: true skip_user_on_blank_event_products: type: boolean default: true account_algorithm_uuid: type: string nullable: true description: Specify the recommendation scheme for the template. If you leave this field blank, no change will be done to any recommendation schemes that were previously added to the template. If you send null as a value, any recommendation schemes that were previously added to the template will be removed. example: 2879b1a3-ee84-4e13-b63c-ad83674c0ca1 external_fetches: type: array description: Specify the external fetches for the template. example: - uuid: e789705f-3eb3-4e2a-a666-648dedae6g86 - uuid: af9bbbd3-7133-4ab4-80a2-938b67c12d34 items: type: object required: - uuid properties: uuid: type: string transaction_mixins: type: array description: Specify the transaction mixins for the template. Note that when you add multiple transaction mixins, the resultant transactions are the OR result of all the queries related to the transactions mixins. For example, the resultant JSON response will contain any transaction that meets EITHER the `transaction_mixin1` criteria OR the `transaction_mixin2` criteria (or both). example: - uuid: transaction_mixin1_uuid - uuid: transaction_mixin2_uuid items: type: object required: - uuid properties: uuid: type: string tag_data: type: string description: "Specify a folder and then tags under the folder in the format `folder_name:\ \ tag1, tag2, tag3`. For example, `Regions:USA,China,Brazil,Hong Kong,India,Sweden,Canada`.\n\ \ \n > **\U0001F4D8** Tag data should exist in your account.\n" example: Regions:NA,EU,APAC,LATAM,GreaterChina description: Takes the template details returns a JSON that provides the UUID of the created template. responses: '200': description: OK '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: message: type: string example: Bad Request '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout /api/v1/email_templates/test_send.json: post: summary: Send a test mail description: Use this endpoint to send a test mail to a specific email address. tags: - Email template security: - user_api_auth: [] requestBody: content: application/json: schema: type: object required: - id - personalize_for properties: id: type: string description: Specify the UUID of the template. The template uuids can be found by [querying the index](https://developer.blueshift.com/reference/email-template#get_api-v1-email-templates-json), or from the URL when you view a template in the Blueshift app. For example, in `https://app.getblueshift.com/dashboard#/email_template_studio//edit/info`, the `` is the uuid you need. example: 9da0744e-***-**-85d7-***4ac745b personalize_for: type: string description: Specify the email address of the user whose personalization context we should use to send the test email. example: testuser@acme.com recipients: type: array description: Specify email addresses of the recipients example: - email1 - email2 - email3 - '...' items: type: string from_name: type: string description: "Specify the name that we should use in the `from` field of the email.\n\ \ > **\U0001F4D8** This is only applicable for the email channel.\n" example: Blueshift Support from_address: type: string description: "Specify the email address that we should use as the sender's email address.\ \ For example, `support@blueshift.com`.\n > **\U0001F4D8** This is only applicable\ \ for the email channel. \nYou can take a look at documentation on [SendGrid](https://help.blueshift.com/hc/en-us/articles/360046787053-SendGrid-Email#h_6da2d422-23a0-4504-b0ce-000b203201fd)\ \ for reference. If you use a different adapter, you can review its documentation\ \ too.\n" example: support@blueshift.com reply_to_address: type: string description: "Specify the email address to which your customers can reply to, if they\ \ want to reply to an email that our platform sends.\n > **\U0001F4D8** This is only\ \ applicable for the email channel. \nYou can take a look at documentation on [SendGrid](https://help.blueshift.com/hc/en-us/articles/360046787053-SendGrid-Email#h_6da2d422-23a0-4504-b0ce-000b203201fd)\ \ for reference. If you use a different adapter, you can review its documentation\ \ too.\n" example: support@blueshift.com description: Sends a test mail to a specific email address, using the personalization context for a given user. The following request will send a test mail to me@example.com responses: '200': description: OK '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: message: type: string example: Bad Request '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout /api/v1/email_templates/{TEMPLATE_UUID}.json: get: summary: Get template details description: Use this endpoint to get a JSON representation of your email template along with a list of campaigns using the template. tags: - Email template security: - user_api_auth: [] parameters: - name: TEMPLATE_UUID in: path required: true description: Specify the UUID of the template. The template uuids can be found by [querying the index](https://developer.blueshift.com/reference/email-template#get_api-v1-email-templates-json), or from the URL when you view a template in the Blueshift app. For example, in `https://app.getblueshift.com/dashboard#/email_template_studio//edit/info`, the `` is the uuid you need. example: 9da0744e-***-**-85d7-***4ac745b schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: name: type: string example: my template description: The name of the template. created_at: type: string format: date-time description: The date and time when the template was created. example: '2023-10-03T04:57:24.000Z' updated_at: type: string format: date-time description: The date and time when the template was updated. example: '2024-05-03T04:57:24.000Z' uuid: type: string example: 1da9e1e8-feae-4ec3-be0a-7dba528590bb description: The UUID of the template. author: type: string example: Bertram Gilfoyle description: The name of the author of the template. resource: type: object properties: subject: type: string example: Hello description: The subject line of the email template. content: type: string example: ' Hello' description: The HTML content of the email template. campaigns: type: array items: type: object properties: names: type: string uuid: type: string status: type: string description: The list of campaigns that use this template. example: - names: my campaign uuid: f63ebf4f-160b-42d8-b482-cbe0fc7de6b7 status: draft - names: my other campaign uuid: ab67f1a7-efbb-46cd-8e9d-9a823e77bf1c status: launched '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: message: type: string example: Bad Request '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout put: summary: Update email template description: Use this endpoint to update an email template. tags: - Email template security: - user_api_auth: [] parameters: - name: TEMPLATE_UUID in: path required: true description: Specify the UUID of the template. The template uuids can be found by [querying the index](https://developer.blueshift.com/reference/email-template#get_api-v1-email-templates-json), or from the URL when you view a template in the Blueshift app. For example, in `https://app.getblueshift.com/dashboard#/email_template_studio//edit/info`, the `` is the uuid you need. example: 9da0744e-***-**-85d7-***4ac745b schema: type: string requestBody: content: application/json: schema: type: object properties: resource: type: object properties: subject: type: string description: Specify the subject line of the template. example: Hey there {{user.firstname}}! preheader: type: string description: Specify the preheader line of the template. example: Recommendations just for you. Get it now! content: type: string example: ' Hello ' description: "Specify the body of the template with its HTML content. \nEnsure that\ \ you format your subject and content as a quoted string literal. \n- **Incorrect**:\ \ ``\n- **Correct**: `` \nFailure to properly escape your content results in a malformed JSON, and\ \ a malformed JSON leads to an error or mangled mangled content. You can use this\ \ [online tool](https://www.freeformatter.com/json-escape.html) to see an example\ \ of how it should look.\n" skip_user_on_external_fetch_error: type: boolean default: true description: Message is not sent to user if the external fetch encounters an error or does not return any data) example: true template_properties: type: array maxItems: 1 description: Specify the campaign behavior properties for the template. items: type: object properties: skip_user_on_blank_products: type: boolean default: true example: true skip_user_on_blank_event_products: type: boolean default: true example: true account_algorithm_uuid: type: string nullable: true description: Specify the recommendation scheme for the template. If you leave this field blank, no change will be done to any recommendation schemes that were previously added to the template. If you send null as a value, any recommendation schemes that were previously added to the template will be removed. example: 4879b1a3-ee24-3e13-a63c-da83674c0ca2 external_fetches: type: array description: Specify the external fetches for the template. If you leave this field blank, any external fetches that were previously added to the template will be removed. example: - uuid: e789705f-3eb3-4e2a-a666-648dedae6g86 - uuid: af9bbbd3-7133-4ab4-80a2-938b67c12d34 items: type: object properties: uuid: type: string transaction_mixins: type: array description: Specify the transaction mixins for the template. If you leave this field blank, any transaction mixins that were previously added to the template will be removed. If you add multiple transaction mixins, the resultant transactions are the OR result of all the queries related to the transactions mixins. example: - uuid: transaction_mixin1_uuid - uuid: transaction_mixin2_uuid items: type: object properties: uuid: type: string description: Takes the UUID and details of template to update it. responses: '200': description: OK '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: message: type: string example: Bad Request '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout /api/v1/emails/bulk_validate: post: tags: - Email validation summary: Validate multiple email addresses description: Use this endpoint to validate up to 30 email addresses. This feature requires custom setup. Contact Blueshift Support or your CSM to enable it. security: - user_api_auth: [] requestBody: required: true content: application/json: schema: type: object properties: emails: type: array description: A list of email addresses to validate (max 30). items: type: string example: - janedoe@acme.com - bob@tempmail.com required: - emails responses: '200': description: Bulk email validation result. content: application/json: schema: type: object properties: result: type: array items: type: object additionalProperties: type: object properties: address: type: string did_you_mean: type: string engagement: type: object properties: engaging: type: boolean is_bot: type: boolean is_disposable_address: type: boolean is_role_address: type: boolean reason: type: array items: type: string result: type: string risk: type: string example: result: - janedoe@acme.com: address: janedoe@acme.com engagement: engaging: true is_bot: false is_disposable_address: false is_role_address: false reason: [] result: deliverable risk: low - bob@tempmail.com: address: bob@tempmail.com engagement: engaging: false is_bot: false is_disposable_address: true is_role_address: false reason: - disposable result: invalid risk: high '400': description: Bad Request - The request contains missing or invalid parameters. content: application/json: example: errors: email: - can't be blank or is invalid '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: example: message: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: example: message: Permission denied '404': description: Not Found - The requested API endpoint does not exist. content: application/json: example: message: Endpoint not found '413': description: Payload Too Large - The request payload exceeds the allowed limit. content: application/json: example: message: You can validate a maximum of 30 emails in one API call. '429': description: Too Many Requests - The request limit has been exceeded. content: application/json: example: message: Rate limit exceeded '500': description: Internal Server Error - An unexpected error occurred. content: application/json: example: message: Internal Server Error - Please contact support for more information. '502': description: Bad Gateway - The server received an invalid response. content: application/json: example: message: Bad Gateway - Please retry the request. '503': description: Service Unavailable - The service is temporarily unavailable. content: application/json: example: message: Service Unavailable - Try again later. '504': description: Gateway Timeout - The server took too long to respond. content: application/json: example: message: Gateway Timeout - Retry with exponential backoff. /api/v1/emails/validate: get: tags: - Email validation summary: Validate a single email address description: Use this endpoint to validate a single email address and evaluate its deliverability and risk profile. security: - user_api_auth: [] parameters: - in: query name: email required: true description: The email address to validate. schema: type: string example: janedoe@acme.com responses: '200': description: OK content: application/json: schema: type: object properties: result: type: object properties: address: type: string engagement: type: object properties: engaging: type: boolean is_bot: type: boolean is_disposable_address: type: boolean is_role_address: type: boolean reason: type: array items: type: string result: type: string risk: type: string example: result: address: janedoe@acme.com engagement: engaging: true is_bot: false is_disposable_address: false is_role_address: false reason: [] result: deliverable risk: low '400': description: Bad Request - The request contains missing or invalid parameters. content: application/json: example: errors: email: - can't be blank or is invalid '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: example: message: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: example: message: Permission denied '404': description: Not Found - The requested API endpoint does not exist. content: application/json: example: message: Endpoint not found '413': description: Payload Too Large - The request payload exceeds the allowed limit. content: application/json: example: message: You can validate a maximum of 30 emails in one API call. '429': description: Too Many Requests - The request limit has been exceeded. content: application/json: example: message: Rate limit exceeded '500': description: Internal Server Error - An unexpected error occurred. content: application/json: example: message: Internal Server Error - Please contact support for more information. '502': description: Bad Gateway - The server received an invalid response. content: application/json: example: message: Bad Gateway - Please retry the request. '503': description: Service Unavailable - The service is temporarily unavailable. content: application/json: example: message: Service Unavailable - Try again later. '504': description: Gateway Timeout - The server took too long to respond. content: application/json: example: message: Gateway Timeout - Retry with exponential backoff. /api/v1/event: post: summary: Send an event description: Use this endpoint to send an event from your server or use javascript events to call the API. tags: - Event security: - event_api_auth: [] requestBody: content: application/json: schema: type: object additionalProperties: true required: - event properties: customer_id: type: string description: 'Specify the customer ID. You must specify information in either this field or atleast in one of the following fields: `event`, `device_id`, `email`, or `group_id`. These fields are described below.' example: '812123' event: type: string description: "Specify the name of the event. For example identify, view (product view),\ \ add_to_cart, remove_from_cart, checkout, purchase, search, your_custom_event_name\ \ (custom event) etc. You must atleast specify this value, or one or more of the following\ \ fields: customer_id/device_id/email. \n > **\U0001F4D8** Ensure that the event name\ \ does not contain periods (`.`), whitespaces, is not a numeric value, and contains\ \ not more than 64 characters.\n" example: identify device_type: type: string description: Specify the type of the device. example: ios device_token: type: string description: "Specify the token of the device.\n > **\U0001F4D8** If you use the event\ \ API to identify a user from a mobile app, ensure that you also include `device_id`\ \ and `device_token` parameters in your API call. However, we recommend that you use\ \ our SDK to identify users on a mobile app. For more information, see [Track events\ \ on your Android app](https://developer.blueshift.com/docs/events-tracking-android-sdk)\ \ and [Track events on your iOS app](https://developer.blueshift.com/docs/track-events-on-your-app-with-blueshifts-ios-sdk).\n" example: '49244924492449244924492449244924492449244924' device_id: type: string description: "Specify the UUID of the device. You must atleast specify this value, or\ \ one or more of the following fields: event/customer_id/email.\n > **\U0001F4D8**\ \ If you use the event API to identify a user from a mobile app, ensure that you also\ \ include `device_id` and `device_token` parameters in your API call. However, we\ \ recommend that you use our SDK to identify users on a mobile app. For more information,\ \ see [Track events on your Android app](https://developer.blueshift.com/docs/events-tracking-android-sdk)\ \ and [Track events on your iOS app](https://developer.blueshift.com/docs/track-events-on-your-app-with-blueshifts-ios-sdk).\n" example: 8abe3faa-d48d-4e4a-00ca-beae01f1c987 device_idfa: type: string description: Sepcify the advertising identifier (idfa) on the device. example: 4d031ed8-c40e-57d4-9c99-a3e308d8cd78 device_idfv: type: string description: Specify the identfier for vendor (idfv) on the device. example: 6d031ec8-e40c-47d4-9c99-b3e308d8ed78 device_manufacturer: type: string description: Specify the manufacturer of the device. example: apple os_name: type: string description: Specify the OS name. example: ios network_carrier: type: string description: Specify the carrier on the mobile device. example: verizon ip: type: string description: Specify the IP address of the device. example: 192.0.2.1 email: type: string description: 'Specify the user''s email address. For example, abc@def.com. You must atleast specify this value, or one or more of the following fields: event/device_id/customer_id.' example: janedoe@acme.com latitude: type: string description: Specify the latitude of the user's location. example: '212.99333' longitude: type: string description: Specify the longitude of the user's location. example: '-12.39334' event_uuid: type: string description: Specify a unique identifier of the event in the format `1234abcd-efghijkj-1234kfjadslk-34iu123`. For reference on the UUID format, see [RFC 4122](https://tools.ietf.org/html/rfc4122.html). Ensure that the `event_uuid` that you specify is unique. This is an optional field and you can leave this field blank. example: 4f575aa4-082c-12ed-dd00-0676ac110004 cookie: type: string description: User's Blueshift cookie used as an identifier for anonymous users. example: 8d74322c-7bb6-44f1-18ce-6a92c5a9672f subscription_groups: type: array description: Specify the user's subscription preferences. items: type: object properties: id: type: string description: The ID of the subscription group. subscribed: type: boolean description: Enter `true` if the user is subscribed, or `false` if unsubscribed. example: - id: newsletter subscribed: true - id: weekly_promo subscribed: false description: Specify device_id. The device_id is the mobile specific (iOS or Android) device identifier to uniquely identify the mobile device. responses: '200': description: OK content: application/json: schema: type: object properties: status: type: string description: OK or Bad request example: OK '400': description: Bad Request - The request was invalid or cannot be otherwise served. An accompanying error message will explain further. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: customer_id: type: string example: can't be blank '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '413': description: You can upload upto 100 products in an api call. The server is refusing to process a request because the request payload is larger than the server is willing or able to process. '422': description: Unprocessable Entity - Some/all of the products have invalid data, please check the response for more information on. '429': description: Rate limit exceeded - Too many requests '500': description: "Internal Server Error\t- Please contact blueshift for more information" '502': description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff '503': description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff '504': description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff /api/v1/event/debug: get: summary: Most recent event description: Use this endpoint to fetch the most recent event. It returns the latest events our server has received for each event type. tags: - Event security: - event_api_auth: [] responses: '200': description: OK content: application/json: schema: type: object properties: customer_id: type: string example: '812123' description: The customer ID. event: type: string description: The name of the event. For example, identify, view (product view), add_to_cart, remove_from_cart, checkout, purchase, search, your_custom_event_name (custom event) etc. example: identify device_type: type: string description: The type of the device. For example, ios or android. example: ios device_tokens: type: string description: The token of the device. example: '49244924492449244924492449244924492449244924' device_id: type: string description: The UUID of the device. example: 8abe3faa-d48d-4e4a-00ca-beae01f1c987 device_idfa: type: string description: The advertising identifier (idfa) on the device. example: 4d031ed8-c40e-57d4-9c99-a3e308d8cd78 device_idfv: type: string description: The identfier for vendor (idfv) on the device. example: 6d031ec8-e40c-47d4-9c99-b3e308d8ed78 device_manufacturer: type: string description: The manufacturer of the device. example: apple os_name: type: string description: The OS name. example: ios network_carrier: type: string description: The carrier on the mobile device. example: verizon ip: type: string description: The IP address of the device. example: 123.123.123.123 email: type: string description: The user's email address. example: janedoe@acme.com latitude: type: string description: The latitude of the user's location. example: '212.99333' longitude: type: string description: The longitude of the user's location. example: '-12.39334' '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: message: type: string example: Bad Request '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout /api/v1/event/history: get: tags: - Event summary: Get event history description: Retrieves up to 50 most recent successful events for the given event name, starting with the latest. security: - event_api_auth: [] parameters: - in: query name: event_name required: true description: The name of the event for which to fetch history. schema: type: string example: app_install - in: query name: limit required: false description: 'Maximum number of records to return. Defaults to system limit if not specified. **Maximum value**: `50`.' schema: type: integer maximum: 50 example: 10 responses: '200': description: OK content: application/json: schema: type: object additionalProperties: type: array items: type: object properties: _bsft_ts: type: string format: date-time description: Event ingestion timestamp in ISO 8601 format. example: '2025-09-17T10:26:55.000Z' account_uuid: type: string description: UUID of the Blueshift account. example: 11112222-3333-4444-5555-666677778888 event: type: string description: The event name. example: app_install event_uuid: type: string description: The unique UUID for this event occurrence. example: aaaa1111-bbbb-2222-cccc-3333dddd4444 site: type: string description: The site associated with the event. example: demoappsite.com timestamp: type: string format: date-time description: The event timestamp in ISO 8601 format. example: '2025-09-17T10:26:54.688Z' timestamp_epoch: type: integer description: The event timestamp in epoch seconds. example: 1758104814 user_agent: type: string description: The user agent string captured for the event. example: Dalvik/2.1.0 (Linux; U; Android 16; Pixel 8 Build/ABC123) additionalProperties: true example: app_install: - _bsft_ts: '2025-09-17T10:26:55.000Z' account_uuid: 11112222-3333-4444-5555-666677778888 app_installed_at: '2025-09-17T10:26:54.687Z' app_name: com.example.demoapp app_version: 5.0.0 (42) bsft_sdk_version: 5.0.0 country_code: US device_id: abcd1234-5678-90ef-ghij-1234567890kl device_manufacturer: ExampleTech device_type: android enable_inapp: true enable_push: false event: app_install event_uuid: aaaa1111-bbbb-2222-cccc-3333dddd4444 language_code: en os_name: Android 16 site: demoappsite.com timestamp: '2025-09-17T10:26:54.688Z' timestamp_epoch: 1758104814 user_agent: Dalvik/2.1.0 (Linux; U; Android 16; Pixel 8 Build/ABC123) - _bsft_ts: '2025-09-17T06:47:22.572Z' account_uuid: 11112222-3333-4444-5555-666677778888 app_installed_at: '2025-09-17T06:47:22.060Z' app_name: com.example.demoapp app_version: 5.0.0 (42) bsft_sdk_version: 5.0.0 country_code: US device_id: mnop9876-5432-10fe-dcba-0987654321zx device_manufacturer: ExampleTech device_type: android enable_inapp: true enable_push: true event: app_install event_uuid: eeee5555-ffff-6666-gggg-7777hhhh8888 language_code: en os_name: Android 16 site: demoappsite.com timestamp: '2025-09-17T06:47:22.062Z' timestamp_epoch: 1758091642 user_agent: Dalvik/2.1.0 (Linux; U; Android 16; Pixel 8 Build/XYZ456) '400': description: Bad request – The request is invalid due to missing or incorrect parameters. '401': description: Unauthorized – API authentication failed due to an invalid or missing API key. '403': description: Forbidden – The API key does not have sufficient permissions to perform this action. '404': description: Not found – The specified resource was not found. '422': description: Unprocessable entity – The request was well-formed but could not be processed due to validation or state errors. '429': description: Rate limit exceeded – Too many requests. Reduce request frequency. '500': description: Internal server error – An unexpected server error occurred. Contact Blueshift support if the issue persists. '502': description: Bad gateway – The server received an invalid response. Retry the request. '503': description: Service unavailable – The service is temporarily unavailable. Try again later. '504': description: Gateway timeout – The server took too long to respond. Retry with exponential backoff. /api/v1/event/summary.json: post: summary: Summary of events description: Use this endpoint to get a summary of counted events. By default, this endpoint returns data for the last 7 days. tags: - Event security: - user_api_auth: [] parameters: - in: query name: timestamp_start description: Specify a timestamp in ISO 8601 format to filter data for events that occurred after it. example: '2023-04-25T00:00:00Z' schema: type: string format: date-time - in: query name: timestamp_end description: Specify a timestamp in ISO 8601 format to filter data for events that occured before it. example: '2023-04-26T23:59:59Z' schema: type: string format: date-time responses: '200': description: OK content: application/json: schema: type: object properties: events_chart_stats: type: array items: type: object description: This data could include events, counts, and other relevant metrics. properties: archives: type: object error: type: object properties: invalid_user_attributes: type: array items: type: number description: Number of errors due to invalid user attributes example: '[10, 15, 27]' missing_identifier: type: array items: type: number description: Number of errors due to missing identifiers example: '[20, 30, 15]' events: type: object properties: add_to_cart: type: array items: type: number description: Array of event counts for `add_to_cart` events over the timeframe. example: '[20, 30, 15]' subscription_update: type: array items: type: number description: Array of event counts for `subscription_update` events over the timeframe. example: - '53' - '42' - '16' timelapse: type: array items: type: string description: Format will be MM/DD for daily data example: - 04/25 - 04/26 - 04/27 stats: type: object properties: add_to_cart: type: object properties: archived: type: boolean example: false count: type: number description: Event count example: 375983 display_name: type: string description: Typically same as the event name, such as, view, purchase, search. example: add_to_cart type: type: string subscription_update: type: object properties: archived: type: boolean count: type: number description: Event count example: 375983 display_name: type: string description: Typically same as the event name, such as, view, purchase, search. example: pageload type: type: string description: Specifies whether an event is standard or custom event. example: standard status: type: string timestamp_end: type: string format: date-time example: '2023-06-22T17:16:14.179Z' timestamp_start: type: string format: date-time example: '2023-06-21T17:16:14.179Z' '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: message: type: string example: Bad Request '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout /api/v1/external_fetches.json: get: summary: List external fetch templates description: Use this endpoint to get the list of external fetch templates. tags: - External fetch security: - user_api_auth: [] parameters: - name: per_page description: Specify the number of records to be returned per page example: 2 in: query schema: type: string - name: page description: Specify the page number for the search results. example: 2 in: query schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: template: type: array items: type: object properties: name: type: string created_at: type: string format: date-time example: '2023-08-29T01:41:27.000Z' updated_at: type: string format: date-time example: '2023-08-29T05:15:39.000Z' uuid: type: string example: f8220927-20b7-409c-b970-8c17a24e1010 author: type: string example: Jane Doe resource: type: object properties: updated_at: type: string format: date-time '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: message: type: string example: Bad Request '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout post: summary: Create an external fetch template description: Use this endpoint to create an external fetch template. tags: - External fetch security: - user_api_auth: [] requestBody: content: application/json: schema: type: object required: - alias_name - http_method - url properties: alias_name: type: string description: Specify the name of the external fetch template. The alias_name can contain lowercase alphanumeric characters and underscores only. example: fetch_weekly_promotions author: type: string example: john.doe@blueshift.com description: Specify the email address of the author of the template. http_method: type: string description: HTTP method to fetch the data. Set `GET` or `POST` as the method. example: GET enum: - GET - POST auth_header: type: string description: Along with the `auth_token`, specifies the details for secure URLs. example: your_auth_header auth_token: type: string description: Along with the `auth_header`, specifies the details for secure URLs. example: your_auth_token url: type: string description: The external URL. The external fetch URL may include dynamic liquid variables such as user id, email address, product ids, and more. example: https://api.example.com/data body: type: string description: Specify the `JSON` payload if the `http_method` is `POST`. example: user_id: 4981 email: jane.doe@acme.com first_name: Jane last_name: Doe preferences: language: en_US newsletter_subscription: true test_context: type: string description: Specify the test context for the template. example: 'This is a test fetch to update user profile (user: 4981)' description: Specify the details of the external fetch template. responses: '200': description: OK '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: message: type: string example: Bad Request '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout /api/v1/external_fetches/{template_uuid}: put: summary: Update an external fetch template description: Use this endpoint to update an external fetch template. tags: - External fetch security: - user_api_auth: [] parameters: - in: path name: template_uuid description: Specify the UUID of the template that you want to update. You can get the template UUID from the URL when you view a template in the Blueshift app. For example, in `https://app.getblueshift.com/dashboard#/app/external_fetches//edit`, the is the uuid that you need. example: 8da0744e-141d-4c9d-85d7-c89a54ac745a required: true schema: type: string requestBody: content: application/json: schema: type: object properties: alias_name: type: string description: Specify the name of the external fetch template. The alias_name can contain lowercase alphanumeric characters and underscores only. example: fetch_weekly_promotions_jane_doe author: type: string description: Specify the email address of the author of the template. example: john.doe@blueshift.com http_method: type: string description: HTTP method to fetch the data. Set `GET` or `POST` as the method. example: GET enum: - GET - POST auth_header: type: string description: Along with the `auth_token`, specifies the details for secure URLs. example: your_auth_header auth_token: type: string description: Along with the `auth_header`, specifies the details for secure URLs. example: your_auth_token url: type: string description: The external URL. The external fetch URL may include dynamic liquid variables such as user id, email address, product ids, and more. example: https://example.com/api/v2/additional_seat_link?license_key={(user_transaction.license_key)} body: type: string description: Specify the `JSON` payload if the `http_method` is `POST`. test_context: type: string description: Specify the test context for the template. example: user_transaction: license_key: some_value description: Update an external fetch template. responses: '200': description: OK '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: message: type: string example: Bad Request '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout /api/v1/interests/alert: post: tags: - Interest alerts summary: Update or alert customers description: Use this endpoint to send an update to or to alert customers about topics that they have subscribed to. security: - event_api_auth: [] requestBody: content: application/json: schema: type: object required: - event - topic - author - metadata properties: event: type: string description: Specify the name of the event for which the alert is being sent. example: interest_news_alert topic: type: string description: Specify the topic that the alert is for. example: sports author: type: string description: Specify the email address for the author of the alert. example: john.doe@blueshift.com metadata: type: object description: 'Custom attributes providing additional information about the alert. Examples: city, discount, coupon code, match details, product information.' example: live_match_today: true teams: Lakers vs Warriors description: Update customers about a topic that they have subscribed to. responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean description: true or false example: true '400': description: Bad Request - The request was invalid or cannot be otherwise served. An accompanying error message will explain further. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: topic: type: string example: can't be blank '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: Unprocessable Entity - Some/all of the products have invalid data, please check the response for more information on. '429': description: Rate limit exceeded - Too many requests '500': description: "Internal Server Error\t- Please contact blueshift for more information" '502': description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff '503': description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff '504': description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff /api/v1/interests/user_subscriptions: get: tags: - Interest alerts summary: Get customer subscriptions description: Use this endpoint to get all the topics that a customer has subscribed to. security: - event_api_auth: [] parameters: - name: email description: 'Specify the customer''s email address. For example, abc@def.com. You must atleast specify this value, or one of the following fields: uuid, customer_id, phone_number, or device_id.' example: janedoe@acme.com in: query schema: type: string - name: uuid description: The unique identifier for the customer. example: e909605f-3eb3-4e2a-a666-648dedae5b89 in: query schema: type: string - name: customer_id description: Specify the customer ID. example: '812123' in: query schema: type: string - name: phone_number description: Specify the phone number of the customer. Ensure that it includes the country code, starts with a +, follows the E.164 standard, does not start with a 0, and contains 6 to 14 characters. For example, +14155553467. in: query schema: type: string - name: device_id description: Specify the UUID of the device. example: 8abe3faa-d48d-4e4a-00ca-beae01f1c987 in: query schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: topics: type: array items: type: string example: Politics '400': description: Bad Request - The request was invalid or cannot be otherwise served. An accompanying error message will explain further. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: topic: type: string example: can't be blank '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: 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. '422': description: Unprocessable Entity - Some/all of the products have invalid data, please check the response for more information on. '429': description: Rate limit exceeded - Too many requests '500': description: "Internal Server Error\t- Please contact blueshift for more information" '502': description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff '503': description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff '504': description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff /api/v1/live_activity/start: post: summary: Start a Live Activity description: Starts a Live Activity on one or more customers' devices. tags: - Live Activities security: - event_api_auth: [] requestBody: required: true content: application/json: schema: type: object required: - customer_identifier_type - customer_identifiers - activity_attributes_type - activity_attributes - content_state - notification properties: customer_identifier_type: type: string enum: - customer_id - email - phone_number description: Type of identifier used in customer_identifiers. example: email customer_identifiers: type: array items: type: string description: Identifier values. Maximum 50 per call. example: - jane.doe@example.com activity_attributes_type: type: string description: Name of the activity design, matching the name your app registers with registerPushToStart. example: DeliveryActivityAttribute activity_attributes: type: object description: Static attributes that do not change for the life of the activity. Must include `bsftActivityId`, a unique identifier for this activity for this customer. required: - bsftActivityId properties: bsftActivityId: type: string description: Your identifier for this activity. Reuse it to update or end the activity. example: order_4482 additionalProperties: true example: bsftActivityId: order_4482 activityName: 'Order #4482' content_state: type: object description: Dynamic content shown in the activity. The property names must exactly match the ContentState defined in your app. A mismatch is not reported as an error and the device discards the update. additionalProperties: true example: title: Order confirmed subtitle: Preparing your order progress: 0.2 notification: type: object description: Alert shown when the activity starts. properties: title: type: string example: 'Order #4482' body: type: string example: Your order is confirmed stale_date: type: string format: date-time description: ISO 8601 timestamp after which the content is considered out of date. Must be in the future. example: '2026-07-29T18:30:00Z' example: customer_identifier_type: email customer_identifiers: - jane.doe@example.com activity_attributes_type: DeliveryActivityAttribute activity_attributes: bsftActivityId: order_4482 activityName: 'Order #4482' content_state: title: Order confirmed subtitle: Preparing your order progress: 0.2 notification: title: 'Order #4482' body: Your order is confirmed responses: '200': description: OK content: application/json: schema: type: object properties: status: type: string description: Result of the request. example: ok dispatched_to: type: integer description: Number of devices the message was dispatched to. A value of 0 means no device received it; check the errors array. example: 1 errors: type: array description: Per-identifier errors. Empty when every identifier resolved to a device. items: type: object properties: customer_identifier_type: type: string customer_identifier_value: type: string error_message: type: string examples: success: summary: Activity dispatched to the customer's device value: status: ok dispatched_to: 1 errors: [] not_delivered: summary: Request accepted, but no device could be reached value: status: ok dispatched_to: 0 errors: - customer_identifier_type: email customer_identifier_value: jane.doe@example.com error_message: No user found for given identifier '400': description: Bad Request - The request was invalid or cannot be otherwise served. An accompanying error message will explain further. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: detail: type: string example: Missing customer_identifier_type '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: detail: type: string example: No identifiers resolved '413': description: Payload Too Large - Too many customer identifiers in a single call. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: detail: type: string example: You can add maximum 50 customer identifiers in one API call '422': description: Unprocessable Entity - The account is not configured to deliver this request. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: detail: type: string example: No push adapter configured '429': description: Rate limit exceeded - Too many requests '500': description: "Internal Server Error\t- Please contact blueshift for more information" content: application/json: schema: type: object properties: errors: type: array items: type: object properties: detail: type: string example: Delivery failed '502': description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff '503': description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff '504': description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff /api/v1/live_activity/update: post: summary: Update a Live Activity description: Updates the content of a running Live Activity, or ends it. tags: - Live Activities security: - event_api_auth: [] requestBody: required: true content: application/json: schema: type: object required: - customer_identifier_type - customer_identifiers - activity_attributes_type - bsft_activity_id - content_state properties: customer_identifier_type: type: string enum: - customer_id - email - phone_number description: Type of identifier used in customer_identifiers. example: email customer_identifiers: type: array items: type: string description: Identifier values. Maximum 50 per call. example: - jane.doe@example.com activity_attributes_type: type: string description: Name of the activity design, matching the name your app registers with registerPushToStart. example: DeliveryActivityAttribute bsft_activity_id: type: string description: The identifier you set as bsftActivityId when starting the activity. example: order_4482 content_state: type: object description: Updated dynamic content. The property names must exactly match the ContentState defined in your app. additionalProperties: true example: title: Out for delivery subtitle: Arriving by 6:45 PM progress: 0.7 notification: type: object description: Optional alert shown with the update. Omit it to update the activity silently. properties: title: type: string example: 'Order #4482' body: type: string example: Your order is out for delivery end_activity: type: boolean description: Set to true to end the activity. The activity is removed from the Dynamic Island immediately and clears from the Lock Screen shortly after. example: false stale_date: type: string format: date-time description: ISO 8601 timestamp after which the content is considered out of date. example: '2026-07-29T18:30:00Z' dismissal_date: type: string format: date-time description: ISO 8601 timestamp at which the activity is dismissed from the device. example: '2026-07-29T19:00:00Z' example: customer_identifier_type: email customer_identifiers: - jane.doe@example.com activity_attributes_type: DeliveryActivityAttribute bsft_activity_id: order_4482 content_state: title: Out for delivery subtitle: Arriving by 6:45 PM progress: 0.7 responses: '200': description: OK content: application/json: schema: type: object properties: status: type: string description: Result of the request. example: ok dispatched_to: type: integer description: Number of devices the message was dispatched to. A value of 0 means no device received it; check the errors array. example: 1 errors: type: array description: Per-identifier errors. Empty when every identifier resolved to a device. items: type: object properties: customer_identifier_type: type: string customer_identifier_value: type: string error_message: type: string examples: success: summary: Update dispatched to the customer's device value: status: ok dispatched_to: 1 errors: [] not_delivered: summary: Request accepted, but the activity was not found value: status: ok dispatched_to: 0 errors: - customer_identifier_type: email customer_identifier_value: jane.doe@example.com error_message: Running Live Activity not found for any device '400': description: Bad Request - The request was invalid or cannot be otherwise served. An accompanying error message will explain further. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: detail: type: string example: Missing customer_identifier_type '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: detail: type: string example: No identifiers resolved '413': description: Payload Too Large - Too many customer identifiers in a single call. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: detail: type: string example: You can add maximum 50 customer identifiers in one API call '422': description: Unprocessable Entity - The account is not configured to deliver this request. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: detail: type: string example: No push adapter configured '429': description: Rate limit exceeded - Too many requests '500': description: "Internal Server Error\t- Please contact blueshift for more information" content: application/json: schema: type: object properties: errors: type: array items: type: object properties: detail: type: string example: Delivery failed '502': description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff '503': description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff '504': description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff /api/v1/onsite_slots.json: get: summary: List live content slots description: Use this endpoint to get the list of live content slots. tags: - Live content security: - user_api_auth: [] parameters: - name: name description: Search for live content slot that contain the specified string in the name of the slot. Leave blank to get a list of all slots. example: mobile_top_banner in: query schema: type: string - name: slot_format description: Search for live content slots based on their format. This filter is case insensitive, and values can be HTML, JSON, Popup, or Landing Page. Leave blank to get a list of all slots. example: JSON in: query schema: type: string - name: active description: Search for live content slots based on active filter. when 'active' is true, it returns slots linked to campaigns not in 'Completed' or 'Archived' states. when 'active' is false, it return slots those unused by campaigns or associated with campaigns in 'Completed' or 'Archived' states. Leave blank to get a list of all slots. example: true in: query schema: type: boolean responses: '200': description: OK content: application/json: schema: type: array description: The list of live content slots. items: type: object properties: name: type: string description: The name of the live content slot. example: abandon_browse_html format: type: string description: The format of the live content slot. example: HTML uuid: type: string description: The UUID of the live content slot. example: 81878e0675c5c-4baa-b876-f90b0cf62e02 '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: message: type: string example: Bad Request '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout /api/v1/promotions/{promotion_uuid}/add_promocodes: put: summary: Add promo codes to promotion description: Use this endpoint to add promo codes to existing promotion. tags: - Promotions security: - user_api_auth: [] parameters: - in: path name: promotion_uuid required: true description: Specify the UUID of the promotion to which you want to add promo codes. schema: type: string requestBody: content: application/json: schema: type: object properties: promocodes: type: array description: Array of promo codes to overwrite the current list. items: type: string example: - promo_code_1 - promo_code_2 - promo_code_3 required: - promocodes description: Specify the array of the promo codes that you want to add to the promotion. responses: '200': description: OK content: application/json: schema: type: object properties: available_codes: type: integer description: Available codes in promotion for consumption by the campaign. example: 6 total_codes: type: integer description: Total codes present in the promotion including available codes and used codes. example: 10 '400': description: Bad request - The request was invalid or cannot be otherwise served. An accompanying error message will explain further. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found - Can happen due to resource conflicts. Re-try with exponential backoff. Contact us on support@blueshift.com if the issue persists. '409': description: Conflict error, please retry - The request could not be completed due to a conflict with the current state of the target resource, re-try with exponential backoff. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: "Internal Server Error\t- Please contact blueshift for more information." '502': description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff. '503': description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff. '504': description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff. /api/v1/promotions/{promotion_uuid}/overwrite: put: summary: Overwrite promo codes in promotion description: Use this endpoint to replace all existing promo codes in a promotion with a new set of codes. tags: - Promotions security: - user_api_auth: [] parameters: - in: path name: promotion_uuid required: true description: Specify the UUID of the promotion to which you want to add promo codes. schema: type: string requestBody: content: application/json: schema: type: object properties: promocodes: type: array description: List of promo codes to replace the current set. For testing, enter each promo code individually as a string below. For bulk updates, use the Postman collection to submit multiple promo codes as an array, e.g., `["SUMMER2023", "FALL2023", "WINTER2023"]`. items: type: string example: - SUMMER2023 - FALL2023 - WINTER2023 required: - promocodes description: Specify the array of promo codes that will replace the existing codes in the promotion. responses: '200': description: OK content: application/json: schema: type: object properties: available_codes: type: integer description: Available codes in promotion for consumption by the campaign. example: 6 total_codes: type: integer description: Total codes present in the promotion including available codes and used codes. example: 10 '400': description: Bad request - The request was invalid or cannot be otherwise served. An accompanying error message will explain further. '401': description: Unauthorized - Invalid or missing API key. '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found - The specified promotion ID was not found. '409': description: Conflict error, please retry - The request could not be completed due to a conflict with the current state of the target resource, re-try with exponential backoff. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - Please contact support for more information. '502': description: Bad Gateway - Please retry the request. '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. '504': description: Gateway Timeout - The server took too long to respond. Retry with exponential backoff. /api/v1/push_templates.json: get: summary: List push templates description: Use this endpoint to get the list of push templates. tags: - Push template security: - user_api_auth: [] parameters: - name: name description: Search for push templates that contain the specified string in the name of the template. in: query schema: type: string - name: archived description: Search for templates with specified archived status. Value can be `0` to get a list of un-archived templates or `1` to get a list of archived templates. Leave blank to get a list of all templates. in: query schema: type: integer - name: per_page description: Specify the number of records to be returned per page in: query schema: type: string - name: page description: Specify the page number for the search results. in: query schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: template: type: array items: type: object properties: name: type: string created_at: type: string format: date-time example: '2024-10-03T04:57:24.000Z' updated_at: type: string format: date-time uuid: type: string author: type: string resource: type: object properties: updated_at: type: string format: date-time '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: message: type: string example: Bad Request '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout post: summary: Create a push template description: Use this endpoint to create a push template. tags: - Push template security: - user_api_auth: [] requestBody: content: application/json: schema: type: object required: - push_template - template_property properties: push_template: type: object required: - name - content - skip_user_on_external_fetch_error properties: name: type: string description: Specify the name of the template. For example, `My API created template`. example: Summer Rush author: type: string example: john.doe@blueshift.com description: Specify the email address of the author of the template. message_type: type: string description: Only `json` message type is supported. enum: - json example: json default: json device_type: type: string description: Specify the type of device you want to target. For example, `both`, `apple`, or `android`. By default, it's set to both. enum: - apple - android - both example: apple default: both content: type: string description: Specify the `JSON` payload of the notification that is pushed to a user. For example, specify `"{\"GCM\":{\"notification\":{\"title\":\"Notification Content\"}},\"APNS\":{\"aps\":{\"alert\":\"Hello world, now we're cookin!\"}}}"`. Leave the GCM payload empty if you want the push notification to be iOS only. Similarly, leave the APNs payload empty if you want the push notification to be Android only. example: ' Hellooo ' tag_data: type: string description: "Specify a folder and then tags under the folder in the format `folder_name:\ \ tag1, tag2, tag3`. For example, `Regions:USA,China,Brazil,Hong Kong,India,Sweden,Canada`.\n\ \n > **\U0001F4D8** Tag data should exist in your account.\n" example: Regions:NA,EU,APAC,LATAM,GreaterChina skip_user_on_external_fetch_error: type: boolean default: true description: Message is not sent to user if the external fetch encounters an error or does not return any data) example: true template_property: type: object description: Specify the campaign behavior properties for the template. required: - skip_user_on_blank_products - skip_user_on_blank_event_products properties: skip_user_on_blank_products: type: boolean default: true skip_user_on_blank_event_products: type: boolean default: true account_algorithm_uuid: type: string nullable: true description: Specify the recommendation scheme for the template. If you leave this field blank, no change will be done to any recommendation schemes that were previously added to the template. If you send null as a value, any recommendation schemes that were previously added to the template will be removed. external_fetches: type: array description: Specify the external fetches for the template. example: - uuid: e789705f-3eb3-4e2a-a666-648dedae6g86 - uuid: af9bbbd3-7133-4ab4-80a2-938b67c12d34 items: type: object required: - uuid properties: uuid: type: string transaction_mixins: type: array description: Specify the transaction mixins for the template. example: - uuid: transaction_mixin1_uuid - uuid: transaction_mixin2_uuid items: type: object required: - uuid properties: uuid: type: string description: Specify the details of the push template. responses: '200': description: OK '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: message: type: string example: Bad Request '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout /api/v1/push_templates/test_push.json: post: summary: Push a test message description: Use this endpoint to push a test message to users. tags: - Push template security: - user_api_auth: [] requestBody: content: application/json: schema: type: object required: - uuid - personalize_for properties: uuid: type: string description: Specify the UUID of the template. You can the UUID from the URL of the template. For example, if you open the template in the Blueshift app, its URL looks like `https://app.getblueshift.com/dashboard#/app/push_template/studio//edit/info`. example: 9da0744e-141d-4c9d-85d7-c89a54ac745b personalize_for: type: string description: The email address of the user profile for whom you want to personalize the test push message. example: janedoe@acme.com email: type: string description: Specify the email address of the user to whom you want to push the test message. example: janedoe@acme.com responses: '200': description: OK '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: message: type: string example: Bad Request '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout /api/v1/push_templates/{template_uuid}: put: summary: Update a push template description: Use this endpoint to update a push template. tags: - Push template security: - user_api_auth: [] parameters: - in: path name: template_uuid description: Specify the UUID of the template that you want to update. You can get the template UUID from the URL when you view a template in the Blueshift app. For example, in `https://app.getblueshift.com/dashboard#/app/push_template/studio//edit/info`, the is the uuid that you need. example: 9da0744e-141d-4c9d-85d7-c89a54ac745b required: true schema: type: string requestBody: content: application/json: schema: type: object properties: push_template: type: object properties: message_type: type: string description: Only `json` message type is supported. enum: - json default: json device_type: type: string description: Specify the type of device you want to target. enum: - apple - android - both content: type: string description: Specify the `JSON` payload of the notification that is pushed to a user. For example, specify `"{\"GCM\":{\"notification\":{\"title\":\"Notification Content\"}},\"APNS\":{\"aps\":{\"alert\":\"Hello world, now we're cookin!\"}}}"`. Leave the GCM payload empty if you want the push notification to be iOS only. Similarly, leave the APNs payload empty if you want the push notification to be Android only. tag_data: type: string description: 'Specify a folder and then tags under the folder in the format `folder_name: tag1, tag2, tag3`. **📘** Tag data should exist in your account.' example: Regions:NA,EU,APAC,LATAM,GreaterChina skip_user_on_external_fetch_error: type: boolean default: true description: Message is not sent to user if the external fetch encounters an error or does not return any data) example: true template_property: type: object description: Specify the campaign behavior properties for the template. properties: skip_user_on_blank_products: type: boolean default: true example: true skip_user_on_blank_event_products: type: boolean default: true example: true account_algorithm_uuid: type: string nullable: true description: Specify the recommendation scheme for the template. If you leave this field blank, no change will be done to any recommendation schemes that were previously added to the template. If you send null as a value, any recommendation schemes that were previously added to the template will be removed. example: 3879b1a3-ee84-5e13-b63c-ad83674c0ba1 external_fetches: type: array description: Specify the external fetches for the template. If you leave this field blank, any external fetches that were previously added to the template will be removed. items: type: string example: - - - '...' transaction_mixins: type: array description: Specify the transaction mixins for the template. If you leave this field blank, any transaction mixins that were previously added to the template will be removed. example: - uuid: e789705f-3eb3-4e2a-a666-648dedae6g86 - uuid: af9bbbd3-7133-4ab4-80a2-938b67c12d34 items: type: object properties: uuid: type: string description: Update a push template. responses: '200': description: OK '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: message: type: string example: Bad Request '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout /api/v1/segments/list: get: summary: Get list of segments description: Use this endpoint to get the list of segments. tags: - Segments security: - user_api_auth: [] parameters: - name: name description: Search for segments that contain the specified string in the name. in: query schema: type: string - name: archived description: Search for segments with specified archived status. Value can be `0` to get a list of un-archived segments or `1` to get a list of archived segments. Leave blank to get a list of all segments. in: query schema: type: integer - name: per_page description: Specify the number of records to be returned per page in: query schema: type: string - name: page description: Specify the page number for the search results. in: query schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: segments: type: array items: type: object properties: name: type: string example: High value customers uuid: type: string example: e24f90d8-53df-46fd-8014-ff1bfa8774b5 mixin_key: type: integer example: null created_at: type: string format: date-time example: '2024-08-25T06:06:59.412Z' updated_at: type: string format: date-time example: '2021-08-25T06:06:59.412Z' status: type: string approxusers: type: integer description: Approximate number of users in the segment. Includes known as well as anonymous users. email_users: type: integer description: Approximate number of emailable users in the segment. Excludes opted-out users. sms_users: type: integer description: Approximate number of SMS users in the segment. Excludes opted-out users. push_users: type: integer description: Approximate number of Mobile Push enabled users in the segment. Excludes opted-out users. approxusers_updated_at: type: integer version: type: integer '400': description: Bad request - The request was invalid or cannot be otherwise served. An accompanying error message will explain further. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found - Can happen due to resource conflicts. Re-try with exponential backoff. Contact us on support@blueshift.com if the issue persists. '409': description: Conflict error, please retry - The request could not be completed due to a conflict with the current state of the target resource, re-try with exponential backoff. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: "Rate limit exceeded\t- Too many requests. Contact us on support@blueshift.com\ \ for recommended throughput." '500': description: "Internal Server Error\t- Please contact blueshift for more information." '502': description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff. '503': description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff. '504': description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff. /api/v1/segments/{segment_uuid}/matching_users.json: get: summary: Get segment membership counts description: Use this endpoint to get count of users in the segment. tags: - Segments security: - user_api_auth: [] parameters: - name: segment_uuid description: UUID of the segment. in: path required: true schema: type: string - name: refresh description: Trigger job to update segment counts. Counts are updated asynchronously in the background. Use refresh=true to trigger a new count update, and subsequently poll with refresh=false to retrieve updated counts. in: query schema: type: boolean - name: channels description: 'Channels can be one of: ''users'', ''email'', ''push'', ''sms'', or ''inApp''. Parameter indicates which channel audience counts to refresh.' in: query example: email schema: type: string - name: bypass_global description: Set 'true' to return counts bypassing the global inclusion segments. in: query schema: type: boolean responses: '200': description: OK content: application/json: schema: type: object properties: refresh_status: type: string example: refreshing description:

'refreshing'- indicates count calculation job has triggered and awaiting counts to be computed in the background.

'ready' - indicates count calculation job completed and counts have been updated at timestamp indicated in 'approxusers_updated_at'.

approxusers: type: integer example: 45 email_users: type: integer example: 20 sms_users: type: integer push_users: type: integer in_app_users: type: integer approxusers_updated_at: type: string format: date-time example: '2021-08-25T06:06:59.412Z' description: Timestamp when segment counts were last updated. '400': description: Bad request - The request was invalid or cannot be otherwise served. An accompanying error message will explain further. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found - Can happen due to resource conflicts. Re-try with exponential backoff. Contact us on support@blueshift.com if the issue persists. '409': description: Conflict error, please retry - The request could not be completed due to a conflict with the current state of the target resource, re-try with exponential backoff. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: "Rate limit exceeded\t- Too many requests. Contact us on support@blueshift.com\ \ for recommended throughput." '500': description: "Internal Server Error\t- Please contact blueshift for more information." '502': description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff. '503': description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff. '504': description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff. /api/v1/shared_assets.json: get: summary: List shared assets description: 'Retrieve a list of shared assets: HTML, rich text, subject lines, and visual editor content.' tags: - Shared assets security: - user_api_auth: [] parameters: - name: asset_type[] in: query description: 'Filter by one or more asset types. Repeat the parameter for multiple values. Allowed values: `html`, `rich_text`, `visual_editor`, `subject`.' schema: type: array items: type: string enum: - html - rich_text - visual_editor - subject style: form explode: true example: - html - visual_editor - name: display_name in: query description: Returns assets whose display name contains the specified substring. An empty string returns all. schema: type: string example: Banner - name: archived in: query description: Archived status filter. Use `0` for active/unarchived, `1` for archived, or omit to include both. In the response, this field is returned as a boolean (`true`/`false`). schema: type: integer enum: - 0 - 1 examples: active: summary: Active (unarchived) value: 0 archived: summary: Archived value: 1 all: summary: All (omit parameter) value: '' - name: page in: query description: 'Which page of results to fetch. **Zero-based index.** Example: `page=0&per_page=25` returns the first 25 results, `page=1&per_page=25` returns the next 25.' schema: type: integer example: '0' - name: per_page in: query description: The number of results to return per page. schema: type: integer example: 25 responses: '200': description: OK content: application/json: schema: type: array items: type: object properties: id: type: integer description: Unique numeric ID of the asset. example: 24990 uuid: type: string description: Unique UUID of the asset. example: 2c7967ff-5404-481d-83d9-90a11d2fa8e7 asset_type: type: string enum: - html - rich_text - visual_editor - subject description: Type of shared asset. example: subject shareable_name: type: string description: System name used for sharing/reuse. example: footer_template display_name: type: string description: Human-readable display name. example: New subject & preheader archived: type: boolean description: Archived status of the asset. example: false author: type: string description: Author of the asset. example: Content Team email: type: string format: email description: Email address of the author. example: team@example.com templates: type: array description: Templates linked to this asset. items: type: object properties: name: type: string example: Welcome Email uuid: type: string example: 1111aaaa-2222-bbbb-3333-cccc4444dddd resource_type: type: string example: EmailTemplate archived: type: boolean example: false template_count: type: integer example: 0 asset_count: type: integer example: 0 updated_at: type: string format: date-time description: Last update (ISO 8601). example: '2025-06-04T07:23:02.000Z' content: type: string description: Asset content (HTML, rich text, or subject line). example: change me!!! locked_parents: type: array items: type: string lockable_children: type: array items: type: string example: - uuid: a1111111-b222-4ccc-8ddd-eeeeeeee0001 asset_type: html shareable_name: footer_template display_name: Footer Template archived: false author: Content Team email: team@example.com templates: - name: Welcome Email uuid: 1111aaaa-2222-bbbb-3333-cccc4444dddd resource_type: EmailTemplate archived: false template_count: 1 updated_at: '2025-08-22T18:12:47.000Z' content: "\n \n {% for product in recommendations.block1.products\ \ %}\n \n {% endfor\ \ %}\n \n
\n \n \n \n \ \

{{ product.title }}

\n {{ product.extended_attributes.description }}

\n\ \ Buy Now\n
" locked_parents: [] lockable_children: [] - uuid: b2222222-c333-4ddd-8eee-ffffffff0002 asset_type: subject shareable_name: subject_line_offer display_name: Subject Line – Summer Offer archived: false author: Copywriter email: copywriter@example.com templates: [] template_count: 0 updated_at: '2025-08-23T11:20:00.000Z' content: Get 20% off your first order this week! locked_parents: [] lockable_children: [] - uuid: c3333333-d444-4eee-8fff-aaaaaaaa0003 asset_type: visual_editor shareable_name: promo_banner_autumn display_name: Autumn Promo Banner archived: false author: Marketing Team email: marketing@example.com templates: [] template_count: 0 updated_at: '2025-08-25T09:15:00.000Z' content: "" locked_parents: [] lockable_children: [] '400': description: Bad request - The request was invalid or cannot be otherwise served. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found - Can happen due to resource conflicts. Re-try with exponential backoff. '409': description: Conflict error, please retry - The request could not be completed due to a conflict with the current state of the target resource, re-try with exponential backoff. '413': description: Payload too large - The server is refusing to process a request because the request payload is larger than the server is willing or able to process. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Rate limit exceeded - Too many requests. '500': description: Internal Server Error - Please contact Blueshift for more information. '502': description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff. '503': description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff. '504': description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff. post: summary: Create a shared asset description: Use this endpoint to create a shared asset. tags: - Shared assets security: - user_api_auth: [] requestBody: content: application/json: schema: type: object required: - display_name - content - asset_type properties: display_name: type: string description: Human-readable name for the asset. Used to generate the shareable_name if not provided. example: Welcome Email Header content: type: string description: The actual content of the asset. For HTML assets, provide HTML markup. For Subject assets, provide plain text. example:

Welcome to our store!

asset_type: type: string description: Type of asset to create. Must be either 'html' or 'subject'. Cannot be changed after creation. enum: - html - subject example: html plain_text: type: string description: Plain text version of the content. Only applicable for HTML assets. If not provided, Blueshift will auto-generate it. example: Welcome to our store! is_plain_text_custom: type: boolean description: Set to true if providing a custom plain_text version, false to auto-generate. Only applicable for HTML assets. example: true author: type: string description: Email address of the user to attribute as the asset's author. Must be a valid user in the account. If omitted or invalid, defaults to the account's primary user. example: john.doe@example.com examples: html_asset: summary: Create HTML asset value: display_name: Welcome Email Header content:

Welcome to our store!

asset_type: html html_asset_with_plain_text: summary: Create HTML asset with custom plain text value: display_name: Product Announcement content:

New Product Launch

Check out our latest collection.

asset_type: html plain_text: New Product Launch - Check out our latest collection. is_plain_text_custom: true subject_asset: summary: Create Subject asset value: display_name: Welcome Subject Line content: Welcome to our community! asset_type: subject html_asset_with_author: summary: Create HTML asset attributed to an author value: display_name: Welcome Email Header content:

Welcome to our store!

asset_type: html author: john.doe@example.com responses: '200': description: OK content: application/json: schema: type: object properties: uuid: type: string description: Unique identifier for the shared asset. Use this value for updates. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 asset_type: type: string description: Type of the asset. example: html shareable_name: type: string description: 'Auto-generated unique identifier based on display_name. Format: bsft_. Spaces become underscores, special characters are removed.' example: bsft_Welcome_Email_Header display_name: type: string description: Human-readable name for the asset. example: Welcome Email Header author: type: string description: Name of the user who created the asset. example: John Doe email: type: string description: Email of the user who created the asset. example: john.doe@example.com content: type: string description: The actual content of the asset. example:

Welcome to our store!

plain_text: type: string nullable: true description: Plain text version of the content. Null if not provided for HTML assets or not applicable for Subject assets. example: null is_plain_text_custom: type: boolean nullable: true description: Indicates whether plain text is custom (true) or auto-generated (false). Null for Subject assets. example: false updated_at: type: string format: date-time description: Timestamp of when the asset was last updated (ISO 8601 format). example: '2026-01-28T08:00:00.000Z' tag_data: type: string description: Tags associated with the asset. example: Regions:NA,EU,APAC,LATAM,GreaterChina examples: html_asset_response: summary: HTML asset created value: uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890 asset_type: html shareable_name: bsft_Welcome_Email_Header display_name: Welcome Email Header author: John Doe email: john.doe@example.com content:

Welcome to our store!

plain_text: null is_plain_text_custom: false updated_at: '2026-01-28T08:00:00.000Z' tag_data: Regions:NA,EU,APAC,LATAM,GreaterChina subject_asset_response: summary: Subject asset created value: uuid: b2c3d4e5-f6a7-8901-bcde-f12345678901 asset_type: subject shareable_name: bsft_Welcome_Subject_Line display_name: Welcome Subject Line author: John Doe email: john.doe@example.com content: Welcome to our community! plain_text: null is_plain_text_custom: null updated_at: '2026-01-28T08:00:00.000Z' tag_data: Regions:NA,EU,APAC,LATAM,GreaterChina '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: 'HTTP Basic: Access denied.' '422': description: 'Unprocessable Entity - The request was well-formed but contains validation errors. Common causes: missing required fields (display_name, content, asset_type), duplicate shareable_name, or empty values.' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: title: type: string example: shareable_name detail: type: string example: 'Shareable_name: This template name is already in use, please use a different name' meta: type: object properties: combine_errors: type: boolean example: false no_toast: type: boolean example: false unformatted: type: object additionalProperties: type: array items: type: string examples: duplicate_name: summary: Duplicate shareable_name value: errors: - title: shareable_name detail: 'Shareable_name: This template name is already in use, please use a different name' meta: combine_errors: false no_toast: false unformatted: shareable_name: - This template name is already in use, please use a different name blank_field: summary: Missing required field value: errors: - title: shareable_name detail: 'Shareable_name: can''t be blank' meta: combine_errors: false no_toast: false unformatted: shareable_name: - can't be blank '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: status: type: string example: '500' error: type: string example: Internal Server Error /api/v1/shared_assets/{uuid}.json: put: summary: Update a shared asset description: Use this endpoint to update a shared asset. tags: - Shared assets security: - user_api_auth: [] parameters: - in: path required: true name: uuid description: The UUID of the shared asset to update. This value is returned when you create an asset. schema: type: string example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 requestBody: content: application/json: schema: type: object properties: display_name: type: string description: Human-readable name for the asset. Can be updated at any time. example: Updated Welcome Header content: type: string description: The actual content of the asset. For HTML assets, provide HTML markup. For Subject assets, provide plain text. example:

Welcome to our updated store!

plain_text: type: string description: Plain text version of the content. Only applicable for HTML assets. example: Welcome to our updated store! is_plain_text_custom: type: boolean description: Set to true if providing a custom plain_text version, false to auto-generate. Only applicable for HTML assets. example: true examples: update_html_asset: summary: Update HTML asset value: display_name: Updated Welcome Header content:

Welcome to our updated store!

update_html_with_plain_text: summary: Update HTML asset with custom plain text value: display_name: Updated Product Announcement content:

New Product Launch Updated

Check out our latest collection.

plain_text: New Product Launch Updated - Check out our latest collection. is_plain_text_custom: true update_subject_asset: summary: Update Subject asset value: display_name: Updated Welcome Subject content: Welcome to our growing community! responses: '200': description: OK content: application/json: schema: type: object properties: uuid: type: string description: Unique identifier for the shared asset. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 asset_type: type: string description: Type of the asset. Cannot be changed after creation. example: html shareable_name: type: string description: Auto-generated unique identifier. Cannot be changed after creation. example: bsft_Welcome_Email_Header display_name: type: string description: Human-readable name for the asset. example: Updated Welcome Header author: type: string description: Name of the user who last updated the asset. example: John Doe email: type: string description: Email of the user who last updated the asset. example: john.doe@example.com content: type: string description: The actual content of the asset. example:

Welcome to our updated store!

plain_text: type: string nullable: true description: Plain text version of the content. Null if not provided for HTML assets or not applicable for Subject assets. example: null is_plain_text_custom: type: boolean nullable: true description: Indicates whether plain text is custom (true) or auto-generated (false). Null for Subject assets. example: false updated_at: type: string format: date-time description: Timestamp of when the asset was last updated (ISO 8601 format). example: '2026-01-28T09:30:00.000Z' tag_data: type: string description: Tags associated with the asset. example: Regions:NA,EU,APAC,LATAM,GreaterChina examples: html_asset_updated: summary: HTML asset updated value: uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890 asset_type: html shareable_name: bsft_Welcome_Email_Header display_name: Updated Welcome Header author: John Doe email: john.doe@example.com content:

Welcome to our updated store!

plain_text: null is_plain_text_custom: false updated_at: '2026-01-28T09:30:00.000Z' tag_data: Regions:NA,EU,APAC,LATAM,GreaterChina subject_asset_updated: summary: Subject asset updated value: uuid: b2c3d4e5-f6a7-8901-bcde-f12345678901 asset_type: subject shareable_name: bsft_Welcome_Subject_Line display_name: Updated Welcome Subject author: John Doe email: john.doe@example.com content: Welcome to our growing community! plain_text: null is_plain_text_custom: null updated_at: '2026-01-28T09:30:00.000Z' tag_data: NA,EU,APAC,LATAM,GreaterChina '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: 'HTTP Basic: Access denied.' '404': description: Not Found - The specified shared asset UUID does not exist. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: 'Unprocessable Entity - The request was well-formed but contains validation errors. Common causes: duplicate shareable_name or empty values.' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: title: type: string example: shareable_name detail: type: string example: 'Shareable_name: This template name is already in use, please use a different name' meta: type: object properties: combine_errors: type: boolean example: false no_toast: type: boolean example: false unformatted: type: object additionalProperties: type: array items: type: string examples: validation_error: summary: Validation error value: errors: - title: content detail: 'Content: can''t be blank' meta: combine_errors: false no_toast: false unformatted: content: - can't be blank '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: status: type: string example: '500' error: type: string example: Internal Server Error /api/v1/sms_templates.json: get: tags: - SMS template summary: List SMS templates description: Use this endpoint to list all SMS templates. The SMS template has the content that the Blueshift platform uses to create and send text messages to your customers. security: - user_api_auth: [] parameters: - name: resource.message_type description: Search for SMS templates by the message type - sms or mms. example: sms in: query schema: type: string enum: - sms - mms - name: name description: Search for SMS templates that contain the specified string in the name of the template. example: Template SMS test in: query schema: type: string - name: archived description: Search for templates with specified archived status. Value can be `0` to get a list of un-archived templates or `1` to get a list of archived templates. Leave blank to get a list of all templates. example: '1' in: query schema: type: integer - name: per_page description: Specify the number of records to be returned per page example: '5' in: query schema: type: string - name: page description: Specify the page number for the search results. example: '2' in: query schema: type: string responses: '200': description: OK content: application/json: schema: type: array items: type: object description: Properties of the SMS template. properties: name: type: string description: Name of the template example: Template SMS test created_at: type: string format: date-time description: Date and time of the template's creation. example: '2024-10-03T04:57:24.000Z' updated_at: type: string format: date-time description: Date and time when the template got updated. uuid: type: string description: The universally unique identifier of the template. example: bb8e4fd8-12cf-3409-899b-7d2b4ecfc93b archived: type: boolean description: Describes whether the template is archived or not. example: true is_destroy: type: boolean description: Describes whether you can delete the template or not. example: false author: type: string description: The name of the author of the template. example: Jane Doe '400': description: The request was invalid or cannot be otherwise served. An accompanying error message will explain further. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found. This can happen due to resource conflicts. Retry with exponential backoff. If the issue persists, contact Blueshift. '409': description: Conflict error, please retry. The request could not be completed due to a conflict with the current state of the target resource. Re-try with exponential backoff. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Rate limit exceeded. Too many requests. Contact us on support@blueshift.com for recommended throughput. '500': description: Internal server error. Contact Blueshift for more information. '502': description: Service unavailable, please retry. Bad gateway. Retry with exponential backoff. '503': description: Service unavailable, please retry. Service unavailable. Retry with exponential backoff. '504': description: Service unavailable, please retry. Gateway timeout. Retry with exponential backoff. post: tags: - SMS template summary: Create an SMS template description: Use this endpoint to create an SMS template. security: - user_api_auth: [] requestBody: content: application/json: schema: type: object required: - template - template_property properties: template: type: object description: Specify the properties of the template. required: - name - resource - skip_user_on_external_fetch_error properties: name: type: string description: Specify the name of the template. example: John's SMS template author: type: string example: john.doe@blueshift.com description: Specify the email address of the author of the template. For example, `johndoe@blueshift.com`. resource: type: object description: Specify the content of the template. For a message of type MMS, the media URL is a required field. properties: message_type: type: string description: Specify the type of the template. The type can be `sms` or `mms`. example: sms enum: - sms - mms default: sms subject: type: string description: Specify the subject for an MMS template. example: Hey, {{user.firstname}}! content: type: string description: Specify the content of the template. This content is used in the text message that a campaign triggers. This field is required for SMS messages. example: ' Hellooo ' media_url: type: string description: Specify the URL for the media for an MMS message. This field is required for MMS messages. example: https://cdn.getblueshift.com/pictures/114354/content/sample-pic.jpeg shorten_links: type: boolean description: Specify whether we should shorten URLs in a text message. We can track link clicks if you set this value to `true`. example: true default: true tag_data: type: string description: "Specify a folder and then tags under the folder in the format `folder_name:\ \ tag1, tag2, tag3`. For example, `Regions:USA,China,Brazil,Hong Kong,India,Sweden,Canada`.\n\ \n > **\U0001F4D8** Tag data should exist in your account.\n" example: Regions:NA,EU,APAC,LATAM,GreaterChina skip_user_on_external_fetch_error: type: boolean default: true description: Message is not sent to user if the external fetch encounters an error or does not return any data) example: true template_property: type: object description: Specify the campaign behavior properties for the template. required: - skip_user_on_blank_products - skip_user_on_blank_event_products properties: skip_user_on_blank_products: type: boolean default: true skip_user_on_blank_event_products: type: boolean default: true account_algorithm_uuid: type: string nullable: true description: Specify the recommendation scheme for the template. If you leave this field blank, no change will be done to any recommendation schemes that were previously added to the template. If you send null as a value, any recommendation schemes that were previously added to the template will be removed. example: 2879b1a3-ee84-4e13-b63c-ad83674c0ca1 external_fetches: type: array description: Specify the external fetches for the template. example: - uuid: e789705f-3eb3-4e2a-a666-648dedae6g86 - uuid: af9bbbd3-7133-4ab4-80a2-938b67c12d34 items: type: object required: - uuid properties: uuid: type: string transaction_mixins: type: array description: Specify the transaction mixins for the template. example: - uuid: transaction_mixin1_uuid - uuid: transaction_mixin2_uuid items: type: object required: - uuid properties: uuid: type: string description: Takes the template and its details and returns a JSON that provides the UUID of the template. responses: '200': description: OK content: application/json: schema: type: object properties: name: type: string description: Name of the template example: John's SMS template created_at: type: string format: date-time description: Date and time of the template's creation. example: '2024-05-05T20:41:21.000Z' updated_at: type: string format: date-time description: Date and time when the template got updated. example: '2024-05-11T22:04:38.000Z' uuid: type: string description: The universally unique identifier of the template. example: 67b6ad85-461c-403f-b779-64eb4e7d401c archived: type: boolean description: Describes whether the template is archived or not. example: false is_destroy: type: boolean description: Describes whether you can delete the template or not. author: type: string description: The name of the author of the template. '400': description: The request was invalid or cannot be otherwise served. An accompanying error message will explain further. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found. This can happen due to resource conflicts. Retry with exponential backoff. If the issue persists, contact Blueshift. '409': description: Conflict error, please retry. The request could not be completed due to a conflict with the current state of the target resource. Re-try with exponential backoff. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Rate limit exceeded. Too many requests. Contact us on support@blueshift.com for recommended throughput. '500': description: Internal server error. Contact Blueshift for more information. '502': description: Service unavailable, please retry. Bad gateway. Retry with exponential backoff. '503': description: Service unavailable, please retry. Service unavailable. Retry with exponential backoff. '504': description: Service unavailable, please retry. Gateway timeout. Retry with exponential backoff. /api/v1/sms_templates/test_send.json: post: tags: - SMS template summary: Send a test SMS description: Use this endpoint to send a test message. You can use this endpoint to test an SMS template that you create in Blueshift. security: - user_api_auth: [] requestBody: content: application/json: schema: type: object required: - uuid - mobile - personalize_for properties: uuid: type: string description: Specify the UUID of the template that you want to use to send a test SMS message. example: 153e6eaa-cae2-45a3-a59c-f6bed9a38712 mobile: type: string description: Specify the mobile number of the individual who should receive the test SMS message with the country code. For example, if the phone number is `2345678` and the country code is `1`, specify the number as `12345678`. example: '167892453' personalize_for: type: string description: Specify the email address of the customer whose information we should use to customize the SMS message. For example, if you want the message to contain the first name of a specific customer, specify that customer's email address. example: janedoe@acme.com description: Specify the template that you want to choose and the phone number to which you want to send the message. responses: '200': description: OK content: application/json: schema: type: object properties: status: type: string description: Status of the test SMS send operation. example: ok failed: type: object description: Object containing any failed recipients. Empty if all successful. example: {} '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: message: type: string example: Bad Request '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. This includes cases where the personalization user is not found. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: detail: type: string example: Test send failed because personalization user not found. meta: type: object properties: combine_errors: type: boolean example: false no_toast: type: boolean example: false '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout /api/v1/sms_templates/{template_uuid}: put: tags: - SMS template summary: Update an SMS template description: Use this endpoint to update an existing SMS template. security: - user_api_auth: [] parameters: - name: template_uuid description: Specify the UUID of the template that you want to update. You can copy the UUID from the URL of the template on the Blueshift app. For example, if you open a template in the Blueshift app, its URL looks like `https://app.getblueshift.com/dashboard#/app/sms_template//edit`. example: 9da0744e-141d-4c9d-85d7-c89a54ac745b in: path required: true schema: type: string requestBody: content: application/json: schema: type: object required: - template properties: template: type: object description: Specify the properties of the template. required: - resource properties: name: type: string description: Specify a new name for the template. For example, `John's SMS template`. example: Summer Rush resource: type: object description: Specify new content for the template. For a message of type MMS, the media URL is a required field. properties: subject: type: string description: Specify the subject for an MMS template. example: Hey, {{user.firstname}}! content: type: string description: Specify the content of the template. This content is used in the text message that a campaign triggers. This field is required for SMS messages. media_url: type: string description: Specify the URL for the media for an MMS template. This field is required for MMS messages. shorten_links: type: boolean description: Specify whether we should shorten URLs in a text message. We can track link clicks if you set this value to `true`. example: true default: true tag_data: type: string description: 'Specify a folder and then tags under the folder in the format `folder_name: tag1, tag2, tag3`. For example, `Regions:USA,China,Brazil,Hong Kong,India,Sweden,Canada`. **📘** Tag data should exist in your account.' example: Regions:NA,EU,APAC,LATAM,GreaterChina skip_user_on_external_fetch_error: type: boolean default: true description: Message is not sent to user if the external fetch encounters an error or does not return any data) example: true template_property: type: object description: Specify the campaign behavior properties for the template. properties: skip_user_on_blank_products: type: boolean default: true skip_user_on_blank_event_products: type: boolean default: true account_algorithm_uuid: type: string nullable: true description: Specify the recommendation scheme for the template. If you leave this field blank, no change will be done to any recommendation schemes that were previously added to the template. If you send null as a value, any recommendation schemes that were previously added to the template will be removed. example: 2879b1a3-ee84-4e13-b63c-ad83674c0ca1 external_fetches: type: array description: Specify the external fetches for the template. If you leave this field blank, any external fetches that were previously added to the template will be removed. example: - uuid: e789705f-3eb3-4e2a-a666-648dedae6g86 - uuid: af9bbbd3-7133-4ab4-80a2-938b67c12d34 items: type: object properties: uuid: type: string transaction_mixins: type: array description: Specify the transaction mixins for the template. If you leave this field blank, any transaction mixins that were previously added to the template will be removed. example: - uuid: transaction_mixin1_uuid - uuid: transaction_mixin2_uuid items: type: object properties: uuid: type: string description: Specify the values of the properties that you want to update in the template. responses: '200': description: OK content: application/json: schema: type: object properties: name: type: string description: Name of the template example: John's SMS template created_at: type: string format: date-time description: Date and time of the template's creation. example: '2016-08-19T21:53:38.000Z' updated_at: type: string format: date-time description: Date and time when the template got updated. example: '2020-11-19T12:48:13.000Z' uuid: type: string description: The universally unique identifier of the template. example: 41e574b2-72bd-4fad-bc5b-6b0aa0cc04f3 archived: type: boolean description: Describes whether the template is archived or not. example: false author: type: string description: The name of the author of the template. '400': description: The request was invalid or cannot be otherwise served. An accompanying error message will explain further. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found. This can happen due to resource conflicts. Retry with exponential backoff. If the issue persists, contact Blueshift. '409': description: Conflict error, please retry. The request could not be completed due to a conflict with the current state of the target resource. Re-try with exponential backoff. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Rate limit exceeded. Too many requests. Contact us on support@blueshift.com for recommended throughput. '500': description: Internal server error. Contact Blueshift for more information. '502': description: Service unavailable, please retry. Bad gateway. Retry with exponential backoff. '503': description: Service unavailable, please retry. Service unavailable. Retry with exponential backoff. '504': description: Service unavailable, please retry. Gateway timeout. Retry with exponential backoff. /api/v1/subscription_groups: get: tags: - Subscription groups summary: List subscription groups description: Retrieve all subscription groups in your account, including archived ones. security: - user_api_auth: [] responses: '200': description: A list of subscription groups. content: application/json: schema: type: object properties: subscription_groups: type: array items: type: object properties: subscription_group_id: type: string description: type: string nullable: true user_id: type: integer account_id: type: integer uuid: type: string created_at: type: string format: date-time updated_at: type: string format: date-time subscription_group_label: type: string archived: type: boolean author: type: string example: subscription_groups: - subscription_group_id: weekly_updates description: Weekly marketing newsletter user_id: 4821 account_id: 182 uuid: a1b2c3d4-5678-49ab-9cde-0123456789ab created_at: '2025-10-12T08:15:27.000Z' updated_at: '2025-11-03T12:44:10.000Z' subscription_group_label: Weekly Updates archived: false author: Emily Johnson - subscription_group_id: promotions description: Seasonal and promotional campaigns user_id: 5930 account_id: 182 uuid: b2c3d4e5-6789-40fa-8123-abcdef123456 created_at: '2025-09-18T07:52:01.000Z' updated_at: '2025-09-30T09:21:33.000Z' subscription_group_label: Promotions archived: false author: Michael Lee '401': description: Unauthorized - API authentication failed. content: application/json: example: message: Not authorized '404': description: Endpoint not found. content: application/json: example: message: Not Found '429': description: Too Many Requests - Rate limit exceeded. '500': description: Internal Server Error - Unexpected server error. '502': description: Bad Gateway - Invalid response from upstream server. '503': description: Service Unavailable - Temporary outage. '504': description: Gateway Timeout - Server took too long to respond. /api/v1/subscription_groups/index_lite: get: tags: - Subscription groups summary: List subscription groups (lite) description: Retrieve a lightweight list of subscription groups without metadata. security: - user_api_auth: [] responses: '200': description: A lite list of subscription groups. content: application/json: schema: type: object properties: subscription_groups: type: array items: type: object properties: subscription_group_id: type: string uuid: type: string subscription_group_label: type: string example: subscription_groups: - subscription_group_id: weekly_updates uuid: a1b2c3d4-5678-49ab-9cde-0123456789ab subscription_group_label: Weekly Updates - subscription_group_id: promotions uuid: b2c3d4e5-6789-40fa-8123-abcdef123456 subscription_group_label: Promotions '401': description: Unauthorized - API authentication failed. content: application/json: example: message: Not authorized '404': description: Endpoint not found. content: application/json: example: message: Not Found '429': description: Too Many Requests '500': description: Internal Server Error '502': description: Bad Gateway '503': description: Service Unavailable '504': description: Gateway Timeout /api/v1/subscription_groups/{uuid}: get: tags: - Subscription groups summary: Get a subscription group description: Retrieve details of a specific subscription group using its UUID. security: - user_api_auth: [] parameters: - in: path name: uuid required: true schema: type: string description: UUID of the subscription group. You can get the subscription group's UUID from its URL. For example, if you open a subscription group on the Blueshift app, its URL looks like `https://app.getblueshift.com/dashboard#/app/subscription-groups/09de09a9-243f-494e-8f7f-44c610692a74/edit`, where the UUID is `09de09a9-243f-494e-8f7f-44c610692a74`. responses: '200': description: Subscription group details. content: application/json: schema: type: object properties: subscription_group: type: object properties: subscription_group_id: type: string description: type: string nullable: true user_id: type: integer account_id: type: integer uuid: type: string created_at: type: string format: date-time updated_at: type: string format: date-time subscription_group_label: type: string archived: type: boolean author: type: string example: subscription_group: subscription_group_id: weekly_updates description: Weekly marketing newsletter user_id: 4821 account_id: 182 uuid: a1b2c3d4-5678-49ab-9cde-0123456789ab created_at: '2025-10-12T08:15:27.000Z' updated_at: '2025-11-03T12:44:10.000Z' subscription_group_label: Weekly Updates archived: false author: Emily Johnson '401': description: Unauthorized - API authentication failed. content: application/json: example: message: Not authorized '404': description: Subscription group not found. content: application/json: example: message: Not Found '429': description: Too Many Requests '500': description: Internal Server Error '502': description: Bad Gateway '503': description: Service Unavailable '504': description: Gateway Timeout /api/v1/tag_contexts/list: get: tags: - Tags summary: List tags and tag folders description: Use this endpoint to list all the tags and tag folders in your Blueshift account. security: - user_api_auth: [] parameters: - name: resource_type description: 'Filter by resource type (e.g., `Campaign`, `Segment`, `Template:EmailTemplate`, `SharedAsset`, `Syndication`). **Note:** Must exactly match the resource type. Not required when using `resource_uuid` since UUIDs are unique across all resource types.' example: Campaign in: query schema: type: string - name: resource_uuid description: 'Filter tags for a specific resource by its UUID. **No need to specify `resource_type` when using UUID** - UUIDs are unique across all resources. **Finding the UUID:** • Campaign: `https://app.getblueshift.com/dashboard#/app/campaigns//details` • Segment: `https://app.getblueshift.com/dashboard#/app/segments//edit/events` • Template: `https://app.getblueshift.com/dashboard#/app/templates//edit` Returns empty array `[]` if UUID doesn''t exist or has no tags.' example: 311499b0-35b9-4f1a-9f04-aa600078a447 in: query schema: type: string format: uuid responses: '200': description: OK content: application/json: schema: type: array items: type: object properties: id: type: integer description: Specifies the tag folder's ID. example: 180 account_id: type: integer description: Specifies ID of the account under which the tag folder is created. example: 182 name: type: string description: The name of the tag folder. example: Category description: type: string description: Specifies the description of the tag's folder that you provide when you create the tag. example: New users push for the top categories color: type: string description: Specifies the hex-code of the color that you choose for the tag. example: '#76ef4f' allowed_tags: type: string description: Specifies the list of tags that you add in the folder. example: new member top categories push usage_type: type: string description: Type of tag usage (e.g., 'organization' for organizational tags). example: organization tagged_items: type: array description: Lists the entities that have this tag. For example, email templates, shared assets, or segments. items: type: object properties: uuid: type: string description: The UUID of the enitity that has this tag. example: d0d3e2d0-983f-4fb0-8d14-70da314120cd name: type: string description: The name of the entitity that has this tag. example: Black Friday 2024 resource_type: type: string description: The type of the entity. For example, `Template:EmailTemplate`, `Campaign`, `SharedAsset`. example: Campaign tags: type: string description: The list of tags attached to this entity. example: Black Friday 2024:Wishlist '400': description: The request was invalid or cannot be otherwise served. An accompanying error message will explain further. '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Resource not found. This can happen due to resource conflicts. Retry with exponential backoff. If the issue persists, contact Blueshift. '409': description: Conflict error, please retry. The request could not be completed due to a conflict with the current state of the target resource. Re-try with exponential backoff. '413': description: You can upload up to 50 users in an API call. '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Rate limit exceeded. Too many requests. Contact us on support@blueshift.com for recommended throughput. '500': description: Internal server error. Contact Blueshift for more information. '502': description: Service unavailable, please retry. Bad gateway. Retry with exponential backoff. '503': description: Service unavailable, please retry. Service unavailable. Retry with exponential backoff. '504': description: Service unavailable, please retry. Gateway timeout. Retry with exponential backoff. /api/v2/campaigns.json: get: summary: List campaigns description: Use this endpoint to get the list of campaigns. tags: - Campaigns security: - user_api_auth: [] parameters: - name: name description: Search for campaigns that contain the specified string in the name of the campaign. example: Members-only Banner in: query schema: type: string - name: email description: Search for campaigns created by specified author. example: janedoe@acme.com in: query schema: type: string - name: created_after description: Search for campaigns created after specified date and time. example: '2024-05-21T07:05:00.000Z' in: query schema: type: string format: date-time - name: created_before description: Search for campaigns created before specified date and time. example: '2024-05-24T07:05:00.000Z' in: query schema: type: string format: date-time - name: startdate description: Search for campaigns that started after specified date and time. If the start date is not specified, for one time campaigns, response contains only campaigns that have a start date within the last 30 days. For other campaign types, if start date is not specified, all campaigns are returned irrespective of start date. example: '2024-05-22T02:26:00.000Z' in: query schema: type: string format: date-time - name: archived description: Search for campaigns with specified archived status. Set as true for archived campaigns. example: true in: query schema: type: string - name: status description: Search for campaigns with specified status. example: launched in: query schema: type: string - name: exec_term description: Search for campaigns of specified type. Value can be one_time, recurring, on_going (segment triggered), transactional (event triggered), or onsite (live content). example: one_time in: query schema: type: string - name: per_page description: Specify the number of records to be returned per page example: 4 in: query schema: type: string - name: page description: Specify the page number for the search results. example: 3 in: query schema: type: string responses: '200': description: OK content: application/json: schema: type: array items: type: object properties: name: type: string description: The name of the campaign. status: type: string description: 'The current status of the campaign. Possible values: draft, launched, paused, completed.' startdate: type: string format: date-time description: The start date and time at which the campaign starts running. created_at: type: string format: date-time description: The timestamp when the campaign was created. updated_at: type: string format: date-time description: The timestamp when the campaign was last updated. uuid: type: string description: The UUID of the campaign. exec_term: type: string description: 'The campaign type. Possible values: one_time, recurring, on_going, transactional, onsite.' next_execution_scheduled_at: type: string format: date-time nullable: true description: For recurring campaigns, the next scheduled execution time. archived: type: boolean description: Indicates if the campaign is archived. holdout_percentage: type: number description: Specifies the campaign-level holdout percentage. segment_uuid: type: string nullable: true description: The UUID of the associated segment, if any. segment_name: type: string nullable: true description: The name of the associated segment, if any. author: type: string description: The author of the campaign. email: type: string description: Email address of the campaign author. prioritization_label: type: string description: Indicates campaign prioritization override, if any. '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: message: type: string example: Bad Request '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout /api/v2/customer_campaign_activity: get: summary: Get a customer's campaign activity description: Returns a customer's campaign activity (sends, opens, clicks, purchases, revenue) for up to 366 days. tags: - Campaigns security: - user_api_auth: [] parameters: - name: email in: query required: false description: Customer's email. schema: type: string example: jane.doe@example.com - name: customer_id in: query required: false description: Retailer/customer ID. schema: type: string example: cust_91455 - name: phone_number in: query required: false description: Customer's phone number. schema: type: string example: '+14155550172' - name: uuid in: query required: false description: Customer's Blueshift UUID. schema: type: string example: e909605f-3eb3-4e2a-a666-648dedae5b89 - name: start_time in: query required: true description: ISO8601 start of the activity window (inclusive); cannot be more than 366 days in the past. schema: type: string format: date-time example: '2026-07-01T00:00:00Z' - name: end_time in: query required: true description: ISO8601 end of the activity window (exclusive); must be on or after start_time and cannot be in the future. schema: type: string format: date-time example: '2026-07-30T23:59:59Z' - name: cursor in: query required: false description: ISO8601 pagination token from a prior response's cursor field, used to fetch older activity past the 10,000-record cap; must fall within (start_time, end_time]. schema: type: string format: date-time example: '2026-07-15T08:30:00Z' responses: '200': description: OK content: application/json: schema: type: object properties: activities: type: array description: Array of campaign activity records for the customer within the given time window. items: type: object properties: action: type: string description: Type of activity — e.g. sent, delivered, open, click, purchase. campaign_uuid: type: string description: Unique identifier of the campaign. trigger_uuid: type: string description: Unique identifier of the trigger that fired the activity. trigger_timestamp: type: string format: date-time description: ISO8601 timestamp of when the activity occurred. trigger_name: type: string description: Human-readable name of the trigger step. trigger_type: type: string description: Type of trigger, e.g. emailtrigger. campaign_name: type: string description: Human-readable name of the campaign. creative_uuid: type: string description: Unique identifier of the creative/template used. browser_type: type: string description: Browser used by the customer; present only on engagement actions like open or click. browser_platform: type: string description: Operating system of the customer's device; present only on engagement actions. email_domain: type: string description: Domain portion of the customer's email address. extended_attributes: type: object description: Additional metadata about the activity, varies by action type. total: type: integer description: Total number of activity records matching the query. truncated: type: boolean description: True if results were capped at 10,000 records and a cursor should be used to fetch more. date_range: type: object description: Echoes back the start_time and end_time used for the query. properties: start_time: type: string format: date-time end_time: type: string format: date-time examples: with_activity: summary: Customer with campaign activity value: activities: - action: sent campaign_uuid: aa075690-a173-4e1b-bfed-be504f738942 trigger_uuid: 62d05640-c5d8-b63d-938a-659e27369f3c trigger_timestamp: '2026-07-30T12:54:31Z' trigger_name: Send an email trigger_type: emailtrigger campaign_name: Summer Sale — Email Blast creative_uuid: 9340a0c8-cc2c-4c64-b62c-e1ac0476048e email_domain: example.com extended_attributes: bsft_template_version: 26 execution_key: '2026-07-30T12:54:29Z' - action: delivered campaign_uuid: aa075690-a173-4e1b-bfed-be504f738942 trigger_uuid: 62d05640-c5d8-b63d-938a-659e27369f3c trigger_timestamp: '2026-07-30T12:54:37Z' trigger_name: Send an email trigger_type: emailtrigger campaign_name: Summer Sale — Email Blast creative_uuid: 9340a0c8-cc2c-4c64-b62c-e1ac0476048e email_domain: example.com extended_attributes: bsft_template_version: 26 execution_key: '2026-07-30T12:54:29Z' - action: open campaign_uuid: aa075690-a173-4e1b-bfed-be504f738942 trigger_uuid: 62d05640-c5d8-b63d-938a-659e27369f3c trigger_timestamp: '2026-07-30T12:54:38Z' trigger_name: Send an email trigger_type: emailtrigger campaign_name: Summer Sale — Email Blast creative_uuid: 9340a0c8-cc2c-4c64-b62c-e1ac0476048e browser_type: chrome browser_platform: windows email_domain: example.com extended_attributes: bsft_template_version: 26 execution_key: '2026-07-30T12:54:29Z' opened_by: user total: 3 truncated: false date_range: start_time: '2026-07-30T12:00:00Z' end_time: '2026-07-30T13:30:00Z' no_activity: summary: Customer with no activity in the window value: activities: [] total: 0 truncated: false date_range: start_time: '2026-07-01T00:00:00Z' end_time: '2026-07-29T23:59:59Z' '400': description: Bad Request - The request was invalid; see examples for specific validation error messages. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: detail: type: string meta: type: object properties: combine_errors: type: boolean example: false no_toast: type: boolean example: false examples: missing_identifier: summary: No identifier provided value: errors: - detail: Customer identifier required (customer_id, email, phone_number, or uuid) meta: combine_errors: false no_toast: false missing_start_time: summary: Missing start_time value: errors: - detail: start_time is required (ISO8601 format) meta: combine_errors: false no_toast: false start_time_too_old: summary: start_time more than 366 days in the past value: errors: - detail: start_time cannot be more than 366 days in the past meta: combine_errors: false no_toast: false end_time_in_future: summary: end_time in the future value: errors: - detail: end_time cannot be in the future meta: combine_errors: false no_toast: false end_time_before_start_time: summary: end_time before start_time value: errors: - detail: end_time cannot be before start_time meta: combine_errors: false no_toast: false invalid_date_format: summary: Invalid date format value: errors: - detail: start_time must be in ISO8601 format meta: combine_errors: false no_toast: false '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. '404': description: Not Found - The customer specified by the given identifier could not be found. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: detail: type: string meta: type: object properties: combine_errors: type: boolean example: false no_toast: type: boolean example: false examples: customer_not_found: summary: Customer not found value: errors: - detail: User not found meta: combine_errors: false no_toast: false '429': description: Rate limit exceeded - Too many requests '500': description: "Internal Server Error\t- Please contact blueshift for more information" '502': description: Service unavailable, please retry - Bad Gateway, re-try with exponential backoff '503': description: Service unavailable, please retry - Service Unavailable, re-try with exponential backoff '504': description: Service unavailable, please retry - Gateway Timeout, please re-try with exponential backoff /live: post: summary: Live content description: Use this endpoint to insert content recommendations in your website and mobile apps. tags: - Live content security: - event_api_auth: [] requestBody: content: application/json: schema: type: object properties: slot: type: string description: Specify the name of the slot on your website as registered on the Blueshift app. example: Promotions_Homepage_Carousel_JSON api_key: type: string description: Specify the Event API key that you get from the account settings page of the Blueshift app. example: user: type: object properties: customer_id: type: string description: Specify the customer ID of the user. example: '812123' email: type: string description: Specify the email address of the user. example: janedoe@acme.com cookie: type: string description: Specify the user's Blueshift cookie as an identifier for anonymous users. example: 8d74322c-7bb6-44f1-18ce-6a92c5a9672f device_id: type: string description: Specify the UUID of the device. example: 8abe3faa-d48d-4e4a-00ca-beae01f1c987 context: type: object properties: seed_item_ids: type: array description: Specify the IDs of the items that form the basis of replay or related items. items: type: string example: - - - '...' exclude_item_ids: type: array description: Specify the IDs of the items that should be excluded from the response. items: type: string example: - - - '...' exclude_categories: type: array description: Specify the categories that should be excluded from the response. items: type: string example: - category1 - category2 - '...' page_number: type: integer description: Specify this value to get more pages of recommendations if pagination is enabled for your account. example: 2 description: Create a live content campaign and enter the campaign name, select the target segment, flight dates, the slot name and the JSON template responses: '200': description: OK content: application/json: schema: type: object properties: content: type: object properties: products: type: array items: type: object properties: image_url: type: string name: type: string price: type: number sku: type: string url: type: string example: - image_url: https://images.randomhouse.com/cover/9780140437911 name: Saint Joan price: 14 sku: 9780140437911 url: http://www.blueshiftreads.com/products/drama-european-english-irish-scottish-welsh/saint-joan - image_url: https://images.randomhouse.com/cover/9780142410806 name: Free Baseball price: 5.99 sku: 9780142410806 url: http://www.blueshiftreads.com/products/juvenile-fiction-sports-recreation-baseball-softball/free-baseball user: type: object properties: firstname: type: string example: Jane lastname: type: string description: The last name of the customer. example: Doe feedback: type: object properties: errors: type: array items: type: string selected_experiment_uuid: type: string example: 175d4f44-f1f0-438c-ad38-f4ede2047974 selected_trigger_uuid: type: string example: d181abb6-d5d5-4120-8c9b-c0de724576d6 skipped_triggers: type: object properties: d181abb6-d5d5-4120-8c9b-c0de724576d6: type: string example: Active ( launch preview simulation is enabled ) success: type: boolean tracking: type: object properties: click_url: type: string example: http://api.getblueshift.com/track?uid=d1a50376-4f62-46d0-b4a3-36ca0bd2f9cc&eid=175d4f44-f1f0-438c-ad38-f4ede2047974&mid=42a62e43-438a-4cf9-ac1d-a24706fe3065&a=click impression_url: type: string example: http://api.getblueshift.com/track?uid=d1a50376-4f62-46d0-b4a3-36ca0bd2f9cc&eid=175d4f44-f1f0-438c-ad38-f4ede2047974&mid=42a62e43-438a-4cf9-ac1d-a24706fe3065&a=open '400': description: Bad Request - The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data. content: application/json: schema: type: object properties: message: type: string example: Bad Request '401': description: Unauthorized - API authentication failed due to an invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Not authorized '403': description: Forbidden - The API key does not have sufficient permissions to perform this action. content: application/json: schema: type: object properties: message: type: string example: Forbidden '404': description: Not Found - The requested resource was not found. content: application/json: schema: type: object properties: message: type: string example: Not Found '422': description: Unprocessable Entity - The request was well-formed but contains semantic errors. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation failed '429': description: Too Many Requests - The request limit has been exceeded. Reduce request frequency. content: application/json: schema: type: object properties: message: type: string example: Too Many Requests '500': description: Internal Server Error - An unexpected server error occurred. Contact support if the issue persists. content: application/json: schema: type: object properties: message: type: string example: Internal Server Error '502': description: Bad Gateway - The server received an invalid response. Retry the request. content: application/json: schema: type: object properties: message: type: string example: Bad Gateway '503': description: Service Unavailable - The service is temporarily unavailable. Try again later. content: application/json: schema: type: object properties: message: type: string example: Service Unavailable '504': description: Gateway Timeout - The server took too long to respond. Retry the request with exponential backoff. content: application/json: schema: type: object properties: message: type: string example: Gateway Timeout components: securitySchemes: user_api_auth: type: http scheme: basic event_api_auth: type: http scheme: basic