Clix Documentation

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

POST

api

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

Parameter	Type	Required	Description
`campaign_id`	string	Yes	The unique identifier of the campaign to trigger

Request Body

Field	Type	Required	Description
`audience`	object	No	Defines the target audience for this campaign trigger
`properties`	map	No	Custom properties to pass to the campaign for personalization

Audience Object

Field	Type	Required	Description
`broadcast`	boolean	No	If `true`, sends to all users matching the campaign’s segment definition. Ignores `targets` if set. Default: `false`
`targets`	array	No	Array 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:

Field	Type	Description
`project_user_id`	string	Target a user by your project’s user ID
`device_id`	string	Target 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:

Filter to users where user_role == "store_staff" AND store_location == "San Francisco"
Send a message with title “New pickup order”
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

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

Show child attributes

properties

object

Custom properties for personalization

Response

Campaign triggered successfully

Response containing the trigger ID

trigger_id

string

Unique identifier for this campaign trigger

Delete User Send Messages

​Overview

​Authentication

​Path Parameters

​Request Body

​Audience Object

​Target Object

​Properties

​Example Requests

​Broadcast to All Eligible Users

​Target Specific Users

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

​Dynamic Filtering and Personalization

​Response

​Success Response (200 OK)

​Error Responses

​400 Bad Request

​401 Unauthorized

​Notes

Authorizations

Path Parameters

Body

Response

Overview

Authentication

Path Parameters

Request Body

Audience Object

Target Object

Properties

Example Requests

Broadcast to All Eligible Users

Target Specific Users

Trigger Without Audience (Uses Campaign’s Default Audience)

Dynamic Filtering and Personalization

Response

Success Response (200 OK)

Error Responses

400 Bad Request

401 Unauthorized

Notes