Skip to main content

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 */]
}
StatusError codeMeaning
400invalid_bodyRequest body failed Zod validation. issues[] shows which field.
401unauthenticatedMissing/expired session, or invalid Bearer token.
403no_active_organizationCaller has no membership row.
404not_foundResource doesn't exist or belongs to another org.
409too_many_active_keysAlready at 20-key cap. Revoke an old one first.
409plan_in_useTrying to delete a plan with active subscriptions.

Endpoints

Selected endpoints — full reference will land before public launch.

GET/api/me

The authenticated user, their session, and their organizations.

curl https://fareof.com/api/me \
  -H "Authorization: Bearer fareof_live_xxxx"
POST/api/search/companies

Filter 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
  }'
POST/api/search/people

Filter 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
  }'
POST/api/search/ai

Natural-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" }'
POST/api/lists

Create 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" }'
POST/api/verify

Verify 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]" }'
POST/api/lists/:id/verify

Bulk-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"
GET/api/lists/:id/export.csv

Stream 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.csv

Integrations

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.

Salesforce

full guide →

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 → Lead

Sync 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\"}}"
fi

CSV 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)

Make (Integromat)

full guide →

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

v0.4.0feature
  • 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 /docs with quickstart + endpoint reference + this changelog.
v0.3.0seo
  • 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 /about page; metadata on /privacy /terms /refund.
v0.2.0infra
  • 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.
v0.1.0initial
  • 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).