Events
| Field | Value |
|---|---|
| Method | POST |
| Path | /events/{integrationId}/trigger |
| Success | 200 OK |
| Authentication | X-Api-Key with write access |
| Model | Stateless behavioral action |
| Test base URL | https://api-integration.test.kaizenloyalty.com/api/v1 |
See Environments for base URLs and Authentication and security for API keys.
Endpoint
POST /events/{integrationId}/trigger
X-Api-Key: <API_KEY>
Content-Type: application/json
integrationId is a path parameter. The request body does not carry a body-level IntegrationId field.
When to use events
Use an event to send a single consumer action that does not need a shopping lifecycle to the KLP rule engine.
Examples:
- Registration or sign-up
- Login
- Survey completion
- Page or feature interaction
- Product click
- Newsletter subscription
- Money transfer completion
- Mobile application usage
- Business process completion
If the cart changes over time, or the transaction needs finalization, cancellation or a refund, use Sessions instead of events.
Request
{
"Event": {
"SelectedCampaignIds": [],
"EventType": "SurveyCompleted",
"Referral": {
"Code": "REFERRALCODE"
},
"Attributes": {
"SurveyId": "20",
"Channel": "Mobile"
}
},
"ResponseContents": [
"TriggeredCampaigns",
"RuleFailureReasons"
]
}
Minimal request example:
{
"Event": {
"EventType": "kazan",
"Attributes": {
"KazanEventAttribute": 10
}
}
}
Request model
| Field | Type | Required | Description |
|---|---|---|---|
Event | ConsumerEventRequestModel | Yes | Event data |
ResponseContents | enum array | No | Content sections to include in the response |
Event.SelectedCampaignIds | string[]? | No | Filter for the campaigns to evaluate |
Event.EventType | string | Yes | Event API name defined in KLP |
Event.Referral | object | No | Referral context |
Event.Referral.Code | string | If a referral is sent | Referral code |
Event.Attributes | Dictionary<string, object>? | No | Attributes used in rule evaluation |
ResponseContents
Supported enum values:
ConsumerSession
ConsumerProfile
TriggeredCampaigns
RuleFailureReasons
For event requests, TriggeredCampaigns and RuleFailureReasons are usually enough. Verify the actual response envelope for the combinations you use with contract tests.
Event naming standard
- Keep the event API name immutable.
- Keep the display name separate from the API name.
- Use a single casing standard across your organization.
- Do not change the meaning of an existing event; create a new API name for a breaking change.
- Do not put PII in event names.
Recommended examples:
UserRegistered
UserLoggedIn
SurveyCompleted
ProductViewed
MoneyTransferCompleted
Attribute schema governance
Attribute types:
String
Number
Boolean
DateTime
StringArray
NumberArray
DateTimeArray
ConsumerEvent is one of the attribute entity types.
Recommendations:
- Keep the attribute API name immutable.
- Treat a type change as a breaking change.
- Send dates and times in ISO 8601 format.
- Use separate fields for amount and currency in monetary values.
- Do not send Boolean values as strings.
- Do not send unnecessary PII.
- Use nested objects only if you have verified support for them with a contract test.
Example:
{
"Event": {
"EventType": "MoneyTransferCompleted",
"Attributes": {
"Amount": 1200.00,
"Currency": "TRY",
"TransferType": "Domestic",
"IsFirstTransfer": false
}
}
}
Campaign filtering
To evaluate all eligible campaigns:
"SelectedCampaignIds": []
To evaluate specific campaigns:
"SelectedCampaignIds": [
"4JC9YlDLJV30ysAKMbAc5w=="
]
Success response
A successful event returns the rule engine result model (see Effects):
{
"effects": [
{
"campaignId": "g8JYWnwRK6-VB8Ti9LvS1w==",
"rulesetId": "RQC1pkGN7ooGh4AwO9bdXA==",
"ruleId": "b605580f-1c3a-4152-97e4-4fdac8c0bb86",
"ruleName": "Campaign rule",
"ruleIndex": 2,
"id": "09d94a10-8e6f-47a4-a4f1-d20ca8761cae",
"name": "Goal progress",
"actionType": "IncreaseGoalProgress",
"detail": {
"effectTransactionId": "0f1b0901-7052-40c9-bf14-34ba8edfe147",
"increaseGoalProgress": {
"goalId": "WoIl2IoXT_dplrE1KbuPjA==",
"organizationConsumerGoalId": "69931f5e2b5e9e5b5104efea",
"value": 10,
"total": 10,
"target": 100,
"completed": false,
"startDate": "2026-02-16T16:45:02.6436468Z",
"endDate": "2026-03-14T00:00:00"
}
}
}
],
"ruleFailureReasons": []
}
Rule evaluation failure
When a rule condition is not met, the endpoint can still return 200:
{
"effects": [],
"ruleFailureReasons": [
{
"campaignId": "g8JYWnwRK6-VB8Ti9LvS1w==",
"rulesetId": "RQC1pkGN7ooGh4AwO9bdXA==",
"details": [
{
"ruleId": "b605580f-1c3a-4152-97e4-4fdac8c0bb86",
"ruleName": "Campaign rule",
"ruleIndex": 2,
"couponId": null,
"referralId": null,
"type": "Condition",
"index": 1,
"message": ""
}
]
}
]
}
Do not treat HTTP 200 as equivalent to an effect being applied.
RuleFailureReasonType enum
Condition
Effect
Limit
Session
System
Cancel
ruleFailureReasons.details[i].index can carry the condition or item index. couponId and referralId can carry the related code context. For more, see Rule failure reasons in Effects.
Authentication errors
Missing API key
401 Unauthorized
The response body is empty.
Invalid API key
404 Not Found
{
"Code": 3001,
"Message": "Code:3001, Message:Code:3001, Message:Api Key could not be found!"
}
Delivery semantics and idempotency
The API does not define a client-generated event ID or an idempotency header. Your application must therefore manage the following risks:
- After a timeout, it can be unclear whether the event was processed.
- Retrying the same event can create a duplicate reward or duplicate goal progress.
- Send business-critical events through a durable outbox.
- Base your retry policy on the business impact of processing the event again.
- Until KLP supports idempotency, keep a local event delivery ID and a reconciliation record.
Do not add fields that are not part of the contract, such as EventId or OccurredAt, to the request.
Client processing
- Evaluate
effectsandruleFailureReasonstogether. - Deduplicate effects by
effectTransactionId. - Handle unknown
actionTypevalues in a forward-compatible way. - Invalidate goal and wallet caches after an effect.
- Do not log full raw requests and responses, because they can contain PII.
- Manage
EventTypevalues and the attribute schema in a central registry.
Test checklist
- Valid event without attributes
- Typed attributes
- Empty
SelectedCampaignIds - Specific campaign filter
- Referral code event
-
ResponseContentscombinations - Unknown
EventType - Missing
EventType - Invalid attribute type
- No matching campaign /
effects: [] - Condition failure inside HTTP 200
- Duplicate delivery
- Timeout and retry
- Invalid API key / 404 Code 3001
- Missing API key / 401
- Rate limit / 429
- Unknown action type
- SDK
me/trigger - SDK
trigger-encryptedsuccessful decryption -
trigger-encryptedcalled with an API key / 400Private key is missing. -
trigger-encryptedwith corrupted ciphertext / 400Decryption failed.
SDK variants: me/trigger and trigger-encrypted
| Method | Path | Authentication | Description |
|---|---|---|---|
POST | /events/me/trigger | SDK | Triggers an event for the current consumer (JWT) |
POST | /events/{integrationId}/trigger-encrypted | SDK (signed) | Triggers an event with an encrypted payload |
POST | /events/me/trigger-encrypted | SDK (signed) | Triggers an encrypted event for the current consumer |
The request and response models are the same as for /events/{integrationId}/trigger (Event wrapper, rule engine result model).
Encrypted payload
On the trigger-encrypted endpoints, the following fields are sent encrypted:
Event.EventType- Every value in
Event.Attributes(keys stay in plain text; null or empty values are skipped)
The KLP SDK encrypts the payload with the public key it receives in the challenge flow, using RSA-OAEP (SHA-256), and Base64-encodes the result. KLP processes decrypted attribute values as strings.
The native SDKs do this automatically with logEncryptedEvent; your application does not implement the encryption itself. For SDK usage, see iOS SDK and React Native SDK.
{
"Event": {
"SelectedCampaignIds": [],
"EventType": "<base64 RSA-OAEP-SHA256 ciphertext>",
"Attributes": {
"Amount": "<base64 ciphertext>"
}
}
}
Errors
| Case | HTTP | Message |
|---|---|---|
The request is not a signed SDK request (for example, it was called with X-Api-Key) | 400 | Private key is missing. |
| The ciphertext could not be decrypted | 400 | Decryption failed. |
Encrypted triggers are not designed for backend integrations; your backend must use POST /events/{integrationId}/trigger. For the request-signing requirement, see Authentication and security.