Server API

Server API

This REST API provides a way for you to send event information to Kahuna servers so that you learn more about your users and so that Kahuna can predict when and how to send communications to your users.

The API sends the following types of information:

  • Events, which contain information about a user or device action, including your own custom events.
  • User attributes, which contain information about a user such as age, gender, geographical region, and so on.
  • Intelligent Events, which are custom events with custom values called properties.

You can send information for a single event or for a batch of events. Sending multiple events in a single request is more efficient and helps the Kahuna servers process the information more quickly.

Server API is not a replacement for the platform-specific SDKs. To send information directly from a mobile or web-based application, use an SDK.

Note: Information is not immediately available after you send a Server API request. If you want to add users to an Adaptive Campaign with the Adaptive Campaign API, wait approximately 60 seconds after sending a Server API request.

API Request

Request URI and Header


Request Header

Content Type: application/x-www-form-urlencoded

Authorization: Server API does not use authentication headers. Instead, Kahuna authenticates each event in your request using the namespace Secret Key you provide (see Required Parameters).

Request Body

Basic Request

A Server API request has several types of parameters:

Required Parameters


Your Kahuna namespace Secret Key.

The Secret Key for the namespace is Available in Settings.


A globally-unique identifier (GUID) for a new or existing device. You can assign your own device ID, especially when testing, but if you are adding events for a device that Kahuna already knows, use the Kahuna device ID.

For example: dev_id=12a217b6ui2


The name of each event you want to record. You can send one event or a batch of events (when you send multiple events in one batch, the API request is more efficient).

The value of this parameter is a JSON array of one or more dictionaries. An event name must contain fewer than 100 characters, must be in lowercase letters, and can use a - (minus sign). For example:



The events parameter can also include the optional field time to specify the date and time of the event. The value of time must be an integer representing the number of seconds since the UNIX epoch. The value must be UTC-relative and not relative to the local time zone. For example,


Note: If you send a batch of events, all the events you specify must be for the same device and (if specified) the same user. You can specify multiple Intelligent Events, and you can combine regular events and Intelligent Events in the same request (see Intelligent Events below).

Intelligent Events

An Intelligent Event is a custom event combined with custom information sent as key-value pairs, also known as properties. Intelligent Events allow you to track user behavior together with information about that behavior, all at a detailed level. For example, you can create an event indicating that a user has watched a movie and include the movie genre, the name of the movie, and the number of times the user has watched the movie in the past.

Each element in the array contains the following fields:

  • event—the name of the event
  • properties—a dictionary of properties. Each property in the properties dictionary has a property name and value. The property name is a string you assign. The property value is an array of strings. Kahuna associates each string with the property name.
  • time—the time of the event (optional).


For example:

events=[{"event":"add_to_cart","time":1450817760,"properties": {"items":["socks","shirt"]}},


To store the event in your production environment, use env=p.

To store the event in your sandbox environment, use env=s.

Optional Parameters

User Credentials


Sends user credentials with an event. The value of this parameter is a JSON dictionary containing the user credential keys and the values you want to add. For example:


You can specify the following credentials.

user_id A globally-unique ID (GUID) that you assign to the user. For example: user_id=THX11389.

A globally-unique user name for the user, for example: username=johnd1989.




The user's email address. The key user_email is a synonym for email. You can use either one.

Because an email address is globally unique, it makes an excellent value for a user credential. However, Kahuna uses the email address to send out email campaign notifications, so make sure your users understand this.

fbid The user's Facebook ID.
twtr The user's Twitter ID
lnk The user's LinkedIn ID
gplus_id The user's Google Plus ID.
install_token The token that you assign to the device when the user installs your app.
mobile_number The user's mobile phone number for SMS messages.
User Attributes

Sends user attributes with an event. The value of this parameter is a JSON dictionary containing the user attribute keys and the values you want to add or update. For example:


User attributes contain descriptive information for the user. Unlike a user credential, a user attribute doesn't have to be globally unique. Also, Kahuna doesn't have an official list of user attributes, so you can create any user attribute you want. A user's gender is an example of a user attribute. Gender is not globally unique, but it is an aspect of users that you can track. To track gender, you can use a gender user attribute key.

Note: Create a reasonable number of important user attributes to track. To ensure you do not have too many attributes, Kahuna reviews the user attributes you create. This review assists you in streamlining your user and campaign data.

Device Parameters

app_bundle_id A string that identifies the application bundle for an iOS device. For example, com.kahuna.KahunaApp.

A string that identifies the application that generated the event.


A string that identifies the application version.


The device model name (for example, iphone 4,2 or galaxy nexus). In iOS, device names have the format iphone major,minor (note the blank between iphone and major and the comma , between the major and minor version numbers). Other devices report a device name set by the manufacturer.


A string that identifies the OS in use by the device. For mobile platforms, you can specify ios, android, iphone, ipad, or ipod. This value is shown in the Devices list in the user mini profile. If the browser name is available, you can specify chrome, safari, or firefox, otherwise specify web. These values are shown in the Web Devices list in the user mini profile.


A string that identifies the version of the OS, such as 3.5.

push_token The push token for the mobile OS that is passed in the os_name parameter.

The following examples show the raw payload for sending an event with device parameters, credentials, and user attributes. Examples for sending a batch of events and intelligent events are also provided.

Send an Event

The following shows the format for sending an event for a given device.




Send Device Parameters with an Event

The following shows the format for sending device parameters with an event.




Send Credentials with an Event

The following shows the format for sending credentials with an event.




Send User Attributes

The following shows the format for sending user attributes with an event.




Send Events in a Batch

The following shows the format for sending a batch of events.




Send Intelligent Events

The following shows the format for sending intelligent events.




API Response

Server API responds to requests with an HTTP response code and a response body in JSON format.

HTTP Response Codes

The server successfully performed the following:

  • Authenticated the request based on the value of the key parameter.
  • Parsed the parameters.
  • Identified a valid user credential. A valid device_id is considered to be a valid credential.

Unsuccessful request:

  • Authentication failed.
  • A parameter is malformed. For example, the time parameter value is not an integer.
  • An internal server error occurred.

If the server returns this response code, the response body contains "success": false and an error message describing the problem.

Response Body

The response body is a JSON dictionary:

  • If your request succeeds, the dictionary contains the results of the request, as well as status information for the user or device associated with the event or events you have sent.
  • If your request fails, the dictionary contains information about the failure.

The important dictionary fields are listed in the following table:


A boolean that indicates the overall success of the request: true if the request was successful, otherwise false.

A value of true means that the server authenticated the request, successfully parsed its parameters, and identified a valid user credential. Events are processed asynchronously, so errors might occur after the server receives the request and responds.


If success is false, this field contains a message that describes the error.

If success is true, this field is not present.

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