Playbooks · Playbook
The plumbing endpoints: string cleaning, list splitting, date formatting, sitemap and meta-tag extraction, lead round-robin, reference-data lookups. Most cost 0.5 or 1 credit, one costs nothing, and all of them bill on any 2xx because none are waterfall endpoints. One page, seventeen curls, because seventeen separate pages would each be thin.
Last updated September 22, 2026
Pattern: These are the calls that sit between the expensive ones. Normalise before you join, split before you loop, resolve filter labels before you search, and extract page data before you decide whether an account is worth 25 credits of phone lookup.
Credit math: The cleaning family is 0.5 credits each: clean_domain, count_occurrences, distribute_leads, encode_uri, format_datetime, normalize_company, normalize_list, remove_whitespace. The web and inference family is 1 credit each: find_redirect, find_sitemap_urls, predict_gender, web_meta_tags, web_json_ld. geo_id_search is 0.01 credits, search_reference_data is 0 credits. Two are per-result: web_sitemap at 1 credit per result and directory_yellowpages at 0.01 credits per result, and neither has a meaningful cost estimate without a stated result count. Every figure here bills on any 2xx.
ROI math: None of these save you money directly. They save money by preventing a 5-credit or 25-credit call from firing against a malformed row. A 0.5-credit normalisation that stops one wasted phone lookup has paid for fifty of itself. Credit tiers on /pricing.
Owned internally by: Whoever is writing the pipeline. These are library functions that happen to live behind HTTP.
Best for: Anyone whose enrichment script is 40% string handling, and anyone whose agent needs a tool rather than a regex.
# All seventeen share the same shape: POST, x-api-key, JSON body.
# Substitute the path and the body from the sections below.
curl -s https://api.richapi.ai/api/v1/normalize_company \
-H "x-api-key: $RICHAPI_KEY" \
-H "content-type: application/json" \
-d '{"company_name": "ACME TECHNOLOGIES, INC.", "normalize_case": true}'
Use the same key and the same base URL as every other endpoint.
There is no separate utilities key, tier or quota.
Check whether you actually need the call.
remove_whitespace and encode_uri have one-line equivalents in every language you might be writing in, and at 0.5 credits a row they are not free. They earn their place inside an agent or a no-code tool that has no string library, not inside a Python script.
Call search_reference_data before you build any search filter.
It costs zero credits and it is the difference between a filter that matches and a filter that silently returns nothing.
Treat every endpoint on this page as billing on any 2xx.
None of them are waterfall endpoints. The miss-free rule covers email_finder, email_verifier and phone_finder only.
For the two per-result endpoints, web_sitemap and directory_yellowpages, set a limit or a page cap on the first call. Per-result pricing plus an unbounded sitemap is how a 1-credit idea becomes a four-figure one.
Read the predict_gender section before using it.
It is on this list because it exists, not because we recommend it.
Every enrichment script is mostly string handling. Split the comma-separated thing, strip the legal suffix, normalise the date, work out whether the URL redirects somewhere else. The expensive calls are five lines; the plumbing around them is two hundred. These seventeen endpoints are that plumbing, exposed over HTTP. One page, because seventeen pages that each said "POST a string, get a cleaner string" would be seventeen pages of nothing. **One rule before the list: none of these are multi-provider waterfall endpoints.** Every one bills on any 2xx, including an empty or useless result. The miss-free behaviour covers `email_finder`, `email_verifier` and `phone_finder` and stops there. See [waterfall email then verify](/use-cases/waterfall-email-then-verify) for what that actually means. They all share the same shape: `POST https://api.richapi.ai/api/v1/{endpoint}`, `x-api-key` header, JSON body.
**`/normalize_company`**: strips legal suffixes, punctuation and stray whitespace from a company name. `normalize_case` defaults to true. Reach for it when you're joining two lists on company name and one of them writes "ACME TECHNOLOGIES, INC." while the other writes "Acme Technologies". ```bash curl -s https://api.richapi.ai/api/v1/normalize_company \ -H "x-api-key: $RICHAPI_KEY" -H "content-type: application/json" \ -d '{"company_name": "ACME TECHNOLOGIES, INC.", "normalize_case": true}' ``` **`/clean_domain`**: a messy URL in, a root domain out. Scheme, `www.`, path and query gone. The dedupe key for a list of scraped URLs. It does **not** chain into company enrichment, and [domain clean then company enrich](/use-cases/domain-clean-then-company-enrich) explains that gap at length. ```bash curl -s https://api.richapi.ai/api/v1/clean_domain \ -H "x-api-key: $RICHAPI_KEY" -H "content-type: application/json" \ -d '{"messy_url": "https://www.Example.COM/pricing?utm_source=x"}' ``` **`/normalize_list`**: splits a delimited string into a clean list, with `remove_empty_values` for the trailing-comma case. Useful when a form field or a CSV cell holds five values and your loop needs five rows. ```bash curl -s https://api.richapi.ai/api/v1/normalize_list \ -H "x-api-key: $RICHAPI_KEY" -H "content-type: application/json" \ -d '{"input": "acme.com, beta.io,, gamma.co,", "remove_empty_values": true}' ``` **`/remove_whitespace`**: strips and collapses whitespace in `input_text`. Honestly: your language does this. It's here for agents and no-code tools with no string library. ```bash curl -s https://api.richapi.ai/api/v1/remove_whitespace \ -H "x-api-key: $RICHAPI_KEY" -H "content-type: application/json" \ -d '{"input_text": " Dana Weiss "}' ``` **`/count_occurrences`**: counts how many times `separator` appears in `input`, with `case_insensitive` and a `limit`. Sanity-checking a delimiter before you split on it, mostly. ```bash curl -s https://api.richapi.ai/api/v1/count_occurrences \ -H "x-api-key: $RICHAPI_KEY" -H "content-type: application/json" \ -d '{"input": "a;b;c;d", "separator": ";", "case_insensitive": false}' ``` **`/encode_uri`**: RFC 3986 encoding of `value`. Same caveat as `remove_whitespace`: a one-liner in code, a genuine tool in a workflow builder. ```bash curl -s https://api.richapi.ai/api/v1/encode_uri \ -H "x-api-key: $RICHAPI_KEY" -H "content-type: application/json" \ -d '{"value": "VP Engineering & Platform"}' ``` **`/format_datetime`**: parses a date string and reformats it, with `original_timezone`, `new_timezone`, `locale` and a strftime `format`. The one in this family that's genuinely annoying to write yourself, because timezone conversion plus localised month names is where date bugs live. ```bash curl -s https://api.richapi.ai/api/v1/format_datetime \ -H "x-api-key: $RICHAPI_KEY" -H "content-type: application/json" \ -d '{"date": "2026-03-04T14:00:00Z", "original_timezone": "UTC", "new_timezone": "America/New_York", "format": "%B %d, %Y %H:%M", "locale": "en"}' ``` **`/distribute_leads`**: round-robins `values_associated_with_labels` across `assignment_labels`, with `current_index` so a later batch picks up where the last one stopped. This is lead routing without a routing product: pass the emails and the rep names, get the assignment. ```bash curl -s https://api.richapi.ai/api/v1/distribute_leads \ -H "x-api-key: $RICHAPI_KEY" -H "content-type: application/json" \ -d '{"values_associated_with_labels": "alice@co.com,bob@co.com,carol@co.com", "assignment_labels": "Rep A,Rep B", "current_index": 0}' ``` Store `current_index` between runs. Without it every batch starts at Rep A and Rep A gets the lion's share.
**`/web_meta_tags`**: OpenGraph, Twitter Card and SEO tags from a URL: title, description, images, favicon. The cheapest way to find out what a company says it does before you spend enrichment credits on it. ```bash curl -s https://api.richapi.ai/api/v1/web_meta_tags \ -H "x-api-key: $RICHAPI_KEY" -H "content-type: application/json" \ -d '{"url": "https://example.com", "cache": true, "cache_bust": false}' ``` **`/web_json_ld`**: Schema.org JSON-LD blocks from a page: products, articles, organisations. Structured data a site has already published about itself, which beats parsing its HTML. ```bash curl -s https://api.richapi.ai/api/v1/web_json_ld \ -H "x-api-key: $RICHAPI_KEY" -H "content-type: application/json" \ -d '{"url": "https://example.com/product/widget", "cache": true}' ``` **`/find_redirect`**: follows `link` through every redirect to the final destination. Unmasking a shortened link, or catching an acquired company whose old domain now points somewhere else. That second case is a real signal. ```bash curl -s https://api.richapi.ai/api/v1/find_redirect \ -H "x-api-key: $RICHAPI_KEY" -H "content-type: application/json" \ -d '{"link": "https://exmpl.co/x7f2"}' ``` **`/find_sitemap_urls`**: discovers a domain's sitemap and filters it by `keywords`, with `exact_match`. "Does this company have a /careers page, a /pricing page, an /integrations page" is a qualification question you can answer for one credit. ```bash curl -s https://api.richapi.ai/api/v1/find_sitemap_urls \ -H "x-api-key: $RICHAPI_KEY" -H "content-type: application/json" \ -d '{"domain": "stripe.com", "keywords": "pricing,careers", "exact_match": false}' ``` **`/web_sitemap`**: every URL from a site's sitemap, via XML, robots.txt or crawl discovery. **Per-result pricing**: 1 credit. `limit` is required and you should treat it as a spending cap, not a convenience. A large site's sitemap is thousands of URLs, and at a credit each that is not a call you make casually. ```bash curl -s https://api.richapi.ai/api/v1/web_sitemap \ -H "x-api-key: $RICHAPI_KEY" -H "content-type: application/json" \ -d '{"url": "https://example.com", "limit": 50, "cache": true}' ``` Use `find_sitemap_urls` when you have a question. Use `web_sitemap` when you need the whole thing and have priced it. **`/directory_yellowpages`**: Yellow Pages business search by `search_query` and `location`, returning name, phone, address, website and categories. **Per-result** at 0.01 credits per result, with `max_pages` and `page`. The local-business route into a list, and the only endpoint on this page that generates rows rather than cleaning them. ```bash curl -s https://api.richapi.ai/api/v1/directory_yellowpages \ -H "x-api-key: $RICHAPI_KEY" -H "content-type: application/json" \ -d '{"search_query": "HVAC contractor", "location": "Austin, TX", "page": 1, "max_pages": 2}' ```
**`/search_reference_data`**: 0 credits. Returns every valid filter label for lead search: seniority levels, industries, functions. No body required. Call it before you write a single filter; a guessed industry string returns an empty result set and no error. ```bash curl -s https://api.richapi.ai/api/v1/search_reference_data \ -H "x-api-key: $RICHAPI_KEY" -H "content-type: application/json" -d '{}' ``` **`/geo_id_search`**: 0.01 credits. Resolves a location name to a LinkedIn Geo ID for profile and lead search filters. ```bash curl -s https://api.richapi.ai/api/v1/geo_id_search \ -H "x-api-key: $RICHAPI_KEY" -H "content-type: application/json" \ -d '{"search": "San Francisco"}' ``` Both feed [people search to email waterfall](/use-cases/people-search-to-email-waterfall), which is where they earn their keep.
It exists. It takes a first `name` and returns a predicted gender. 1 credit. We're not going to sell it to you, because the accuracy limits are structural rather than fixable. Name-to-gender inference works by looking up how a name is usually assigned in some reference population, and that breaks in predictable ways: unisex names (Alex, Sam, Jordan, Andrea) have no right answer; the same name flips gender across languages; transliterated names from non-Latin scripts lose the information that would disambiguate them; and any name outside the reference population's distribution degrades badly. On top of all that, a person's gender is not a property of their first name, so even a perfectly accurate lookup of naming *convention* is still a guess about a person. Which makes it a poor basis for personalisation specifically. The upside of getting it right is a pronoun nobody notices. The downside of getting it wrong is an email that tells the recipient you inferred something about them from a database and got it wrong. That's an asymmetric bet and it's the wrong side of it. Write copy that doesn't need the field. ```bash curl -s https://api.richapi.ai/api/v1/predict_gender \ -H "x-api-key: $RICHAPI_KEY" -H "content-type: application/json" \ -d '{"name": "Dana"}' ``` If you're using it for aggregate analysis rather than per-person messaging (diversity reporting on a list, for instance), the error rate averages out somewhat and the inference is doing less harm. Per person, in an email, don't.
The honest warning about this whole page. `remove_whitespace`, `encode_uri` and `count_occurrences` are one-liners in every programming language. Calling them over HTTP inside a Python loop costs 0.5 credits a row plus a network round trip, to do something `str.strip()` does for free. They belong in an agent's toolbox, or in a no-code builder with no expression language worth using. Inside a script, use your standard library and save the calls for `format_datetime`, `find_sitemap_urls` and the web extractors, which are genuinely doing work you'd rather not write. The other way to burn credits here is an unbounded `web_sitemap` call, which is per-result at a credit each. Set `limit`.
**Do any of these have a free-miss case?** No. All seventeen bill on any 2xx. Only `email_finder`, `email_verifier` and `phone_finder` are waterfall. **Why is `search_reference_data` free?** Because charging you to find out what the valid filter values are would be charging you for our documentation. **`find_sitemap_urls` or `web_sitemap`?** Question versus inventory. The first is flat-rate and filtered; the second is per-result and complete. **Is `directory_yellowpages` US-only?** It searches Yellow Pages, so treat coverage as whatever that directory covers in your target geography. Test before you plan a campaign around it. **Can I use these from MCP?** Yes, all of them, same key and credit pool. [Cursor](/integrations/cursor) and [cursor enrich from csv](/use-cases/cursor-enrich-from-csv) show the agent-side pattern.
[domain clean then company enrich](/use-cases/domain-clean-then-company-enrich) for where `clean_domain` helps and where the chain stops, [people search to email waterfall](/use-cases/people-search-to-email-waterfall) for the search endpoints these feed, [n8n enrich and push hubspot](/use-cases/n8n-enrich-and-push-hubspot) for these calls inside a workflow, /platform for the endpoint catalog, and [use cases](/use-cases) for the rest of the plays. Tiers on [pricing](/pricing). **25 free credits, no card.** That's fifty of the 0.5-credit calls, which is enough to work out which of them you'd actually miss.