Skip to main content
POST
/
api
/
v1
/
campaigns
/
{campaign_id}
:trigger
Trigger a campaign
curl --request POST \
  --url https://api.clix.so/api/v1/campaigns/{campaign_id}:trigger \
  --header 'Content-Type: application/json' \
  --header 'X-Clix-API-Key: <api-key>' \
  --header 'X-Clix-Project-ID: <api-key>' \
  --data '
{
  "audience": {
    "broadcast": true,
    "targets": [
      {
        "project_user_id": "<string>",
        "device_id": "<string>"
      }
    ]
  },
  "properties": {}
}
'
{
  "trigger_id": "<string>"
}

​
Overview

Triggers an API-triggered campaign to send messages to a specific audience. This endpoint allows you to send immediate, one-off messages to designated users or broadcast to your entire audience using a pre-configured campaign. For a comprehensive guide on setting up and using API-triggered campaigns, see the API-Triggered Campaigns guide.

​
Authentication

This endpoint requires authentication via the following HTTP headers:
  • X-Clix-Project-ID: Your project ID
  • X-Clix-API-Key: Your Clix Secret API Key

​
Path Parameters

ParameterTypeRequiredDescription
campaign_idstringYesThe unique identifier of the campaign to trigger

​
Request Body

FieldTypeRequiredDescription
audienceobjectNoDefines the target audience for this campaign trigger
propertiesmapNoCustom properties to pass to the campaign for personalization

​
Audience Object

FieldTypeRequiredDescription
broadcastbooleanNoIf true, sends to all users matching the campaign’s segment definition. Ignores targets if set. Default: false
targetsarrayNoArray of specific users/devices to target. Only users matching the campaign’s segment definition will receive the message. Ignored if broadcast is true.

​
Target Object

Each target should specify one of the following:
FieldTypeDescription
project_user_idstringTarget a user by your project’s user ID
device_idstringTarget a specific device by ID

​
Properties

Custom properties are passed as key-value pairs and can be used for:
  • Message personalization: Insert values in message templates using {{ trigger.property_name }}
  • Dynamic audience filtering: Reference values in audience conditions configured in the console
See Personalization for template syntax details. 
{
  "name": "John Doe",
  "age": 40,
  "is_premium_user": true,
  "state": "CA",
  "city": "Mountain View"
}

​
Example Requests

​
Broadcast to All Eligible Users

Send to all users matching the campaign’s segment definition: 
{
  "audience": {
    "broadcast": true
  },
  "properties": {
    "promotion": "Holiday Sale",
    "discount": "30%"
  }
}

​
Target Specific Users

Send to specific users, but only those who match the campaign’s segment definition: 
{
  "audience": {
    "broadcast": false,
    "targets": [
      {
        "project_user_id": "clix_user_a"
      },
      {
        "project_user_id": "clix_user_b"
      }
    ]
  },
  "properties": {
    "subscription_plan": "premium",
    "message_type": "transactional"
  }
}

​
Trigger Without Audience (Uses Campaign’s Default Audience)

{
  "properties": {
    "campaign_variant": "A"
  }
}

​
Dynamic Filtering and Personalization

This example shows how to use properties for both audience filtering and message content. Campaign configuration in console:
  • Audience filter: user_role == "store_staff" AND store_location == {{ trigger.store_location }}
  • Message title: New pickup order
  • Message body: Order #{{ trigger.order_id }} from {{ trigger.customer_name }}. {{ trigger.item_count }} items ready by {{ trigger.pickup_time }}.
API request: 
{
  "audience": {
    "broadcast": true
  },
  "properties": {
    "store_location": "San Francisco",
    "customer_name": "Sarah Johnson",
    "order_id": "ORD-12345",
    "item_count": "3",
    "pickup_time": "2:30 PM"
  }
}
This will:
  1. Filter to users where user_role == "store_staff" AND store_location == "San Francisco"
  2. Send a message with title “New pickup order”
  3. And body “Order #ORD-12345 from Sarah Johnson. 3 items ready by 2:30 PM.”

​
Response

​
Success Response (200 OK)

Returns a trigger identifier for tracking the campaign send: 
{
  "trigger_id": "5dbdd10e-6ea6-4ff7-836d-bd30a6d1a521"
}
The trigger_id can be used to track the status and results of this specific campaign trigger.

​
Error Responses

​
400 Bad Request

Returned when:
  • campaign_id is missing or invalid
  • Request body is malformed
  • Failed to send campaign trigger message
Returns a plain text error message: 
Campaign Id must be provided
or 
Failed to send campaign trigger message

​
401 Unauthorized

Authentication failed or invalid API key.

​
Notes

  • Campaign must be configured as “API-Triggered” in the dashboard before it can be triggered via this endpoint
  • Segment Filtering: All messages are filtered by the campaign’s segment definition:
    • When broadcast is true, the campaign sends to all users who match the campaign’s segment criteria
    • When broadcast is false (or omitted) and targets are specified, only the targeted users who also match the campaign’s segment criteria will receive the message
    • Users who don’t match the segment criteria will not receive messages, even if explicitly targeted
  • When targeting specific users, you can mix different target types (device_id, user_id, project_user_id) in the same request
  • Properties are optional but highly recommended for personalized messaging
  • The trigger_id in the response can be used to track delivery results and campaign analytics
  • Message delivery is asynchronous - the API returns immediately with a trigger_id, and messages are processed in the background
  • Rate limits apply based on your project plan

Authorizations

​
X-Clix-Project-ID
string
header
required

Project ID for authentication

​
X-Clix-API-Key
string
header
required

API Key for authentication

Path Parameters

​
campaign_id
string
required

The unique identifier of the campaign to trigger

Body

application/json

Campaign trigger configuration

Request to trigger a campaign

​
audience
object

Target audience for the campaign

​
properties
object

Custom properties for personalization

Response

Campaign triggered successfully

Response containing the trigger ID

​
trigger_id
string

Unique identifier for this campaign trigger