Authentication

Every request needs your API key, sent as either header:

X-API-Key: YOUR_KEY
# or
Authorization: Bearer YOUR_KEY

Create a free account to explore the dashboard, or subscribe directly from the pricing page — either way you'll find your key in the dashboard.

Search leads

Search Fyonta's owned contact database.

Param	Type	Notes
industry	string	Fuzzy match, e.g. IT Services
region_code	string	US state code, e.g. CA
seniority_tier	string	Comma-separated: C-Suite,VP,Director,Manager,Other
geo_bucket	string	US or a country code
min_quality	int	0–100 data quality score floor
min_icp	int	0–100 ICP match score floor
q	string	Fuzzy match on company name or title
limit / offset	int	Pagination, limit max 100

curl "https://api.fyonta.com/v1/leads/search?industry=IT+Services&seniority_tier=Director,VP,C-Suite&region_code=CA" \
  -H "X-API-Key: $FYONTA_KEY"

{
  "results": [{
    "company_name": "Robert Half",
    "domain": "roberthalf.com",
    "industry": "Staffing and Recruiting",
    "title": "VP, Talent Acquisition",
    "seniority_tier": "C-Suite",
    "email": "brooke.l@roberthalf.com",
    "data_quality_score": 100,
    "icp_match_score": 100
  }],
  "count": 1,
  "has_more": true,
  "offset": 0,
  "limit": 25
}

Search companies

Search Fyonta's owned firmographic database directly — no enrichment provider involved, so this never costs enrichment credits.

Param	Type	Notes
q	string	Fuzzy match on company name
domain	string	Exact match, e.g. acme.com
industry	string	Fuzzy match
region_code	string	State/region name
country_code	string	Country name
employee_count_range	string	Comma-separated, e.g. 1-10 or 11-50,51-200
limit / offset	int	Pagination, limit max 100

curl "https://api.fyonta.com/v1/leads/company-search?q=solar&country_code=Germany" \
  -H "X-API-Key: $FYONTA_KEY"

{
  "results": [{
    "company_name": "1stop solar gmbh",
    "domain": "1stopsolar.eu",
    "industry": "information technology and services",
    "employee_count_range": "11-50",
    "city": "eschborn",
    "region_code": "Hesse",
    "country_code": "Germany",
    "linkedin_url": "linkedin.com/company/1stop-solar-gmbh",
    "founded": "2023"
  }],
  "count": 1,
  "has_more": true,
  "offset": 0,
  "limit": 25
}

Enrichment endpoints

Live lookups for when your own list needs filling in. Every response is wrapped the same way: {"data": ..., "result_count": N}, plus page / per_page / total / last_page / has_more / next_cursor when the endpoint paginates. A miss returns result_count: 0 with an empty data — you're never charged for a miss.

Email search

Provide linkedin_url alone, or company_url + first_name + last_name. If you provide both, linkedin_url is tried first.

curl "https://api.fyonta.com/v1/enrich/email-search?linkedin_url=https://linkedin.com/in/janedoe" \
  -H "X-API-Key: $FYONTA_KEY"

{
  "data": {
    "first_name": "Jane",
    "last_name": "Doe",
    "title": "Senior Software Engineer",
    "email": "jane.doe@example.com",
    "employee_phone": "+1-555-0123",
    "employee_linkedin": "https://linkedin.com/in/janedoe",
    "email_verification_date": "2026-06-01",
    "company_url": "https://example.com",
    "company_name": "Example Corp",
    "email_domain": "example.com",
    "company_linked": "https://linkedin.com/company/example",
    "company_phone": "+1-555-9999",
    "industry": "Computer Software",
    "revenue": "10 - 20 Million",
    "employee_count": "100 - 249",
    "address": "123 Main St",
    "city": "San Francisco",
    "region_code": "CA",
    "zip": "94105",
    "country_code": "US"
  },
  "result_count": 1
}

Phone search

Same input rules as email search. Returns a direct or mobile number — employee_phone_type tells you which. Only charged when a number is actually returned.

Reverse email lookup

Params: email (required). Identifies the person and title behind an address — same response shape as email search.

Domain search

Lists contacts at a company, up to 25 per page.

Param	Type	Notes
company_url	string	Required. Domain or URL, e.g. example.com
title	string	One title or a comma-separated list — matches any of them
page	int	Default 1
has_email	bool	When true, only contacts with a real email on file

Response includes page, per_page, total, and last_page so you know when to stop paginating. Charged per contact returned when title is set; a flat 1 result_count charge per page of results when it isn't.

Contact finder

Discovery only — results never include an email or phone value, just has_email / has_phone booleans on each contact. Once you've found someone worth enriching, call email search or phone search with the returned employee_linkedin. Search itself is free.

Field	Match	Notes
title, locality, company_name, company_url, city, bio_li	Open text	Each takes {"include": [...], "exclude": [...]}
country_code, industry_linkedin, number_of_employees, revenue, services	Exact value	Same shape, but values must come from the matching lookup endpoint or you'll get a 400
has_email / has_phone	bool	Only return contacts that already have that data on file
page / per_page	int	Default page 1, per_page 10, max per_page 100. page only reaches the first 10,000 matches
cursor	string	Pass back next_cursor from the previous response to page past 10,000; ignores page while set

