# EnrichX402 API Reference
## Authentication

All endpoints require x402 payment. Include payment headers as per the HTTP 402 specification. Payments are processed on Base mainnet (eip155:8453).

## Base URL

https://enrichx402.com

All endpoints are relative to this base URL.

## Web Scraping

For web scraping tasks, always start with **Firecrawl `/api/firecrawl/scrape`** ($0.0126/request). It provides comprehensive page content with clean markdown formatting.

If you need to scrape many URLs and cost is a concern, consider **Exa `/api/exa/contents`** ($0.002/request) as a cheaper alternative for bulk processing.

---

# Research Methodology (Fan-out / Population Tasks)

Use this playbook for ambiguous, broad, or "find many candidates" requests (e.g., "junior hedge fund carry-trade people who might start a company"):

1. **Detect fan-out**: If the request implies a population or list-building task, avoid single-search answers. Plan for *many* queries and a large candidate pool.
2. **Clarify constraints**: Restate the target, must-haves, nice-to-haves, geography, seniority, timeframe, and desired output size. If unclear, make explicit assumptions and proceed.
3. **Broad-to-narrow pipeline**:
   - **Seed**: Use multiple discovery sources to build an initial pool (Exa / Firecrawl for web lists, Grok for social signals, Google Maps for local orgs, Apollo org-search for company IDs).
   - **Expand**: Generate query variants (synonyms, titles, strategies, regions) and paginate until you reach a healthy pool (aim 50–100 candidates).
   - **Enrich**: Use Apollo people-search + people-enrich (and Clado if needed) to fill details; dedupe by name + company + profile URL.
   - **Filter**: Apply the must-haves; keep 30–50 high-confidence matches.
4. **Tool choreography**: Use **mcp__x402__fetch** for all paid endpoints. Verify Apollo org IDs with /api/apollo/org-search before large people searches to avoid wasted calls.
5. **Evidence and transparency**: Track sources per candidate; note uncertainty; surface how the list was constructed and where gaps remain.

---

# Google Maps API

## POST /api/google-maps/text-search/full
Search for places using a text query with full field details (includes ratings, reviews, contact info, and atmosphere data).
Price: $0.08 per request

Request Body:
- textQuery (string, required): Search query text
- maxResultCount (number, 1-5, default: 5): Maximum results to return
- excludeFields (string[], default: ["photos"]): Fields to exclude from response (pass empty array [] to include photos)
- pageToken (string, optional): Pagination token from previous response
- locationBias (object, optional): Bias results to a location
  - circle.center.latitude (number)
  - circle.center.longitude (number)
  - circle.radius (number, 0-50000 meters)
- includedType (string, optional): Filter by place type
- languageCode (string, default: "en"): Language for results
- openNow (boolean, optional): Filter to currently open places
- minRating (number, 0-5, optional): Minimum rating filter
- priceLevels (string[], optional): Price level filter (PRICE_LEVEL_FREE, PRICE_LEVEL_INEXPENSIVE, PRICE_LEVEL_MODERATE, PRICE_LEVEL_EXPENSIVE, PRICE_LEVEL_VERY_EXPENSIVE)

Example:
```json
{
  "textQuery": "coffee shops in San Francisco",
  "maxResultCount": 5
}
```

Response: Object with `places` array containing place objects with id, displayName, formattedAddress, location, types, rating, userRatingCount, reviews, regularOpeningHours, currentOpeningHours, websiteUri, nationalPhoneNumber, internationalPhoneNumber, editorialSummary, and service options (delivery, dineIn, takeout, etc.). Photos excluded by default. May include `nextPageToken` for pagination.

---

## POST /api/google-maps/text-search/partial
Search for places using a text query with partial field details (basic info only, lower cost).
Price: $0.02 per request

Request Body: Same as /text-search/full

Response: Same structure as /text-search/full but returns fewer fields (core fields: id, displayName, formattedAddress, location, types, googleMapsUri, businessStatus, accessibilityOptions). Photos excluded by default.

---

## POST /api/google-maps/nearby-search/full
Search for places near a geographic location with full details.
Price: $0.08 per request

Request Body:
- locationRestriction (object, required): Search area
  - circle.center.latitude (number)
  - circle.center.longitude (number)
  - circle.radius (number, 0-50000 meters)
