Skip to main content

Events

FieldValue
MethodPOST
Path/events/{integrationId}/trigger
Success200 OK
AuthenticationX-Api-Key with write access
ModelStateless behavioral action
Test base URLhttps://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​

FieldTypeRequiredDescription
EventConsumerEventRequestModelYesEvent data
ResponseContentsenum arrayNoContent sections to include in the response
Event.SelectedCampaignIdsstring[]?NoFilter for the campaigns to evaluate
Event.EventTypestringYesEvent API name defined in KLP
Event.ReferralobjectNoReferral context
Event.Referral.CodestringIf a referral is sentReferral code
Event.AttributesDictionary<string, object>?NoAttributes 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 effects and ruleFailureReasons together.
  • Deduplicate effects by effectTransactionId.
  • Handle unknown actionType values 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 EventType values and the attribute schema in a central registry.

Test checklist​

  • Valid event without attributes
  • Typed attributes
  • Empty SelectedCampaignIds
  • Specific campaign filter
  • Referral code event
  • ResponseContents combinations
  • 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-encrypted successful decryption
  • trigger-encrypted called with an API key / 400 Private key is missing.
  • trigger-encrypted with corrupted ciphertext / 400 Decryption failed.

SDK variants: me/trigger and trigger-encrypted​

Pending verification
MethodPathAuthenticationDescription
POST/events/me/triggerSDKTriggers an event for the current consumer (JWT)
POST/events/{integrationId}/trigger-encryptedSDK (signed)Triggers an event with an encrypted payload
POST/events/me/trigger-encryptedSDK (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​

CaseHTTPMessage
The request is not a signed SDK request (for example, it was called with X-Api-Key)400Private key is missing.
The ciphertext could not be decrypted400Decryption 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.