Waterfall Enrichment

Synchronous, single-record endpoints that query multiple data sources in sequence and return the first confident match. One call, one result, pay for success.

Waterfall endpoints are designed to give you the highest possible match rate without forcing you to integrate, monitor, or load-balance a rotating portfolio of data vendors. You send one request. We route it through a sequenced chain of complementary sources. You get back a single, normalized response with a success flag.

All waterfall endpoints are synchronous — no polling, no webhooks. Most complete in 1–3 seconds and are capped at 25 seconds total.

Billing Model

Waterfall calls use a three-tier pricing rule:

Outcome	`success`	`billed`	Credits charged
Hit	`true`	`true`	Full success rate
Soft fail	`false`	`true`	Reduced rate
Hard fail	`false`	`false`	0 — not billed

Hit — a source confidently returned data.
Soft fail — sources responded but none had data for this lookup. You were billed at the reduced "on-all-fail" rate because the sources did the work.
Hard fail — every source was temporarily unreachable (5xx, timeout, rate-limited, or the circuit breaker is tripped). You were not billed. Safe to retry after a short backoff.

Always inspect the success and billed fields — don't rely on HTTP status alone. HTTP 200 is returned for all three outcomes.

Response Envelope

Every waterfall endpoint returns the same shape:

{
  "success": true,
  "result": { /* endpoint-specific fields */ },
  "providers_tried": 2,
  "execution_log": [
    { "source": "A", "status": "no_data", "latency_ms": 612 },
    { "source": "B", "status": "success", "latency_ms": 834 }
  ]
}

On failure:

{
  "success": false,
  "billed": false,
  "error": "All sources in this waterfall were temporarily unavailable. Safe to retry.",
  "providers_tried": 3,
  "execution_log": [ /* ... */ ]
}

The execution_log lists opaque source identifiers (A, B, C, …) so you can see how many sources were tried and the latency of each — without exposing the underlying vendor identities. This is intentional.

curl -X POST https://v3-api.texau.com/api/v1/email_finder \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Doe",
    "full_name": "Jane Doe",
    "domain": "acme.com",
    "linkedin_url": "https://www.linkedin.com/in/janedoe"
  }'

Parameters

Field	Type	Required	Description
`first_name`	string	Cond.	First name (send with `last_name` + `domain`)
`last_name`	string	Cond.	Last name (send with `first_name` + `domain`)
`full_name`	string	Cond.	Full name (alternative to first/last)
`domain`	string	Cond.	Company domain (e.g. `acme.com`)
`linkedin_url`	string	Cond.	LinkedIn profile URL (standalone — works with no name/domain)

At least one valid input shape is required:

first_name + last_name + domain
full_name + domain
linkedin_url

Response

{
  "success": true,
  "result": {
    "email": "[email protected]",
    "email_status": "valid",
    "score": 98
  },
  "providers_tried": 1,
  "execution_log": [
    { "source": "A", "status": "success", "latency_ms": 742 }
  ]
}

Phone Finder

Find a mobile phone number.

Endpoint: POST /phone_finder Credits: 10 on hit · 1 on soft fail · 0 on hard fail

Request

curl -X POST https://v3-api.texau.com/api/v1/phone_finder \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "linkedin_url": "https://www.linkedin.com/in/janedoe"
  }'

Parameters

Field	Type	Required	Description
`linkedin_url`	string	Cond.	LinkedIn profile URL
`email`	string	Cond.	Email address (alternative pathway)

Response

{
  "success": true,
  "result": {
    "phone": "+14155550123",
    "international_format": "+1 415-555-0123",
    "national_format": "(415) 555-0123",
    "country_code": "US"
  },
  "providers_tried": 1
}

Email Verifier

Verify whether an email address is deliverable.

Endpoint: POST /email_verifier Credits: 1 on hit · 0.5 on soft fail · 0 on hard fail

Request

curl -X POST https://v3-api.texau.com/api/v1/email_verifier \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

Response

{
  "success": true,
  "result": {
    "email": "[email protected]",
    "status": "valid",
    "score": 95,
    "disposable": false,
    "webmail": false,
    "mx_records": true,
    "smtp_check": true,
    "accept_all": false
  },
  "providers_tried": 1
}

Status values

Status	Meaning
`valid`	Mailbox exists and is deliverable
`invalid`	Mailbox does not exist or domain is invalid
`accept_all`	Domain is catch-all — we can't confirm the individual address
`unknown`	Could not determine deliverability

Person Enricher

Enrich a person from their email.

Endpoint: POST /person_enricher Credits: 2 on hit · 1 on soft fail · 0 on hard fail

Request

curl -X POST https://v3-api.texau.com/api/v1/person_enricher \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

Response

{
  "success": true,
  "result": {
    "full_name": "Jane Doe",
    "first_name": "Jane",
    "last_name": "Doe",
    "job_title": "VP of Sales",
    "company_name": "Acme Corp",
    "company_domain": "acme.com",
    "company_linkedin_url": "https://linkedin.com/company/acme",
    "linkedin_url": "https://linkedin.com/in/janedoe",
    "twitter_url": "https://twitter.com/janedoe",
    "industry": "Software",
    "location_country": "United States",
    "phone": "+14155550123",
    "work_email": "[email protected]"
  },
  "providers_tried": 1
}

Fields marked as optional may or may not appear depending on which source produced the match.

Company Enricher

Enrich a company from its domain.

Endpoint: POST /company_enricher Credits: 2 on hit · 1 on soft fail · 0 on hard fail

Request

curl -X POST https://v3-api.texau.com/api/v1/company_enricher \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "acme.com"
  }'

Response

{
  "success": true,
  "result": {
    "name": "Acme Corp",
    "domain": "acme.com",
    "description": "Acme builds SaaS for logistics ops teams.",
    "industry": "Software",
    "employee_count": 150,
    "revenue_range": "$10M-$50M",
    "founded_year": 2018,
    "hq_location": "San Francisco, CA",
    "linkedin_url": "https://linkedin.com/company/acme"
  },
  "providers_tried": 1
}

Retry Strategy

Condition	Recommended action
`success: true`	Use the result
`success: false, billed: true`	Treat as "no data" — do not retry the same input
`success: false, billed: false`	Retry once after 5–30 s — this was a transient outage

Best Practices

Send everything you have. The engine uses input richness to pick the best source. Sending first_name + last_name + domain + linkedin_url is always better than any single field.
Pair email_finder with email_verifier. The email_finder score is probabilistic; verify before cold outreach.
Use person_enricher downstream of email_finder. Once you have an email, the person enricher can backfill title, company, socials, and location — all from that one identifier.
Chain with company_enricher. After you resolve a contact's company_domain via person_enricher, enrich the account for firmographics in the same workflow.

Was this page helpful?

Last updated 2 weeks ago

Built with Documentation.AI

Waterfall Enrichment

Billing Model

Response Envelope

Endpoints

Email Finder

Request

Parameters

Response

Phone Finder

Request

Parameters

Response

Email Verifier

Request

Response

Status values

Person Enricher

Request

Response

Company Enricher

Request

Response

Retry Strategy

Best Practices