How destination waterfalls route a lead

If you sell leads, the question that matters most after a form is submitted is simple: who gets this one? EventsIQ answers it with a waterfall. The lead is offered to your destinations one at a time, in an order you choose, and the first destination that accepts it wins.

A destination is anywhere a lead can be sent. Most often it is the endpoint of a company that pays you per lead, but a CRM or an internal service works the same way.

Routing setups, branches and waterfalls

A routing setup decides what happens to a lead after it arrives. Many forms can point at the same routing setup, so you build it once and change it in one place when a destination's terms change.

Inside a routing setup are branches. Each branch pairs a preset (a saved set of rules about the lead, such as "state is TX or FL and homeowner is yes") with an ordered list of destinations. That ordered list is the waterfall.

Branches are tried from top to bottom, and the first branch whose preset matches the lead is the one that runs. Nothing below it is considered. At the bottom sits a default branch, which runs only when no preset matched.

One detail catches people out. The default branch is not a fallback for a matched branch whose destinations all declined. If you want a Texas lead that nobody in the Texas branch wanted to fall through to your general destinations, add those destinations to the end of the Texas branch's own list.

First acceptance wins

Within a branch, the lead is offered to each destination in list order. The first one whose response passes its accept rule buys the lead. Every destination below the winner is never called.

Take an example. Acme Solar's Texas branch lists three destinations:

1. Installer A
2. Installer B
3. National Partner C

A lead from Houston arrives. Installer A declines. Installer B accepts. The lead is sold to Installer B, and National Partner C never sees it.

You change the order by dragging destinations on the routing canvas.

Accept rules: what counts as a yes

The waterfall depends on reading each destination's answer correctly. That is the job of its accept rule.

An empty accept rule means any 2xx response counts as a sale. That is right for some endpoints and wrong for the many that answer 200 OK with a body that says the lead was rejected. For those, you build a rule from three parts:

• Status codes: which HTTP statuses are considered at all. By default, any 2xx.
• Checks: tests on the response body. Each check is a path, an operator and a value, for example status equals accepted, or price greater than 0. Checks combine with AND or OR.
• Price path: where the payout sits in the response, such as data.price, so the sale is recorded with its value.

EventsIQ reads the response as JSON, then XML, then form-encoded, whichever works, rather than trusting the Content-Type header. The destination editor includes a tester: paste a real response from the destination and it shows the verdict and the result of every check. Use it before you go live, because an accept rule that is too generous marks leads as sold that nobody paid for.

Ping/post: asking before you send

With post delivery the full lead is sent in one call. With ping/post, EventsIQ first sends a ping describing the lead, and sends the full post with contact details only if the ping is accepted. That way a lead's name and phone number go only to the destination that wants it. EventsIQ sends whatever your ping template contains, so keep it to things like state, ZIP code and qualifying answers.

Daily caps

Each destination can have a daily cap, and optionally a separate limit per platform, for example a cap on leads that came from Meta.

When a destination has reached its cap, the waterfall skips it and offers the lead to the next destination. The cap is checked before anything is sent, so a full destination is not pinged and does not cost you a request.

Two details matter:

• The count comes from real sales. Today's usage is counted from the leads that destination actually accepted, so the number the cap enforces is the same number you can see in the logs.
• The day is the destination's day. Each destination can have its own time zone, or follow the account's. A destination in New York has its cap reset at midnight New York time, not midnight UTC.

Caps are not reservations. If two leads arrive at the same instant for a destination with one slot left, both can be sent, so a destination can occasionally go slightly over.

Other reasons a destination is skipped

A destination is also skipped when:

• It is disabled. It keeps its place in every waterfall and is skipped at run time. This is how you pause a destination without rebuilding your routing.
• The lead is missing a field it requires. Rather than send a broken request, EventsIQ skips that destination, logs which field was missing and alerts you.

Each destination also has a timeout, ten seconds by default. Keep it short, because a lead waiting on slow destinations goes cold.

Why every call is logged

Every step of a waterfall writes a row to the logs, including the skips. Open any lead in Activity → Lead Logs and the Waterfall section reads as a complete account of what happened: each destination, in order, with the status, how long it took and the reply. Click a call to see the exact request and response.

That record answers the questions that come up every week: why a lead went unsold, why Installer B got it and not Installer A, and whether the destination really received it. Secret headers are redacted in the logs.

Retrying a call

Any call in the logs can be retried. A retry sends the request exactly as it was first sent, even if you have edited the destination since, and always writes a new log row, so earlier attempts are never overwritten. An accepted retry of a post settles the lead as sold. An accepted retry of a ping does not, because interest is not delivery.

Before you go live

Checks lists anything wrong with the routing setup, such as a branch pointing at a deleted preset or an empty waterfall. Test runs a sample lead through it without sending anything, so you can see which branch it would match.

If you ever need to stop selling without losing leads, pause the routing setup. A paused routing setup still captures and stores every lead, but routes and sells nothing.