Nudges endpoint

List nudge events and preview what nudge would fire for a given session state using the elNudge Nudges API.

Base URL: https://api.elnudge.com/v1

All requests require an Authorization: Bearer sk_live_XXXXXXXX header. See Authentication for details.

List nudge events

GET /v1/nudges

Returns a paginated list of nudge events for your site, ordered by shown_at descending.

Query parameters

Parameter	Type	Description
`session_id`	string	Filter to nudge events for a specific session
`type`	string	Filter by nudge type. One of: `chat_bubble`, `toast`, `exit_modal`, `sticky_bar`
`from`	ISO 8601 string	Return events at or after this timestamp
`to`	ISO 8601 string	Return events before this timestamp
`limit`	integer	Number of results (default: 50, max: 200)
`cursor`	string	Pagination cursor from a previous response's `next_cursor`

Example request

curl "https://api.elnudge.com/v1/nudges?type=exit_modal&from=2026-04-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer sk_live_XXXXXXXX"

Example response

{
  "data": [
    {
      "id": "nudg_01HY8QWK9LMNO2PQR3ST4UV5WX",
      "session_id": "sess_01HY8QVZK3MN2PXRT5GW4JCBD",
      "type": "exit_modal",
      "shown_at": "2026-04-29T10:16:30Z",
      "outcome": "clicked",
      "influenced_conversion": true
    },
    {
      "id": "nudg_01HY8QXA1BCDE2FGH3IJ4KL5MN",
      "session_id": "sess_01HY8QV1A2BC3DE4FG5HJ6KL7M",
      "type": "exit_modal",
      "shown_at": "2026-04-29T09:53:41Z",
      "outcome": "dismissed",
      "influenced_conversion": false
    }
  ],
  "next_cursor": "eyJpZCI6Im51ZGdfMDFIWThRWEExQkNERTJGR0gzSUo0S0w1TU4iLCJkaXJlY3Rpb24iOiJiZWZvcmUifQ==",
  "has_more": true
}

Nudge event object fields

Field	Type	Description
`id`	string	Unique nudge event identifier
`session_id`	string	The session this nudge belongs to
`type`	string	`chat_bubble`, `toast`, `exit_modal`, or `sticky_bar`
`shown_at`	string	ISO 8601 UTC — when the nudge was displayed
`outcome`	string	`shown`, `clicked`, `dismissed`, or `chat_opened`
`influenced_conversion`	boolean	`true` if a purchase occurred within 30 min of this nudge interaction

Preview a nudge (for testing)

POST /v1/nudges/preview

Given a hypothetical session state, returns the nudge that would fire — or null if no nudge would fire. Use this endpoint to verify your nudge configuration during integration testing without needing to simulate a real visitor session.

This endpoint works with both sk_live_ and sk_test_ keys.

Request body

{
  "session_state": {
    "intent_score": 75,
    "page_url": "/products/ultra-stride-v2",
    "idle_ms": 35000
  }
}

Field	Type	Description
`intent_score`	integer	Simulated intent score (0–100)
`page_url`	string	The page URL to simulate the nudge on
`idle_ms`	integer	Milliseconds the visitor has been idle on the current page

Example request

curl -X POST "https://api.elnudge.com/v1/nudges/preview" \
  -H "Authorization: Bearer sk_test_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "session_state": {
      "intent_score": 75,
      "page_url": "/products/ultra-stride-v2",
      "idle_ms": 35000
    }
  }'

Example response — nudge would fire

{
  "data": {
    "would_fire": true,
    "nudge": {
      "type": "toast",
      "message": "Still deciding? Here's what makes our Ultra Stride stand out.",
      "cta": "Tell me more",
      "reason": "High intent score on a product page with idle time exceeding threshold"
    }
  }
}

Example response — no nudge would fire

{
  "data": {
    "would_fire": false,
    "nudge": null,
    "reason": "Page URL matches a configured quiet zone"
  }
}

The reason field is informational — useful for debugging why a nudge is or is not firing in a given scenario.