- maxResultCount (number, 1-5, default: 5): Maximum results
- excludeFields (string[], default: ["photos"]): Fields to exclude (pass empty array [] to include photos)
- includedTypes (string[], max 50, optional): Place types to include
- excludedTypes (string[], max 50, optional): Place types to exclude
- languageCode (string, default: "en"): Language for results
- rankPreference (string, default: "POPULARITY"): "POPULARITY" or "DISTANCE"

Example:
```json
{
  "locationRestriction": {
    "circle": {
      "center": { "latitude": 37.7749, "longitude": -122.4194 },
      "radius": 1000
    }
  },
  "maxResultCount": 5
}
```

Response: Same as /text-search/full

---

## POST /api/google-maps/nearby-search/partial
Search for places near a geographic location with partial details.
Price: $0.02 per request

Request Body: Same as /nearby-search/full

Response: Same as /text-search/partial

---

## GET /api/google-maps/place-details/full
Get full details for a specific place by ID.
Price: $0.05 per request

Query Parameters:
- placeId (string, required): Google Place ID
- excludeFields (string, default: "photos"): Comma-separated fields to exclude (pass empty string to include photos)
- languageCode (string, default: "en"): Language for results

Example: GET /api/google-maps/place-details/full?placeId=ChIJN1t_tDeuEmsRUsoyG83frY4

Response: Single place object with all available fields.

---

## GET /api/google-maps/place-details/partial
Get partial details for a specific place by ID.
Price: $0.02 per request

Query Parameters: Same as /place-details/full

Response: Single place object with core fields only.

---

# Apollo API

IMPORTANT: Organization Lookup Workflow
When performing bulk people searches filtered by organization (using organization_ids or q_organization_domains), you MUST first verify the exact organization identifier using /api/apollo/org-search. Apollo performs exact matching on organization IDs and domains - if the identifier is incorrect or misspelled, the search will return zero results or the wrong company's employees. This verification step is critical before making any bulk call to avoid wasted requests and incorrect data.

Recommended workflow:
1. Call /api/apollo/org-search with the company name or domain
2. Confirm the returned organization_id and domain match your intended target
3. Use the verified identifier in your /api/apollo/people-search call


EXTREMELY IMPORTANT:

When Apollo People Search returns names, it will return them in an obfuscated manner. It is absolutely critical that you then immediately use the /api/apollo/people-enrich endpoint to get their full information.
You should pass the person's ID directly into enrich to ensure you get correct data for the person.

If Apollo does not return the needed data, always fall back to Clado (especially for personal emails, phone numbers, and newer accounts). Use /api/clado/contacts-enrich or /api/clado/linkedin-scrape after Apollo fails.

## POST /api/apollo/people-search
Search for people/contacts matching criteria.
Price: $0.02 per request

Request Body:
- q_keywords (string, optional): Keywords to search across all fields
- person_titles (string[], optional): Job titles to match
- person_not_titles (string[], optional): Job titles to exclude
- person_seniorities (string[], optional): Seniority levels (owner, founder, c_suite, partner, vp, head, director, manager, senior, entry, intern)
- person_locations (string[], optional): City, state, or country
- q_organization_domains (string[], optional): Company domains
- organization_locations (string[], optional): Organization locations
- organization_ids (string[], optional): Apollo organization IDs
- organization_num_employees_ranges (string[], optional): Ranges like "1,10", "11,50", "51,200", "201,500", "501,1000", "1001,5000", "5001,10000", "10001,"
- organization_industry_tag_ids (string[], optional): Industry filters
- excludeFields (string[], optional): Fields to exclude
- page (number, min: 1, default: 1): Page number
- per_page (number, 1-100, default: 25): Results per page

Example:
```json
{
  "q_keywords": "software engineer",
  "person_locations": ["San Francisco"],
  "per_page": 5
}
```

Response:
- people: Array of person objects with id, name (obfuscated), first_name, last_name, email, email_status, title, linkedin_url, photo_url, twitter_url, github_url, headline, seniority, departments, functions, city, state, country, phone_numbers, organization_id, organization, employment_history, etc.
- pagination: { page, per_page, total_entries, total_pages }

---

## POST /api/apollo/org-search
Search for organizations/companies matching criteria.
Price: $0.02 per request

