Skip to main content
This API authenticates with Client SDK keys (osk_ prefix). This is the reverse direction from the Data Ingestion API (server to OneSight) — it polls events pushed from the server to the client.

​
Endpoint

GET /v1/persona/{persona_id}/events

​
Overview

The Event Polling API provides a single channel for all push-type information that needs to be delivered from the backend to the client.
  • Zone entry notifications: Alerts when entering specific store sections
  • Promotions: Flash deals, discount information
  • Payment status: Payment requested, processing, completed, or failed

​
Request

​
Query Parameters

ParameterTypeRequiredDescription
zonestringNoCurrent store zone (e.g., wine, meat). If omitted, only zone-independent events are returned

​
Zone Types

ZoneDescription
processed_foodProcessed food
fresh_produceFresh produce
meatMeat counter
wineWine & spirits
bakeryBakery
checkoutCheckout

​
Response

​
Zone Promotion Event

{
  "success": true,
  "data": {
    "events": [
      {
        "event_id": "evt_flash_001",
        "event_type": "zone_promo",
        "expires_at": "2026-04-16T12:00:00Z",
        "blocks": [
          {
            "type": "promo_card",
            "header": "Flash Deal",
            "title": "Processed Food Section",
            "subtitle": "Special Discount on Curry Rice",
            "image_url": "https://cdn.example.com/products/house-curry.jpg",
            "badge": "50% OFF",
            "price": 2450,
            "original_price": 4900,
            "actions": [
              { "id": "claim_coupon", "label": "Claim coupon", "style": "primary" },
              { "id": "dismiss_event", "label": "Maybe later", "style": "text" }
            ]
          }
        ]
      }
    ]
  }
}

​
Zone Entry Notification

{
  "success": true,
  "data": {
    "events": [
      {
        "event_id": "evt_zone_enter_wine_001",
        "event_type": "zone_entered",
        "zone": "wine",
        "expires_at": "2026-04-16T11:00:00Z",
        "blocks": [
          {
            "type": "text",
            "content": "Welcome to the wine section! Shall I help you pick a wine to go with the curry?"
          },
          {
            "type": "suggestion",
            "content": "I can recommend a great value Cabernet Sauvignon.",
            "actions": [
              { "id": "recommend_wine", "label": "Recommend", "style": "primary" },
              { "id": "skip_wine", "label": "No thanks", "style": "secondary" }
            ]
          }
        ]
      }
    ]
  }
}

​
Payment Status Event

{
  "success": true,
  "data": {
    "events": [
      {
        "event_id": "evt_pay_001",
        "event_type": "payment_state",
        "state": "COMPLETED",
        "order_id": "ORD-2026.04.16-A14:23",
        "amount": 42600,
        "blocks": [
          {
            "type": "result_card",
            "status": "success",
            "title": "Payment completed!",
            "message": "Order number ORD-2026.04.16-A14:23"
          }
        ]
      }
    ]
  }
}

​
No Events

{
  "success": true,
  "data": {
    "events": []
  }
}

​
Event Types

TypeDescription
zone_promoZone promotion (Flash Deals, etc.)
zone_enteredZone entry notification
payment_statePayment status change

​
Payment States

StateDescription
REQUESTEDPayment request received
PROCESSINGBeing processed by payment provider
COMPLETEDPayment completed
FAILEDPayment failed

​
Payment Failure Codes

CodeDescription
INSUFFICIENT_BALANCEInsufficient balance or credit limit
CARD_DECLINEDCard declined
TIMEOUTTimed out
USER_CANCELLEDCancelled by user
UNKNOWNUnknown error

​
Block Types

TypeDescription
promo_cardPromotion card (image, price, discount)
textText message
imageImage
product_listProduct listing
suggestionAI recommendation/suggestion
result_cardResult card (success/failure/info)
info_boxInformation box

​
Behavior

  • Events are returned only once (marked as consumed after polling)
  • Events past their expires_at are automatically excluded
  • Use event_id for client-side deduplication
  • Periodic polling is recommended (2-5 second intervals)

​
Code Examples

​
curl

# Poll with zone specified
curl "https://api.ones1ght.com/v1/persona/$PERSONA_ID/events?zone=wine" \
  -H "Authorization: Bearer $SDK_KEY"

# Poll without zone (general events only)
curl "https://api.ones1ght.com/v1/persona/$PERSONA_ID/events" \
  -H "Authorization: Bearer $SDK_KEY"

​
Swift (iOS) — Timer-based Polling

Timer.scheduledTimer(withTimeInterval: 3.0, repeats: true) { _ in
    let url = URL(string: "https://api.ones1ght.com/v1/persona/\(personaId)/events?zone=\(currentZone)")!
    var request = URLRequest(url: url)
    request.setValue("Bearer \(sdkKey)", forHTTPHeaderField: "Authorization")

    URLSession.shared.dataTask(with: request) { data, _, _ in
        guard let data = data,
              let result = try? JSONDecoder().decode(EventsResponse.self, from: data) else { return }

        for event in result.data.events {
            handleEvent(event)  // Update UI
        }
    }.resume()
}