API Reference

Base URL: https://fareof.com/api. All requests require authentication via Bearer token or session cookie.

Authentication

# Via API key (recommended for automations)
Authorization: Bearer $FAREOF_API_KEY

# Via session cookie (browser-based)
credentials: "include"

Get your API key from Settings.

People Search

POST /api/search/people

Search for people matching filters. Returns paginated results with enrichment level based on your plan.

{
  "seniority": ["cxo", "vp"],
  "department": ["sales", "marketing"],
  "company": {
    "industry": ["software"],
    "country": ["US"],
    "size": ["51-200", "201-500"]
  },
  "limit": 50,
  "page": 1
}

Email Verification — Single

POST /api/verify/single

Verify a single email address. Costs 1 credit.

POST /api/verify/single
{ "email": "[email protected]" }

{
  "success": true,
  "data": {
    "status": "valid",
    "confidence": 95,
    "mxBlock": null,
    "usage": { "used": 1, "limit": 100 }
  }
}

Email Verification — Bulk

POST /api/verify/bulk

Upload a CSV or JSON array for bulk verification (max 50K emails).

# JSON mode
POST /api/verify/bulk
{ "name": "Q2 leads", "emails": ["[email protected]", "[email protected]"] }

# CSV upload mode
POST /api/verify/bulk
Content-Type: multipart/form-data
file: @leads.csv

GET /api/verify/jobs         # list all
GET /api/verify/jobs/:id    # detail + sample
GET /api/verify/jobs/:id/download  # CSV stream

Reveal — Contacts

POST /api/reveal/by-linkedin

Reveal email and phone for a LinkedIn profile. Returns best available contact data or an unavailable status.

POST /api/reveal/by-linkedin
{
  "linkedinUrl": "https://linkedin.com/in/janedoe",
  "firstName": "Jane",
  "lastName": "Doe",
  "fullName": "Jane Doe",
  "currentTitle": "VP of Sales",
  "currentCompany": "Acme Inc"
}

Sequences

POST /api/sequences

Create email sequences for outreach.

POST /api/sequences
{
  "name": "Q2 Outreach",
  "steps": [
    { "waitDays": 0, "subject": "Hi {{first_name}}", "body": "..." },
    { "waitDays": 3, "subject": "Following up", "body": "..." }
  ]
}

POST /api/sequences/:id/enroll

Enroll contacts from a list into a sequence.

POST /api/sequences/:id/enroll
{ "listId": "uuid" }

Export

GET /api/lists/:id/export.csv

Export verified contacts as a CSV file.

GET /api/lists/:id/export.csv
Authorization: Bearer $FAREOF_API_KEY

Admin

CRUD /api/admin/verification-servers

Manage email verification provider pool (super-admin only).

GET    /api/admin/verification-servers
POST   /api/admin/verification-servers
PATCH  /api/admin/verification-servers/:id
DELETE /api/admin/verification-servers/:id?force=1
POST   /api/admin/verification-servers/:id/test

Rate Limits

Errors

{
  "success": false,
  "error": "error_code",
  "message": "Human-readable description"
}

Common codes:
- invalid_body     → validation failed
- unauthorized     → missing/invalid API key
- not_found        → resource doesn't exist
- over_limit       → quota exceeded