Request Body:
- q_keywords (string, optional): Keywords to search
- organization_locations (string[], optional): Locations
- organization_num_employees_ranges (string[], optional): Employee count ranges
- organization_industry_tag_ids (string[], optional): Industry filters
- organization_ids (string[], optional): Apollo organization IDs
- q_organization_domains (string[], optional): Company domains
- excludeFields (string[], optional): Fields to exclude
- page (number, min: 1, default: 1): Page number
- per_page (number, 1-100, default: 25): Results per page

Example:
```json
{
  "q_keywords": "saas",
  "organization_locations": ["United States"],
  "per_page": 5
}
```

Response:
- organizations: Array with id, name, domain, website_url, linkedin_url, twitter_url, facebook_url, primary_phone, industry, keywords, estimated_num_employees, annual_revenue, annual_revenue_printed, total_funding, total_funding_printed, latest_funding_round_date, latest_funding_stage, city, state, country, postal_code, street_address, short_description, seo_description, founded_year, technologies, logo_url, etc.
- pagination: { page, per_page, total_entries, total_pages }

---

## POST /api/apollo/people-enrich
Enrich a person's profile with additional data.
Price: $0.0495 per request

Request Body:
- id (string, optional): Apollo person ID - use this when enriching after an Apollo people search to get full information
- first_name (string, optional): Person's first name
- last_name (string, optional): Person's last name
- name (string, optional): Full name if first/last not available
- email (string, optional): Email address (best matching signal)
- domain (string, optional): Company domain
- organization_name (string, optional): Company name
- linkedin_url (string, optional): LinkedIn profile URL
- reveal_personal_emails (boolean, default: false): Request personal email addresses
- excludeFields (string[], optional): Fields to exclude

Example:
```json
{
  "email": "tim@apple.com"
}
```

Response:
- person: Person object or null (same schema as people-search results, but with full unobfuscated data)
- status: Match status string

---

## POST /api/apollo/people-enrich/bulk
Enrich multiple people in a single request.
Price: $0.495 per request (up to 10 people)

Request Body:
- details (array, 1-10 items, required): Array of person lookup objects
  - id, first_name, last_name, name, email, domain, organization_name, linkedin_url (all optional)
- reveal_personal_emails (boolean, default: false): Request personal email addresses
- excludeFields (string[], optional)

Example:
```json
{
  "details": [
    { "email": "tim@apple.com" },
    { "email": "satya@microsoft.com" }
  ]
}
```

Response:
- matches: Array of { person, status } objects

---

## POST /api/apollo/org-enrich
Enrich an organization's profile by domain.
Price: $0.0495 per request

Request Body:
- domain (string, required): Company domain, e.g., "apollo.io"
- excludeFields (string[], optional): Fields to exclude

Example:
```json
{
  "domain": "apollo.io"
}
```

Response:
- organization: Organization object or null
- status: Match status string

---

## POST /api/apollo/org-enrich/bulk
Enrich multiple organizations in a single request.
Price: $0.495 per request (up to 10 organizations)

Request Body:
- domains (string[], 1-10 items, required): Array of company domains
- excludeFields (string[], optional): Fields to exclude

Example:
```json
{
  "domains": ["apollo.io", "stripe.com"]
}
```

Response:
- matches: Array of { organization, status } objects

---

# Grok API (X/Twitter Data)

## POST /api/grok/x-search
Search X (Twitter) posts using natural language.
Price: $0.02 per request

Request Body:
- query (string, required): Natural language search query
- maxResults (number, 1-10, default: 5): Maximum posts to return
- includeMedia (boolean, default: true): Include media attachments
- dateRange (object, optional): Filter by date
  - from (string, optional): ISO date string
  - to (string, optional): ISO date string

Example:
```json
{
  "query": "AI agents",
  "maxResults": 5
}
```

Response:
- posts: Array of post objects with id, text, author (handle, displayName, verified, followerCount), createdAt, metrics (likes, reposts, replies, views), media (type, url, altText), urls, conversationId, inReplyToId
- summary (string, optional): AI-generated summary of results
- searchContext: { query, resultCount, dateRange: { earliest, latest } }

---

## POST /api/grok/user-search
Search for X (Twitter) users.
Price: $0.02 per request

Request Body:
- query (string, required): Search query for users (name, handle, bio keywords, or role)
- maxResults (number, 1-10, default: 5): Maximum users to return

Example:
```json
{
  "query": "AI researcher",
  "maxResults": 5
}
```