At least one filter must be set — an all-empty body is rejected. Values inside one include list are OR'd together; different fields are AND'd.

curl -X POST https://api.fyonta.com/v1/enrich/contact-finder \
  -H "X-API-Key: $FYONTA_KEY" -H "Content-Type: application/json" \
  -d '{"title": {"include": ["CEO"]}, "country_code": {"include": ["US"]}, "has_email": true}'

{
  "data": [{
    "first_name": "Jane",
    "last_name": "Doe",
    "title": "Chief Executive Officer",
    "employee_linkedin": "https://linkedin.com/in/janedoe",
    "company_name": "Example Corp",
    "company_url": "https://example.com",
    "city": "San Francisco",
    "country_code": "US",
    "has_email": true,
    "has_phone": false
  }],
  "result_count": 1,
  "page": 1,
  "per_page": 10,
  "total": 1,
  "last_page": 1,
  "has_more": false,
  "next_cursor": null
}

Company finder

Charged per company returned.

Field	Match	Notes
home_page_text, bio_li, city, company_name	Open text	Each takes {"include": [...], "exclude": [...]}
services, industry, number_of_employees, revenue, country_code	Exact value	Same shape, values from the matching lookup endpoint
company_url	string	A single domain, not include/exclude — matches the company's site or email domain
include_full_text	bool	Return the full scraped homepage text per result instead of just a snippet
page / per_page / cursor	—	Same pagination rules as contact finder

At least one filter must be set (a filter dimension or company_url).

{
  "data": [{
    "company_name": "Example Corp",
    "url": "example.com",
    "email_domain": "example.com",
    "linkedin_url": "https://linkedin.com/company/example",
    "city": "Austin",
    "region_code": "TX",
    "country_code": "US",
    "industry": "Computer Software",
    "employee_count": "100 - 249",
    "revenue": "10 - 20 Million",
    "services": ["Cloud Migration", "DevOps"],
    "home_page_text_snippet": "We help enterprises modernize with cloud migration..."
  }],
  "result_count": 1,
  "page": 1,
  "per_page": 10,
  "total": 1,
  "last_page": 1
}

Lookup values

Contact finder and company finder reject anything that isn't an exact string for country_code, industry / industry_linkedin, number_of_employees, revenue, and services. These five endpoints tell you the valid values instead of guessing — they're free to call, don't touch your enrichment usage, and work on every plan including a demo key.

Endpoint	Returns
GET /v1/enrich/lookups/countries	ISO 2-letter codes, e.g. "US", "GB"
GET /v1/enrich/lookups/industries	Industry names, e.g. "Computer Software"
GET /v1/enrich/lookups/employee-ranges	Size labels, e.g. "100 - 249", ">10000"
GET /v1/enrich/lookups/revenue-ranges	Revenue bands, e.g. "10 - 20 Million", ">1 Billion"
GET /v1/enrich/lookups/services?q=	Service names with how many companies match each, e.g. {"value": "Cloud Migration", "count": 1477} — optional q filters by keyword

curl "https://api.fyonta.com/v1/enrich/lookups/services?q=cloud" \
  -H "X-API-Key: $FYONTA_KEY"

{
  "values": [
    {"value": "Cloud Services", "count": 8782},
    {"value": "Cloud Solutions", "count": 6180},
    {"value": "Cloud Computing", "count": 2698}
  ]
}

Rate limits & errors

Rate limits are per API key, per minute, and apply across the REST API and MCP server together — it's one usage pool either way.

Plan	Rate limit
Basic	200 requests/min
Pro	1,000 requests/min
Free trial	Your plan's per-minute rate limit, 5,000 requests in total over the 7-day trial
Demo key	10 requests/min, 500 requests/month total

A request over the limit gets 429. Other error codes you may see:

Status	Meaning
400	Invalid parameters — e.g. a filter value that isn't in its lookup list, or no filter set at all
403	Demo keys can search but can't call the live enrichment endpoints — subscribe to unlock them
404	No match found for the given input
503	Enrichment temporarily unavailable — retry shortly

Errors are always a JSON object with a plain-English detail field: {"detail": "No match found for the given input"}.

MCP server

Point any MCP-compatible agent at Fyonta directly. Same key, same rate limits, same data as the REST API.

// mcp client config
{
  "fyonta": {
    "url": "https://api.fyonta.com/mcp",
    "headers": { "X-API-Key": "$FYONTA_KEY" }
  }
}

Available tools: search_leads, search_companies, enrich_email_search, enrich_phone_search, enrich_reverse_email_lookup, enrich_domain_search, enrich_contact_finder, enrich_company_finder, enrich_lookup_countries, enrich_lookup_industries, enrich_lookup_employee_ranges, enrich_lookup_revenue_ranges, enrich_lookup_services — same parameters as their REST counterparts above.