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.
Request URI and Header
Request URI - HTTP POST
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).
A Server API request has several types of parameters:
Required Parameters are required in each request.
- Optional parameters include:
Your Kahuna namespace Secret Key.
The Secret Key for the namespace is Available in Settings.
Unable to get Secret Key for your namespace. Please try again later, or contact your Kahuna Customer Success manager.
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.
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
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).
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:
To store the event in your production environment, use
To store the event in your sandbox environment, use
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.
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
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.
|app_bundle_id||A string that identifies the application bundle for an iOS device. For example,
A string that identifies the application that generated the event.
A string that identifies the application version.
The device model name (for example,
A string that identifies the OS in use by the device. For mobile platforms, you can specify
A string that identifies the version of the OS, such as
|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.
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:
If the server returns this response code, the response body contains
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:
A value of
If success is
If success is