Response:
- users: Array of user objects with handle, displayName, bio, followerCount, followingCount, verified, location, website, joinedDate, profileImageUrl
- searchContext: { query, resultCount }

---

## POST /api/grok/user-posts
Get recent posts from a specific X user.
Price: $0.02 per request

Request Body:
- handle (string, required): X username without the @
- maxResults (number, 1-10, default: 5): Maximum posts to return

Example:
```json
{
  "handle": "elonmusk",
  "maxResults": 5
}
```

Response:
- handle: User's handle
- displayName: User's display name
- posts: Array of post objects with id, text, createdAt, likes, reposts, replies, views, isReply, urls
- postCount: Number of posts returned

---

# Exa API (Web Search & Research)

## POST /api/exa/search
Semantic web search for finding relevant pages.
Price: $0.01 per request

Request Body:
- query (string, required): Search query
- numResults (number, 1-100, default: 5): Number of results
- type (string, optional): Search type - "neural" (semantic), "fast" (keyword), "auto" (automatic selection), "deep" (thorough but slower); default: auto
- category (string, optional): Filter by category (company, research paper, news, pdf, github, tweet, personal site, linkedin profile, financial report) 
    (Note: The company and people categories do NOT supported for these parameters: startPublishedDate, endPublishedDate, startCrawlDate, endCrawlDate, includeText, excludeText, excludeDomains. For the people category, includeDomains only accepts LinkedIn domains.)
- includeDomains (string[], optional): Only include these domains
- excludeDomains (string[], optional): Exclude these domains
- startCrawlDate (string, optional): Filter by crawl date (ISO format)
- endCrawlDate (string, optional): Filter by crawl date (ISO format)
- startPublishedDate (string, optional): Filter by publish date (ISO format)
- endPublishedDate (string, optional): Filter by publish date (ISO format)
- includeText (string[], optional): Must contain these terms
- excludeText (string[], optional): Must not contain these terms
- userLocation (string, optional): User location for personalization
- additionalQueries (string[], optional): Additional query variations for broader results
- contents (object, optional): Content extraction options
  - text (boolean | object): Extract text content. Object form: { maxCharacters, includeHtmlTags }
  - highlights (object): Extract highlighted sentences { numSentences, highlightsPerUrl, query }
  - summary (object): Generate summary { query }
  - livecrawl (string): "never", "fallback", "always", "preferred"
  - livecrawlTimeout (number): Timeout in ms
  - subpages (number): Number of subpages to crawl
  - subpageTarget (string | string[]): Target subpage patterns
  - extras (object): { links, imageLinks } - number of each to extract

Example:
```json
{
  "query": "best practices for building AI agents",
  "numResults": 5
}
```

Response:
- results: Array with title, url, publishedDate, author, score, id, image, favicon, text, highlights, highlightScores, summary, extras, subpages
- searchType: Resolved search type used ("neural" or "deep")
- resolvedSearchType: Same as searchType
- requestId: Request identifier
- context (string, optional): Additional context
- costDollars (object, optional): { total } - Exa's reported cost

---

## POST /api/exa/find-similar
Find pages similar to a given URL.
Price: $0.01 per request

Request Body:
- url (string, required): URL to find similar pages for
- numResults (number, 1-100, default: 5): Number of results
- includeDomains, excludeDomains, date filters, contents (same as /search)

Example:
```json
{
  "url": "https://openai.com",
  "numResults": 5
}
```

Response:
- results: Array of similar pages with title, url, score, text, etc.
- requestId: Request identifier
- context (string, optional): Additional context
- costDollars (object, optional): { total }

---

## POST /api/exa/contents
Extract content from specific URLs.
Price: $0.002 per request

Request Body:
- urls (string[], required): URLs to extract content from
- text (boolean | object, optional): Extract text content
  - maxCharacters (number): Limit text length
  - includeHtmlTags (boolean): Include HTML tags
- highlights (object, optional): Extract highlights
  - numSentences (number): Sentences per highlight
  - highlightsPerUrl (number): Highlights per URL
  - query (string): Focus highlights on query
- summary (object, optional): Generate summaries
  - query (string): Focus summary on query
