Documentation
Build on fareof.
Everything you need to plug AI prospect search and triple-verified emails into your stack — REST endpoints, idiomatic curl examples, copy-paste ready.
Quickstart
fareof exposes a JSON REST API at https://fareof.com/api. Every endpoint accepts an Authorization: Bearer fareof_live_… header. Get a key from /app/settings/api-keys after you sign in.
# 1. Create an account
open https://fareof.com/signup
# 2. Mint a key at /app/settings/api-keys → "New key"
# 3. Hit /api/me to confirm
curl https://fareof.com/api/me \
-H "Authorization: Bearer fareof_live_xxxx"
# {
# "success": true,
# "data": {
# "user": { "id": "...", "email": "[email protected]", ... },
# "session": { ... },
# "organizations": [ { "id": "...", "name": "...", "role": "owner" } ]
# }
# }Authentication
All API requests must carry a Bearer token in the Authorization header. Tokens are sha-256 hashed with a server-side pepper before storage; the raw value is shown to you once at creation time and never again.
- Format:
fareof_live_followed by 43 base64url chars (256 bits of entropy) - Permissions inherit from the user that minted the key. Demoting that user immediately scopes down what their keys can do.
- Up to 20 active keys per organization. Revoke unused ones first.
- Revocation is immediate (soft-delete via
revoked_at). Once revoked a key cannot be reactivated — mint a new one. - Cookie-based session auth (the web app) and Bearer-token auth (this API) work side by side. You can use either against the same endpoints.
Rate limits & errors
Per-key rate limits are not enforced server-side yet (early access); please be reasonable while we wire up @fastify/rate-limit. We'll publish concrete limits before charging more than the free tier.
Every error response uses the same envelope:
{
"success": false,
"error": "unauthenticated",
"message": "optional human-readable detail",
"issues": [/* zod validation issues, when applicable */]
}| Status | Error code | Meaning |
|---|---|---|
| 400 | invalid_body | Request body failed Zod validation. issues[] shows which field. |
| 401 | unauthenticated | Missing/expired session, or invalid Bearer token. |
| 403 | no_active_organization | Caller has no membership row. |
| 404 | not_found | Resource doesn't exist or belongs to another org. |
| 409 | too_many_active_keys | Already at 20-key cap. Revoke an old one first. |
| 409 | plan_in_use | Trying to delete a plan with active subscriptions. |
Endpoints
Selected endpoints — full reference will land before public launch.
/api/meThe authenticated user, their session, and their organizations.
curl https://fareof.com/api/me \
-H "Authorization: Bearer fareof_live_xxxx"/api/search/companiesFilter companies by industry, employee count, funding round, location.
curl https://fareof.com/api/search/companies \
-H "Authorization: Bearer fareof_live_xxxx" \
-H "Content-Type: application/json" \
-d '{
"industry": ["fintech"],
"employeeCountMin": 100,
"hqCountry": "United States",
"limit": 25
}'/api/search/peopleFilter people by seniority, department, company filters.
curl https://fareof.com/api/search/people \
-H "Authorization: Bearer fareof_live_xxxx" \
-H "Content-Type: application/json" \
-d '{
"seniority": ["cxo", "vp"],
"department": ["sales"],
"company": { "industry": ["fintech"] },
"limit": 50
}'/api/search/aiNatural-language → structured filter via z.ai. Returns parsed filters + ranked results.
curl https://fareof.com/api/search/ai \
-H "Authorization: Bearer fareof_live_xxxx" \
-H "Content-Type: application/json" \
-d '{ "prompt": "VPs of Sales at Series-B SaaS in EMEA" }'/api/listsCreate a lead list.
curl https://fareof.com/api/lists \
-H "Authorization: Bearer fareof_live_xxxx" \
-H "Content-Type: application/json" \
-d '{ "name": "Q3 outbound — fintech CXOs" }'/api/verifyVerify a single email through the triple-check pipeline.
curl https://fareof.com/api/verify \
-H "Authorization: Bearer fareof_live_xxxx" \
-H "Content-Type: application/json" \
-d '{ "email": "[email protected]" }'/api/lists/:id/verifyBulk-verify every email on a list. Returns counts; emails are updated in place.
curl -X POST https://fareof.com/api/lists/$LIST_ID/verify \
-H "Authorization: Bearer fareof_live_xxxx"/api/lists/:id/export.csvStream a list as CSV. Same auth header (Bearer token) required.
curl https://fareof.com/api/lists/$LIST_ID/export.csv \
-H "Authorization: Bearer fareof_live_xxxx" \
-o list.csvIntegrations
Six native integrations live today. Each one is a thin wrapper around the API endpoints above — no proprietary SDK to install. The recipes below are copy-paste curl pipelines; swap them into Make, Zapier, n8n, or your own backend.
All recipes assume FAREOF_API_KEY=fareof_live_… is set in your shell. Mint one at /app/settings/api-keys.
Push verified leads as Salesforce Leads after every list export.
# 1) Search + save to a list
curl -s https://fareof.com/api/search/people \
-H "Authorization: Bearer $FAREOF_API_KEY" \
-H "Content-Type: application/json" \
-d '{"seniority":["cxo","vp"],"company":{"industry":["fintech"]},"limit":50}' \
| jq '.data.items'
# 2) Bulk verify the list (returns updated rows)
curl -X POST https://fareof.com/api/lists/$LIST_ID/verify \
-H "Authorization: Bearer $FAREOF_API_KEY"
# 3) Pull verified rows + push to Salesforce REST API
curl https://fareof.com/api/lists/$LIST_ID/export.csv \
-H "Authorization: Bearer $FAREOF_API_KEY" \
| python3 push_to_salesforce.py # your script: maps email → LeadSync verified contacts into a HubSpot list, deduped by email.
# Verify a single email + create HubSpot contact in one shell pipeline
EMAIL="[email protected]"
STATUS=$(curl -s https://fareof.com/api/verify \
-H "Authorization: Bearer $FAREOF_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"email\":\"$EMAIL\"}" | jq -r '.data.status')
if [ "$STATUS" = "valid" ]; then
curl -X POST https://api.hubapi.com/crm/v3/objects/contacts \
-H "Authorization: Bearer $HUBSPOT_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"properties\":{\"email\":\"$EMAIL\",\"hs_lead_status\":\"NEW\"}}"
fiCSV pipeline: fareof verified list → Smartlead campaign upload.
# Pull verified-only CSV
curl https://fareof.com/api/lists/$LIST_ID/export.csv \
-H "Authorization: Bearer $FAREOF_API_KEY" \
-o leads.csv
# Smartlead Add Leads to Campaign — multipart upload
curl -X POST "https://server.smartlead.ai/api/v1/campaigns/$CAMPAIGN_ID/leads?api_key=$SMARTLEAD_KEY" \
-F "[email protected];type=text/csv"Same flow as Smartlead — Instantly accepts the same CSV shape.
curl https://fareof.com/api/lists/$LIST_ID/export.csv \
-H "Authorization: Bearer $FAREOF_API_KEY" \
-o leads.csv
# Instantly v2 API — JSON or CSV upload to a campaign
curl -X POST "https://api.instantly.ai/api/v2/leads" \
-H "Authorization: Bearer $INSTANTLY_KEY" \
-H "Content-Type: application/json" \
--data-binary @<(jq -Rsn 'inputs | split("\n") as $rows | $rows[1:] | map(split(",")) | map({"email": .[0], "first_name": .[1], "last_name": .[2]})' < leads.csv)No-code automation: trigger a Make scenario whenever fareof verifies a list.
# Make → HTTP module → POST to fareof
# In your Make scenario, add an HTTP "Make a request" step:
# URL: https://fareof.com/api/search/ai
# Method: POST
# Headers:
# Authorization: Bearer {{env.FAREOF_API_KEY}}
# Content-Type: application/json
# Body (JSON):
# { "prompt": "{{1.intent}}" }
# Use the response `data.items` array as the iterator for the next module
# (e.g. Google Sheets append, Slack post, HubSpot create-contact, etc.).Connect anything via Zapier Webhooks — no code, no Make, no servers.
# Zap recipe:
# Trigger: any (Schedule / Webhook / Form)
# Action 1: Webhooks by Zapier → POST
# URL: https://fareof.com/api/search/ai
# Headers: Authorization: Bearer YOUR_FAREOF_KEY
# Payload: { "prompt": "{{trigger.intent}}" }
# Action 2: iterate over data.items → push each into Sheets / Notion / CRM
#
# Same pattern for /api/verify (single email) — wire it to a Typeform
# submission to score+save leads in real time.Want a deeper integration? Hit [email protected] with the tool name — we usually publish a new recipe within a week.
Webhooks
fareof receives webhooks from DodoPayments at POST /api/webhooks/dodo for billing events (subscription created/updated/canceled). Signature is verified with standardwebhooks using DODO_WEBHOOK_KEY. Outbound webhooks (account → your servers) are not yet available.
Changelog
- API keys: mint, list, revoke under
/app/settings/api-keys. Keys hashed with sha-256 + pepper. - Bearer token auth on all
/api/*endpoints (in addition to the existing cookie session). - Public docs at
/docswith quickstart + endpoint reference + this changelog.
- Cache-Control TTL dropped from 1 year to 5 minutes (with stale-while-revalidate).
- metadataBase set to https://fareof.com — OG/Twitter cards no longer broken.
- Sitemap regenerated as
app/sitemap.ts; robots.txt cleaned up. - Security headers (HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy) added globally.
- Auth pages now
noindex. - JSON-LD: SoftwareApplication, FAQPage, Product+Offer, BreadcrumbList shipped.
- New
/aboutpage; metadata on/privacy /terms /refund.
- Production deploy: ems server (Ubuntu 24.04, 64GB RAM, NVMe).
- Postgres 16 + pgvector + pg_trgm provisioned, tuned for the box.
- Cloudflare Tunnel terminating HTTPS at the edge → systemd Next.js + Fastify on the box.
- Architecture: same-origin (no
api.fareof.com) so cookies flow without cross-subdomain config.
- SuperAdmin panel at
/admin: users, organizations, plans CRUD. - AI prompt search via z.ai; triple-verified emails through the fareof verifier.
- Lead lists + bulk verification + CSV export.
- DodoPayments billing (test mode) on the four-tier plan ladder ($0 / $40 / $150 / $400).
- Email verification + password reset via SMTP (Brevo).
