Flex API

Flex API

This REST API enables you to trigger a campaign when an external event occurs. For example, you can alert a certain segment of your customers automatically when their favorite items become available or send a message to your customers when a sale they bookmarked goes live.

Use this API from your system to trigger the External Trigger Campaign (created in Kahuna) so that the campaign is sent.

Note: The Flex API is used for External Trigger campaigns only.

API Request

Request URI and Header


To target the production environment:


To target the sandbox environment:


Request Header


Content-Type: application/json

Authorization: The API uses Basic Authentication (BasicAuth), which requires credentials in the form of a username (Secret Key) and password (API Key).

The Secret Key and API Key for the namespace are:

Secret Key: Available in Settings
API Key: Available in Settings


Request Body

The request body is a single JSON dictionary (map) that contains configuration information for the request and a list of external events you want to track for your campaign.

You can submit up to ten requests simultaneously.


Required. The dictionary of key-value pairs that specifies how to access and when to start the campaign.


Required. The identifier (an integer), assigned by Kahuna, for the campaign to which you want to track events. You must use an identifier (ID) for an existing External Trigger campaign.

To find the ID for your campaign
  1. From the left navigation panel of the Kahuna application, open Manage > Campaigns in the left navigation pane.
  2. In the campaign list, click the name of your External Trigger campaign to open the Campaign Details page. The ID appears in a gray box at the top.


The date and time at which the campaign starts. If this field is not specified, the campaign starts immediately. The value must be specified as seconds since the POSIX epoch, 01/01/1970 00:00 GMT. Specify this value in GMT time instead of the time for your local time zone.

The date and time cannot be more than 30 days in the future.



If this field is set to true, and a target user of the campaign is still in the notification cooldown period, the user does not receive another message. If the field is set to false, the campaign sends messages to all users, even if they are still in the cooldown period. The default is set to true.



Indicates if the request you make through this API rate-limits other campaigns. For example, if you set influence_rate_limiting : true and another campaign is scheduled to launch immediately afterwards, that campaign is rate-limited and not sent, because this request counts towards the cooldown for your account. The default is set to true.


Required. A dictionary of key-value pairs that specifies the external events you want to track.

All the parameters for the specified campaign must be present. The parameter values must be the correct type. For example, if you include a parameter that is used as an integer (such as price), the value must be an integer, not a string.

    "campaign_config" : {
        "campaign_id" : 999,
        "k_send_ts" : 1478152800,
        "influence_rate_limiting" : false,
        "observe_rate_limiting" : false
    "parameters": {
        "favorite_hotel" : "hilton",
        "price" : 200

API Response

The response to a campaign request is an HTTP response code. The response is immediate, even if the Kahuna servers are still processing the request.

HTTP Response Codes

The servers use the following HTTP response codes.

200 Kahuna successfully parsed the request.

The servers are unable to parse the request, for one of the following reasons:

  • The HTTP verb specified in the request is not POST.
  • The request does not contain a request body JSON object.
  • The request body contains errors. For example, the value of campaign_id is not an existing campaign. Most errors are related to mistakes in the campaign_config dictionary.

One of the following errors occurred:

  • The HTTP authentication header does not specify BasicAuth.
  • There is a syntax error in the BasicAuth Username (Secret Key) or Password (API Key).
  • The BasicAuth Username is not known, or the Password is invalid for the specified Username.
  • The request URL is missing the env= parameter.
409 The BasicAuth credentials are valid, but the namespace they represent does not have authorization to use this API.
500 The servers encountered an internal error.
Response Body

Error Response Summary


If the request fails, this field is set to false. If the request succeeds, this field is not present.


If an error occurs, a human-readable error message is provided. If no error occurs, this field is not present.


If an error occurs, the HTTP response code is provided. If no error occurs, this field is not present.


If an error occurs, provides details about the error. If no error occurs, this field is not present.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request