The events router
The events router is how your own systems hand events to e-satisfaction. Whenever something happens on your side that should trigger feedback — an order ships, a ticket closes, a call ends — your back end sends that event to the router, and e-satisfaction takes it from there: it matches the event against your router conditions, picks the right questionnaire and delivery pipeline, and starts the distribution flow. The result is that a questionnaire goes out at the moment the event happens — right after a sale, a visit or a call.
Think of it as the API-driven sibling of router conditions. The conditions you build in Survey Manager → Router Conditions decide where a response goes; the events router is the doorway that brings events in from outside the platform so those conditions have something to act on.
This is a back-end integration
The events router is meant to be called by your servers, not from a browser or a customer's device. If you're routing responses that already arrive inside e-satisfaction, you don't need the router at all — router conditions handle that on their own.
Why use the events router
e-satisfaction also offers a standard API, but with that approach your development team has to implement the business logic of survey distribution themselves — deciding which questionnaire to send, when, and through which channel.
The events router handles that complexity for you. It collects every event that occurs within your organization at a single endpoint and routes each one based on rules pre-agreed with the e-satisfaction Customer Success team. You implement it once and simply notify the router whenever a new event occurs — a single API call per event.
How it works
Your events are all sent to one endpoint and then routed to the correct touchpoints based on the rules agreed with Customer Success. When an event arrives, the router evaluates it against your router conditions and, on a match, creates the appropriate distribution item — the same kind of entry you'd see in the dispatch queue — for the matching questionnaire and pipeline. That kicks off the invitation just as any other routed response would.
If no router condition matches, you can nominate a default questionnaire and/or pipeline to forward the event to, so nothing falls through the cracks.
Unmatched events are dropped
If an event matches no router condition and you haven't specified a default route, it is discarded. Set a default whenever you want a safety net.
How routing is decided
To send each event to the right questionnaire, the router needs a way to tell touchpoints apart. The usual approach is to agree on a dedicated metadata field whose value flags the touchpoint — for example a touchpoint field carrying a distinct value per touchpoint. Your router conditions then match on that value to pick the questionnaire. You define these flags together with Customer Success when you set up routing.
The endpoint
The router operates at the organization scope — one endpoint receives every event for your organization and routes each one to the right questionnaire.
| Method | POST |
| Endpoint | https://toolkit.e-satisfaction.com/api/organizations/route-item/{organization_id}.json |
Your organization_id is your unique identifier within e-satisfaction. You'll find it on the organization page of the application.
Authentication
The endpoint authenticates with a bearer token, sent on every request in the standard Authorization: Bearer <token> header. To obtain yours:
Create an API token in the platform
From an account with admin access to your workspaces, create an organization API token in the platform — see Security & API keys for how.
Forward it to Customer Success
Send that token to the e-satisfaction Customer Success team. They use it to issue the dedicated bearer token for your events router.
Call the endpoint with the token
Pass the events router token as a bearer token on every request to the endpoint above.
Don't have one yet? You can also request it through support.
The payload
The request body carries the event and the person it relates to. At minimum it must contain the responder_channel_identifier — the phone number or email of the customer who will receive the questionnaire. The rest is metadata that your router conditions can match against.
{
"responder_channel_identifier": "[email protected]",
"metadata": {
"questionnaire": {
"order_id": "A-0001",
"order_date": "2026-01-30"
},
"responder": {
"phone_number": "+30 690 000 0000"
}
},
"locale": "el"
}
responder_channel_identifier(required) — the contact the invitation goes to, an email address or phone number. This is the channel identifier your router conditions can test against (for example, email only vs phone only).metadata.questionnaire— details about the event or transaction itself: the order id, order date, the products of the order, the call details — anything related to the experience.metadata.responder— details about the person who answers: phone number, email, gender — anything related to the customer.locale(optional) — the language the questionnaire is delivered in, including its close and complete buttons. See the supported languages.
Both metadata sections feed the same condition builder you use for router conditions — questionnaire metadata, responder metadata and the questions themselves.
Metadata types
Each metadata field has a type, set when you define it. The available types are:
- text
- number
- date
- boolean
In the response, every value is normalized into the slot for its type (value_text, value_number, value_date or value_boolean), while the value you sent is preserved as original_value.
Metadata must be pre-defined
Any metadata field you send must already exist in e-satisfaction, defined under Data & AI. Fields the platform doesn't recognize are silently discarded, so define your metadata first and use those exact field names in the payload.
Examples & use cases
Post-call feedback for a contact centre
A contact centre wants to survey customers right after a call. The phone system fires one event per completed call to the events router, carrying the call details as questionnaire metadata and the customer as responder metadata. A touchpoint flag of call_center routes the event to the call-centre questionnaire, and locale delivers it in Greek.
Request
{
"responder_channel_identifier": "+30 690 000 0000",
"metadata": {
"questionnaire": {
"touchpoint": "call_center",
"call_date": "2026-01-30",
"call_type": "inbound",
"call_start_time": "2026-01-30T13:45:00+02:00",
"call_duration": "420",
"extension": 1234,
"line": "Customer Support",
"agent": "Agent Example",
"agent_id": "A-0001"
},
"responder": {
"first_name": "Jane",
"last_name": "Doe",
"email": "[email protected]",
"phone_number": "+30 690 000 0000"
}
},
"locale": "el"
}
Response
On success the router returns the queue item(s) it created. Each item shows the questionnaire and pipeline routing chose, its status (a new item starts as Pending), the send_time, and the metadata you sent — normalized into typed slots. Identifiers below are shown as placeholders.
[
{
"item_id": "<generated item id>",
"questionnaire_id": "<questionnaire id>",
"responder_id": "<responder id>",
"responder_channel_identifier": "+30 690 000 0000",
"status_id": 1,
"pipeline_id": "<pipeline id>",
"source": "4",
"locale": "el",
"send_time": "2026-01-30T16:05:54+02:00",
"dispatched_time": null,
"result": null,
"metadata": [
{
"name": "touchpoint",
"value": "call_center",
"value_text": "call_center",
"value_number": null,
"value_date": null,
"value_boolean": null,
"original_value": "call_center"
},
{
"name": "extension",
"value": 1234,
"value_text": null,
"value_number": 1234,
"value_date": null,
"value_boolean": null,
"original_value": "1234"
}
],
"status": {
"status_id": 1,
"title": "Pending"
}
}
]
The metadata array carries one entry per field you sent (trimmed above for brevity). Notice how the text field touchpoint lands in value_text, while the number field extension lands in value_number — that's the metadata typing in action.
Other common use cases
- Post-purchase — fire an event when an order is delivered, with
order_idandorder_dateas questionnaire metadata, to send a satisfaction survey. - After a store visit — fire an event at checkout with the store as a metadata flag, routing to a branch-experience questionnaire.
- Ticket resolved — fire an event when a support ticket closes to trigger a CES survey for that interaction.