Get a customer's campaign activity

Use this endpoint to retrieve a single customer's campaign activity for a specified time window.

API at a glance

Description: Returns a single customer's campaign activity — sends, opens, clicks, purchases, and revenue — within a specified time window of up to 366 days. Use this to look up activity for a specific customer on demand, instead of processing a full campaign activity export.

Authentication & testing

Testing the API on this page

How to try it here

Use your User API Key as the Username (leave Password blank).
Select the appropriate API endpoint based on your Blueshift region.
Enter the necessary parameters and click Try It to run the request.

Authentication using Base64 encoding

Note for developers

API requests require authentication using HTTP Basic Authentication with an API key.
The API key serves as the username, while the password field should be left empty.
The format to encode is: your_api_key: (note the trailing colon).

This string must be Base64-encoded and included in the request's Authorization header
as follows:

Authorization: Basic encoded_value

Postman collection

Try it with Postman: Explore the API using Blueshift's Postman collection.

Things to know before you start

One customer identifier is required. Supply exactly one of email, customer_id, phone_number, or uuid to identify the customer.
366-day limit. start_time cannot be more than 366 days in the past.
end_time cannot be in the future. The window must end at or before the current time.
10,000-record cap. If a customer's activity in the requested window exceeds 10,000 records, the response is truncated and a cursor value is returned to fetch older activity.
Use case: Look up a specific customer's engagement history — for support, debugging, or personalization — without exporting full campaign activity data.

Request parameters

Check out the request parameters

Parameter	Type	Required	Description
`email`	`string`	One of four identifiers required	Customer's email address.
`customer_id`	`string`	One of four identifiers required	Customer's retailer/account-specific ID.
`phone_number`	`string`	One of four identifiers required	Customer's phone number.
`uuid`	`string`	One of four identifiers required	Customer's Blueshift UUID.
`start_time`	`string` (ISO8601)	✅ Yes	Start of the activity window, inclusive. Cannot be more than 366 days in the past.
`end_time`	`string` (ISO8601)	✅ Yes	End of the activity window, exclusive. Must be on or after `start_time` and cannot be in the future.
`cursor`	`string` (ISO8601)	❌ No	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]`.

> Note: At least one of email, customer_id, phone_number, or uuid is required.

Example requests & responses

Get activity for a customer

GET /api/v2/customer_campaign_activity?email=jane.doe%40example.com&start_time=2026-07-01T00:00:00Z&end_time=2026-07-30T23:59:59Z

{
  "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"
  }
}

Get activity for a customer with no matching activity

GET /api/v2/customer_campaign_activity?email=new.customer%40example.com&start_time=2026-07-01T00:00:00Z&end_time=2026-07-29T23:59:59Z

{
  "activities": [],
  "total": 0,
  "truncated": false,
  "date_range": {
    "start_time": "2026-07-01T00:00:00Z",
    "end_time": "2026-07-29T23:59:59Z"
  }
}

Response fields explained

Check out the response fields

Field	Description
`activities`	Array of campaign activity records for the customer within the given time window.
`action`	Type of activity — e.g. `sent`, `delivered`, `open`, `click`, `purchase`.
`campaign_uuid`	Unique identifier of the campaign.
`trigger_uuid`	Unique identifier of the trigger that fired the activity.
`trigger_timestamp`	ISO8601 timestamp of when the activity occurred.
`trigger_name`	Human-readable name of the trigger step.
`trigger_type`	Type of trigger, e.g. `emailtrigger`.
`campaign_name`	Human-readable name of the campaign.
`creative_uuid`	Unique identifier of the creative or template used.
`browser_type`	Browser used by the customer. Present only on engagement actions like `open` or `click`.
`browser_platform`	Operating system of the customer's device. Present only on engagement actions.
`email_domain`	Domain portion of the customer's email address.
`extended_attributes`	Additional metadata about the activity. Varies by action type.
`total`	Total number of activity records matching the query.
`truncated`	`true` if results were capped at 10,000 records. Use `cursor` to fetch more.
`date_range`	Echoes back the `start_time` and `end_time` used for the query.

Common error scenarios

Common error scenarios you may encounter

All errors share this response shape:

{
  "errors": [
    { "detail": "<message>" }
  ],
  "meta": {
    "combine_errors": false,
    "no_toast": false
  }
}

Status code	Scenario	Example `detail`
400 Bad Request	No customer identifier provided.	`Customer identifier required (customer_id, email, phone_number, or uuid)`
400 Bad Request	`start_time` missing.	`start_time is required (ISO8601 format)`
400 Bad Request	`start_time` more than 366 days in the past.	`start_time cannot be more than 366 days in the past`
400 Bad Request	`end_time` is in the future.	`end_time cannot be in the future`
400 Bad Request	`end_time` is before `start_time`.	`end_time cannot be before start_time`
400 Bad Request	Date not in ISO8601 format.	`start_time must be in ISO8601 format`
404 Not Found	Customer not found.	`User not found`