- livecrawl (string, optional): "never", "fallback", "always", "preferred"
- livecrawlTimeout (number, optional): Timeout in ms
- subpages (number, optional): Number of subpages to crawl
- subpageTarget (string | string[], optional): Target subpage patterns
- extras (object, optional): Additional extraction
  - links (number): Extract links
  - imageLinks (number): Extract image links

Example:
```json
{
  "urls": ["https://example.com"]
}
```

Response:
- results: Array with url, title, text, highlights, summary, id, image, favicon
- statuses: Array of crawl statuses per URL { id, status: "success"|"error", error: { tag, httpStatusCode } }
- requestId: Request identifier
- context (string, optional): Additional context
- costDollars (object, optional): { total }

---

## POST /api/exa/answer
Get an AI-generated answer to a question based on web search.
Price: $0.01 per request

Request Body:
- query (string, required): Question or query to answer
- stream (boolean, default: false): Stream response (not currently supported)
- text (boolean, default: false): Include source text in citations

Example:
```json
{
  "query": "What is the capital of France?"
}
```

Response:
- answer: AI-generated answer string
- citations: Array of source citations with id, url, title, author, publishedDate, text, image, favicon
- costDollars (object, optional): { total }

---

# Firecrawl API (Web Scraping)

## POST /api/firecrawl/scrape
Scrape and extract content from a URL.
Price: $0.0126 per request

Request Body:
- url (string, required): URL to scrape

Example:
```json
{
  "url": "https://example.com"
}
```

Response:
- url: Final URL after redirects
- title: Page title
- content: Page content as markdown

---

## POST /api/firecrawl/search
Search the web and get scraped results.
Price: $0.0252 per request

Request Body:
- query (string, required): Search query
- limit (number, 1-10, default: 5): Maximum results

Example:
```json
{
  "query": "best coffee shops",
  "limit": 5
}
```

Response:
- results: Array with title, url, description, snippet (first 500 chars of markdown)
- query: Original query
- resultCount: Number of results returned

---

# Clado API (LinkedIn & Contact Enrichment)

Note: Clado is particularly useful as a fallback when Apollo doesn't return personal emails, phone numbers, or data for newer LinkedIn accounts.

## POST /api/clado/contacts-enrich
Enrich contact information from LinkedIn URL, email, or phone number.
Price: $0.20 per request

Request Body (exactly one identifier required):
- linkedin_url (string, optional): LinkedIn profile URL to enrich
- email (string, optional): Email address to enrich
- phone (string, optional): Phone number to enrich
- email_enrichment (boolean, default: false): Request email enrichment (costs credits when found)
- phone_enrichment (boolean, default: false): Request phone enrichment (costs credits when found)

Notes: Must provide exactly one of: linkedin_url, email, or phone

Example:
```json
{
  "linkedin_url": "https://www.linkedin.com/in/satyanadella"
}
```

Response:
- data: Array of contact info objects
  - error (boolean, optional): Whether an error occurred
  - contacts: Array of contact objects
    - type: "email" or "phone"
    - value: Contact value
    - rating: Confidence score (0-100)
    - subType (string, optional): Contact subtype
  - social: Array of social profile objects
    - link: Social profile URL
    - type: Social network type
    - rating: Confidence score (0-100)

---

## POST /api/clado/linkedin-scrape
Scrape full LinkedIn profile data including experience, education, skills, and posts.
Price: $0.04 per request

Request Body:
- linkedin_url (string, required): LinkedIn profile URL to scrape

Example:
```json
{
  "linkedin_url": "https://www.linkedin.com/in/satyanadella"
}
```

Response:
- profile: Profile object
  - id, name, headline, summary, location, title
  - linkedin_profile_url, linkedin_flagship_url, profile_picture_url
  - num_of_connections, last_updated, linkedin_url, twitter_handle
  - websites (string[]), emails (string[]), criteria (object)
- experience: Array of experience objects
  - employee_position_id, employee_title, employer_name, employee_description
  - employer_linkedin_description, employer_linkedin_id, employer_linkedin_url, employer_logo_url
  - start_date, end_date, employee_location, employer_company_ids, employer_company_website_domains
  - location, is_current
- education: Array of education objects
  - institute_name, degree_name, field_of_study
  - institute_linkedin_id, institute_linkedin_url, institute_logo_url
  - start_date, end_date, description
- skills: Array of skill strings
- languages: Array of language strings
- location: Geographic location string
- certifications: Array of certification objects
- honors: Array of honor objects
- posts: Array of post objects
  - post_url, title, action, order_in_profile

