Waterfall enrichment sends one lookup to several data providers in a fixed order and stops at the first provider that returns data. Three RichAPI endpoints use a waterfall: Email Finder, Phone Finder, and Email Verifier. A waterfall call that finds nothing returns HTTP 200. Email and phone lookups that find nothing cost nothing.

A waterfall is an ordered list of data providers behind one RichAPI endpoint. RichAPI sends your input to the first provider in the list. If that provider returns data, RichAPI stops and returns that data to you. If that provider returns nothing, RichAPI moves to the next provider. RichAPI repeats this until one provider returns data, or until the list ends. You send one request and you receive one response. RichAPI pays every provider that it calls, and you pay one flat price for the whole call.

No single data provider holds every person. Each provider builds its own dataset, and each dataset covers a different part of the market. A waterfall pools that coverage into one call, so a miss from the first provider is not the end of the lookup. The second provider sees the same input and gets its own chance.

A waterfall also skips a provider whose required input is absent from your request. A request body that holds only a LinkedIn URL skips every provider that needs a name and a company domain. A skip costs no time and no credits.

A few lookup endpoints, for example Find Website by Company Name, also try more than one source. They answer in their own response shape, without the waterfall fields below. A lookup on them that finds nothing returns 404 and costs nothing. Read the endpoint article. Every other endpoint follows the normal billing rule in the next section.

The normal RichAPI rule is that RichAPI bills every 2xx response. A normal endpoint that returns 200 with zero results still costs the endpoint price. Email and phone lookups are the exception to that rule: email and phone lookups that find nothing cost nothing.

Email Finder and Phone Finder bill a 2xx response that holds "success": true. A 2xx response from them that holds "success": false costs 0 credits. For such a miss, RichAPI sets the price of the call to 0 credits and releases the credit reservation that it held for the call. The usage log records the call as Free with 0 credits.

CAUTION: Do not treat a 200 response from a waterfall endpoint as a hit. Read the success field. A 200 response with "success": false holds no data. On Email Finder and Phone Finder it costs 0 credits.

Every waterfall endpoint returns the same response envelope. The fields below appear for a hit and for a miss.

A soft miss and a hard miss both return 200 and both hold "success": false. On Email Finder and Phone Finder, both cost 0 credits. The two differ in cause, and each one needs a different action.

The error field is the reliable signal. A hard miss carries an error field. A soft miss carries no error field.

The example below comes from a Phone Finder call. Phone Finder and Email Verifier label each source by its position: source_1, source_2, and so on.

A soft miss means that the providers looked and found nothing. The record does not exist in any dataset that RichAPI reached. A second identical request returns the same soft miss and can take up to 25 seconds.

A hard miss means that RichAPI never got an answer about your record. The lookup was never completed, so a retry can still return data.

The Provider answered column decides the miss type. If every entry in execution_log answers No, the call is a hard miss. If at least one entry answers Yes, the call is a soft miss.

The Usage & Credits page lives at /home/<workspace-slug>/usage. The Status column shows 200 for a miss, because the request itself was valid.

One credit costs $0.02 on the 1,000 and 5,000 credit packs, and less on larger packs. Email Finder costs 5 credits for a hit and 0 credits for a miss. The example below runs 1,000 Email Finder calls over a list with a 62% hit rate.

A normal per-call endpoint bills all 1,000 responses. At 5 credits per call that is 5,000 credits, or $100.00. The waterfall rule saves 1,900 credits, or $38.00, on this one list.

Your price per found email stays at 5 credits, or $0.10, whatever the hit rate. A lower hit rate lowers the bill and never raises the price of a found record.

The same list costs a different amount at each waterfall endpoint. The table below holds the hit count at 620 and counts the hits only.

The 30 hard misses in the example cost nothing. Send those 30 rows again after a short wait. Each retry that hits costs the endpoint price, and each retry that misses again costs 0 credits.

The provider field and every execution_log entry hold a label, not the internal name of the RichAPI integration. On Email Finder, the label is the short name of the data source. When Email Finder has no short name for a source, the field holds the value provider. On Phone Finder and Email Verifier, the labels are positions: source_1 is the first source tried, source_2 the second, and so on. A position label holds only inside one response, so source_1 in two responses can be two different sources. RichAPI selects the providers, sets their order, and changes that order over time. You cannot choose a provider, and you cannot pin a call to one provider.

A waterfall endpoint returns 200 because the request was valid and RichAPI served it. The success field, and not the HTTP status, reports whether a provider found data. Read success in every waterfall response.

Email and phone lookups that find nothing cost nothing. Email Finder and Phone Finder bill a response that holds "success": true. A response from them with "success": false also holds "billed": false, and RichAPI charges 0 credits for it. This rule is the exception to the normal rule that every 2xx response costs credits.

The answer depends on the miss type. If the response holds an error field, the call was a hard miss and a retry can return data. If the response holds no error field, the call was a soft miss and a retry returns the same empty answer.

No. RichAPI charges one flat price for the whole call, whatever the number of providers tried. The providers_tried field reports how many providers ran, and that number never changes the price.

No. RichAPI sets the provider list and the provider order for each waterfall endpoint. The response reports the winning provider in the provider field and every attempt in execution_log.

Each waterfall call has a total budget of 25 seconds. Each provider inside the call has its own shorter time limit. Set a client timeout of 60 seconds so that a slow call completes instead of a client-side abort.

Email and phone lookups that find nothing cost nothing: Email Finder and Phone Finder charge 0 credits for a call that returns no data. Other endpoints can bill a 2xx response with zero results. Read the endpoint article.

Next: Finding Help and API Documentation