---

# Serper API (Google Search)

## POST /api/serper/news
Google News search via Serper.dev.
Price: $0.04 per request

Request Body:
- q (string, required): Google search query
- num (number, optional, 1-100): Number of results to return
- gl (string, optional): Country code (e.g., "us")
- hl (string, optional): Language code (e.g., "en")
- location (string, optional): Location (e.g., "New York, NY")

Example:
```json
{
  "q": "OpenAI funding",
  "num": 10,
  "gl": "us",
  "hl": "en"
}
```

Response:
- searchParameters: Object of resolved search parameters { q, gl, hl, num, type }
- news: Array of news results with position, title, link, snippet, date, source, imageUrl

---

## POST /api/serper/shopping
Google Shopping search via Serper.dev.
Price: $0.04 per request

Request Body: Same as /api/serper/news

Example:
```json
{
  "q": "wireless earbuds",
  "num": 10,
  "gl": "us",
  "hl": "en"
}
```

Response:
- searchParameters: Object of resolved search parameters
- shopping: Array of shopping results with position, title, link, snippet, and additional shopping-specific fields

---

# Whitepages API (People & Property Search)

## POST /api/whitepages/person-search
Search for people by name, phone number, or address.
Price: $0.44 per request

Request Body:
- name (string, optional): Full name to search for
- first_name (string, optional): First name
- last_name (string, optional): Last name
- phone (string, optional): Phone number
- street (string, optional): Street address
- city (string, optional): City name
- state_code (string, optional): Two-letter state code
- zipcode (string, optional): ZIP code
- min_age (number, optional): Minimum age filter
- max_age (number, optional): Maximum age filter
- radius (number, max 100, optional): Radius in miles from address
- include_historical_locations (boolean, optional): Include historical addresses in radius search
- excludeFields (string[], optional): Fields to exclude from response

Example:
```json
{
  "first_name": "John",
  "last_name": "Smith",
  "state_code": "CA"
}
```

Response:
- persons: Array of person objects
  - id, name, aliases (string[])
  - is_dead (boolean)
  - current_addresses: Array of address objects (id, address, full_address, line1, line2, city, state, zip, house, street, street_type, county)
  - historic_addresses: Array of address objects
  - owned_properties: Array of address objects
  - phones: Array of phone objects (number, type, score)
  - emails: Array of email strings
  - date_of_birth
  - linkedin_url, company_name, job_title
  - relatives: Array of relative objects (id, name)

---

## POST /api/whitepages/property-search
Get property ownership, resident, and property details by address.
Price: $0.44 per request

IMPORTANT: The state parameter is named `state_code`, NOT `state`. You must use the field name `state_code` with a two-letter state abbreviation (e.g., "CA", "NY", "TX"). Using `state` instead of `state_code` will result in the field being ignored.

Request Body:
- street (string, required): Street address
- city (string, optional): City name
- state_code (string, optional): Two-letter state code (e.g., "CA", "NY", "TX"). NOTE: field name is `state_code`, not `state`
- zipcode (string, optional): ZIP code
- excludeFields (string[], optional): Fields to exclude from response

Example:
```json
{
  "street": "123 Main St",
  "city": "San Francisco",
  "state_code": "CA"
}
```

WRONG (will not work):
```json
{
  "street": "123 Main St",
  "city": "San Francisco",
  "state": "CA"
}
```

Response:
- result: Property object or null
  - property_id, apn (assessor parcel number)
  - property_address: Address object
  - mailing_address: Address object
  - geolocation: { lat, lng }
  - ownership_info: Object
    - owner_type
    - business_owners: Array of { name }
    - person_owners: Array of owner objects (id, name, current_addresses, phones, emails)
  - residents: Array of resident objects (id, name, phones, emails)
  - property_details: Object
    - year_built, bedrooms, bathrooms, building_area, lot_size
    - property_use, building_type, rooms, stories
    - pool, fireplace, air_conditioning, heating, basement
    - garage_type, parking_spaces, construction_type, roof_type
    - exterior_walls, flooring, water_source, sewer
  - market_value: Object
    - estimated_value, estimated_value_range_low, estimated_value_range_high, value_date
  - sale_history: Array of sale objects
    - sale_date, sale_price, buyer_name, seller_name, document_type
  - tax_info: Object
    - assessed_value, assessment_year, market_value, tax_amount, tax_year

---

# Reddit API

IMPORTANT - Two-step pattern for Reddit research:
1. Use /api/reddit/search to find relevant posts. Responses are lightweight — selftext is truncated to 500 chars.
   Posts with `selftextTruncated: true` have more content available.
2. For any post where you need the full text or comments, call /api/reddit/post-comments with the post's permalink.
   This returns the complete untruncated selftext plus all comments.

This pattern keeps search results small (< 2KB for 10 posts) while letting you drill into specific posts when needed.

## POST /api/reddit/search
Search Reddit posts by query. Returns truncated previews for efficient browsing.
Price: $0.02 per request

Request Body:
- query (string, required): Search term
- sort (string, optional): relevance|new|top|comment_count (default: relevance)
- timeframe (string, optional): all|day|week|month|year (default: all)
- after (string, optional): Pagination cursor
- maxResults (number, 1-25, default: 10): Maximum results

Example:
```json
{
  "query": "AI agents",
  "sort": "top",
  "timeframe": "week",
  "maxResults": 10
}
```

Response:
- posts: Array of post objects
  - id: Post ID
  - title: Post title
  - author: Author username
  - subreddit: Subreddit name
  - score: Net upvotes
  - numComments: Comment count
  - createdAt: ISO timestamp
  - selftext: Text content preview (truncated to 500 chars) or null
  - selftextTruncated: true if selftext was truncated — use /api/reddit/post-comments to get full text
  - permalink: Full Reddit URL
- after: Pagination cursor for next page (or null)
- searchContext: { query, resultCount }

---

## POST /api/reddit/post-comments
Get a Reddit post's full details and comments. Use this to get untruncated selftext and discussion for posts found via search.
Price: $0.02 per request

Request Body:
- url (string, required): Full Reddit post URL (use the permalink from search results)
- cursor (string, optional): Pagination cursor for more comments

Example:
```json
{
  "url": "https://www.reddit.com/r/AskReddit/comments/abc123/example_post"
}
```

Response:
- post: Full post object with id, title, author, subreddit, score, numComments, createdAt, selftext (complete, untruncated), permalink
- comments: Array of comment objects
  - id: Comment ID
  - author: Author username
  - body: Comment text (truncated to 1000 chars)
  - bodyTruncated: true if body was truncated
  - score: Net upvotes
  - createdAt: ISO timestamp
- hasMore: Whether more comments available
- cursor: Pagination cursor for more comments (or null)

---

# Hunter API (Email Verification)

## POST /api/hunter/email-verifier
Verify email deliverability via Hunter.io.
Price: $0.03 per request

Request Body:
- email (string, required): Email address to verify

Example:
```json
{
  "email": "test@stripe.com"
}
```

Response:
- status (string): Verification status (valid, invalid, accept_all, webmail, disposable, unknown)
- score (number): Deliverability score (0-100)
- email (string): The verified email address
- regexp (boolean): Email passes regex validation
- gibberish (boolean): Auto-generated email detection
- disposable (boolean): Disposable email service detection
- webmail (boolean): Webmail provider detection
- mx_records (boolean): MX records exist
- smtp_server (boolean): Successful SMTP connection
- smtp_check (boolean): Email doesn't bounce
- accept_all (boolean): SMTP server accepts all addresses
- block (boolean): SMTP server blocking verification
- sources (array): URLs where the email was found (max 20)
  - domain (string): Source domain
  - uri (string): Full source URL
  - extracted_on (string): First discovery date
  - last_seen_on (string): Most recent sighting
  - still_on_page (boolean): Currently present on page 

---

# Influencer API (Social Media Influencer Enrichment)

The Influencer API helps you enrich social media influencer profiles across multiple platforms (Instagram, TikTok, YouTube, Twitter/X, Facebook). Use this for influencer marketing research and social media contact enrichment.

## POST /api/influencer/enrich-by-email
Find social media profiles associated with an email address.
Price: $0.40 per request

Request Body:
- email (string, required): Email address to enrich
- platform (string, optional): Specific platform to search - "instagram", "tiktok", "youtube", "twitter", or "facebook"
- enrichment_mode (string, default: "raw"): "raw" or "enhanced" - detail level of enrichment
- excludeFields (string[], optional): Fields to exclude from response

Example:
```json
{
  "email": "creator@example.com",
  "platform": "instagram",
  "enrichment_mode": "enhanced"
}
```

Response:
- profiles: Array of social media profile objects
  - id (string): Platform-specific profile ID
  - username (string): Social media handle
  - platform (string): Platform name
  - email (string): Email address
  - followers (number): Follower count
  - following (number): Following count
  - engagement_rate (number): Engagement rate percentage
  - bio (string): Profile bio/description
  - url (string): Profile URL
  - avatar_url (string): Profile picture URL
  - verified (boolean): Verification status
- status (string): Response status message

---

## POST /api/influencer/enrich-by-social
Enrich a social media profile with additional data including contact info.
Price: $0.40 per request

Request Body:
- platform (string, required): Social media platform - "instagram", "tiktok", "youtube", "twitter", or "facebook"
- username (string, required): Social media username or handle
- enrichment_mode (string, default: "raw"): "raw" or "enhanced" - detail level of enrichment
- email_required (string, default: "optional"): "must_have", "optional", or "not_required" - email address requirement
- excludeFields (string[], optional): Fields to exclude from response

Example:
```json
{
  "platform": "instagram",
  "username": "example_creator",
  "enrichment_mode": "enhanced",
  "email_required": "must_have"
}
```

Response:
- profile: Enriched profile object or null
  - id (string): Platform-specific profile ID
  - username (string): Social media handle
  - platform (string): Platform name
  - email (string): Contact email if available
  - phone (string): Contact phone if available
  - followers (number): Follower count
  - following (number): Following count
  - posts_count (number): Total posts count
  - engagement_rate (number): Engagement rate percentage
  - avg_likes (number): Average likes per post
  - avg_comments (number): Average comments per post
  - bio (string): Profile bio/description
  - url (string): Profile URL
  - avatar_url (string): Profile picture URL
  - verified (boolean): Verification status
  - location (string): Profile location
  - website (string): Associated website URL
  - categories (string[]): Profile categories/niches
- status (string): Response status message

---

# Common Features

## Field Filtering
Most endpoints support an `excludeFields` parameter to reduce response size by omitting specific fields. Pass an array of dot-notation field paths to exclude. Google Maps endpoints default to excluding "photos" - pass an empty array to include them.

## Pagination
- Apollo search endpoints support pagination via `page` and `per_page` parameters.
- Google Maps search endpoints support pagination via `pageToken` (returned as `nextPageToken` in responses).
- Exa search supports `numResults` up to 100.

## Error Handling
All endpoints return standard HTTP status codes. Payment-required responses (402) include x402 payment instructions in headers. On server errors (5xx), payments are not settled.

---

# Pricing Summary

| Endpoint | Price |
|----------|-------|
| Google Maps Text Search (Full) | $0.08 |
| Google Maps Text Search (Partial) | $0.02 |
| Google Maps Nearby Search (Full) | $0.08 |
| Google Maps Nearby Search (Partial) | $0.02 |
| Google Maps Place Details (Full) | $0.05 |
| Google Maps Place Details (Partial) | $0.02 |
| Apollo People Search | $0.02 |
| Apollo Org Search | $0.02 |
| Apollo People Enrich | $0.0495 |
| Apollo People Enrich (Bulk, up to 10) | $0.495 |
| Apollo Org Enrich | $0.0495 |
| Apollo Org Enrich (Bulk, up to 10) | $0.495 |
| Grok X Search | $0.02 |
| Grok User Search | $0.02 |
| Grok User Posts | $0.02 |
| Exa Search | $0.01 |
| Exa Find Similar | $0.01 |
| Exa Contents | $0.002 |
| Exa Answer | $0.01 |
| Firecrawl Scrape | $0.0126 |
| Firecrawl Search | $0.0252 |
| Clado Contacts Enrich | $0.20 |
| Clado LinkedIn Scrape | $0.04 |
| Serper News | $0.04 |
| Serper Shopping | $0.04 |
| Reddit Search | $0.02 |
| Reddit Post Comments | $0.02 |
| Whitepages Person Search | $0.44 |
| Whitepages Property Search | $0.44 |
| Hunter Email Verifier | $0.03 |
| Influencer Enrich by Email | $0.40 |
| Influencer Enrich by Social | $0.40 |