Doott API Docs — Data Fetching Reference

🚀 Getting Started

Everything you need to make your first API call in under 2 minutes.

QUICK START · cURL

# 1. Login to get Bearer token
curl -X POST https://doott.jaqyi.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"yourpassword"}'

# 2. Query companies with the returned token
curl -G https://doott.jaqyi.com/api/final-companies \
  -H "Authorization: Bearer <TOKEN>" \
  --data-urlencode "f_city=Mumbai" \
  --data-urlencode "f_has_email=true" \
  --data-urlencode "limit=25"

🔐 Authentication

All data endpoints require a Bearer JWT token in the Authorization header.

Bearer Token (JWT)

Obtain a token via POST /api/auth/login. Attach it to every data request:

HEADER

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

⚠️

Tokens are org-scoped. Never expose them in client-side code or public repos.

🔍 Filter System

All data APIs share a unified filter system. Use f_ prefix + column name + optional operator suffix as query params.

ℹ️

Filter keys are validated against live DB schema. Unknown columns are silently ignored — SQL injection is not possible.

🏢 Companies Database

Query final.companies — millions of verified business records with contact details, location, and industry.

GET/api/final-companies Paginated company list with filters▶

Parameters

Example

Response

Parameter	Type	Status	Description
page	integer	Optional	Page number (default: 1)
limit	integer	Optional	Records per page, max 200 (default: 50)
search	string	Optional	Semantic / full-text search on business_name using vector embeddings
sort_by	string	Optional	Column name to sort by
sort_dir	string	Optional	`asc` or `desc` (default: asc)
f_business_name	string	Optional	Business name contains filter
f_city	string	Optional	City filter (BTree indexed, fast prefix match)
f_state	string	Optional	State / region filter
f_pincode	string	Optional	Exact pincode / ZIP code match
f_industry	string	Optional	Industry category contains filter
f_domain	string	Optional	Exact domain match (e.g. `acme.com`)
f_website	string	Optional	Website URL contains filter
f_has_email	boolean	Optional	`true` = only records with emails; `false` = without
f_has_phone	boolean	Optional	`true` = only records with phone numbers
country	string	Optional	`india` or `usa` — geographic pre-filter

cURL

# Mumbai food companies with verified emails
curl -G https://doott.jaqyi.com/api/final-companies \
  -H "Authorization: Bearer <TOKEN>" \
  --data-urlencode "f_city=Mumbai" \
  --data-urlencode "f_industry=Food" \
  --data-urlencode "f_has_email=true" \
  --data-urlencode "limit=50"

JavaScript · fetch

const res = await fetch(
  `https://doott.jaqyi.com/api/final-companies?${new URLSearchParams({
    f_city:'Mumbai', f_industry:'Food', f_has_email:'true', limit:'50'
  })}`,
  { headers: { Authorization: `Bearer ${token}` } }
);
const { records, total, pages } = await res.json();

recordsarrayCompany objects — all non-hidden DB columns returned

totalintegerTotal matching count (capped at 100,001 for filtered queries)

pageintegerCurrent page

pagesintegerTotal pages

sourcestringAlways "cloud_sql"

200 OK · JSON

{
  "records": [{
    "business_name": "Quirch Foods",
    "industry":      "Manufacturing",
    "phone":         "+13056913535",
    "emails":        "{brian.rumble@quirchfoods.com,john@quirchfoods.com}",
    "website":       "www.quirchfoods.com",
    "city":          "Medley", "state": "FL"
  }],
  "total": 12847, "page": 1, "pages": 257, "source": "cloud_sql"
}

GET/api/final-companies/statsTotal record count (Redis cached 5 min)▶

Response

200 OK · JSON

{ "total": 5820000, "source": "cloud_sql", "table": "companies" }

GET/api/final-companies/categoriesTop 100 industries with counts (cached 24h)▶

Response

200 OK · JSON

[
  { "name": "Manufacturing", "count": 420000 },
  { "name": "Food Production", "count": 318000 }
]

GET/api/final-companies/citiesTop 500 cities with business counts (cached 6h)▶

Response

200 OK · JSON

{ "cities": [{ "name": "Mumbai", "state": "MH", "count": 84200 }], "total": 500 }

GET/api/final-companies/columnsList all queryable columns▶

Response

200 OK · JSON

{ "columns": ["business_name", "industry", "phone", "emails", "website", "city", "state", "address", "pincode", ...], "table": "companies" }

GET/api/final-companies/healthDatabase connectivity check▶

Response

200 OK · JSON

{ "ok": true, "source": "cloud_sql", "serverTime": "2026-09-23T08:23:11Z", "totalRecords": 5820000 }

👤 People Database

Query final.people — 43M+ individual contacts with job titles, emails, phones, and location.

GET/api/final-peoplePaginated people list with filters▶

Parameters

Example

Response

Parameter	Type	Status	Description
page	integer	Optional	Page (default: 1)
limit	integer	Optional	Max 200, default 50
search	string	Optional	Semantic search on full_name via vector embeddings
sort_by / sort_dir	string	Optional	Column + `asc`/`desc`
f_city	string	Optional	City (BTree indexed)
f_state	string	Optional	State / region
f_pincode	string	Optional	Exact ZIP / pincode
f_job_title	string	Optional	Job title contains (e.g. `CEO`, `Founder`, `HR Manager`)
f_location	string	Optional	Free-text location contains
f_has_email	boolean	Optional	`true` = only people with emails
f_has_phone	boolean	Optional	`true` = only people with phone numbers
country	string	Optional	`india` or `usa`

cURL

# CEOs in Bangalore with verified emails
curl -G https://doott.jaqyi.com/api/final-people \
  -H "Authorization: Bearer <TOKEN>" \
  --data-urlencode "f_job_title=CEO" \
  --data-urlencode "f_city=Bangalore" \
  --data-urlencode "f_has_email=true" \
  --data-urlencode "country=india" \
  --data-urlencode "limit=100"

200 OK · JSON

{
  "records": [{
    "full_name":  "Rahul Sharma",
    "first_name": "Rahul",
    "last_name":  "Sharma",
    "job_title":  "CEO",
    "emails":     "{rahul@startup.in}",
    "phone":      "+919812345678",
    "city":       "Bangalore", "state": "Karnataka"
  }],
  "total": 43200000, "page": 1, "pages": 864000
}

ℹ️

first_name / last_name are auto-derived from full_name when not stored separately.

GET/api/final-people/statsTotal people count▶

Response

200 OK

{ "total": 43200000, "source": "cloud_sql", "table": "people" }

GET/api/final-people/categoriesTop 100 job titles with counts (cached 24h)▶

Response

200 OK

[
  { "name": "CEO", "count": 1240000 },
  { "name": "Founder", "count": 980000 }
]

GET/api/final-people/citiesTop 500 cities by people count (cached 6h)▶

Response

200 OK

{ "cities": [{ "name": "New York", "state": "NY", "count": 2400000 }], "total": 500 }

📧 People — Email Filtered

Identical to /api/final-people but pre-filtered — every record is guaranteed to have an email. Same params, same pagination.

✅

Every record returned has at least one non-empty verified email column.

GET/api/final-people-emailPeople with verified email — paginated▶

Example

Response

cURL

# India Founders with emails
curl -G https://doott.jaqyi.com/api/final-people-email \
  -H "Authorization: Bearer <TOKEN>" \
  --data-urlencode "f_job_title=Founder" \
  --data-urlencode "country=india" \
  --data-urlencode "limit=100"

200 OK · JSON

{ "records": [{ "full_name": "Priya Mehta", "emails": "{priya@startup.in}", ... }], "total": 8200000 }

📞 People — Phone Filtered

Identical to /api/final-people but pre-filtered — every record is guaranteed to have a phone number.

✅

Every record returned has at least one non-empty phone number column.

GET/api/final-people-numberPeople with phone number — paginated▶

Example

cURL

curl -G https://doott.jaqyi.com/api/final-people-number \
  -H "Authorization: Bearer <TOKEN>" \
  --data-urlencode "f_job_title=HR Manager" \
  --data-urlencode "f_city=Delhi" \
  --data-urlencode "limit=50"

✅ Email Verification

Real-time email validation with 90-day Redis+Postgres caching. Supports single and bulk CSV verification.

POST/api/verify-emailVerify a single email address▶

Body

Example

Response

Field	Type	Status	Description
email	string	Required	Email address to verify
force_refresh	boolean	Optional	Bypass 90-day cache and re-verify (default: false)
skip_smtp	boolean	Optional	Skip SMTP handshake — faster but less thorough

cURL

curl -X POST https://doott.jaqyi.com/api/verify-email \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"email":"john@example.com"}'

200 OK · JSON

{
  "email":       "john@example.com",
  "valid":       true,
  "deliverable": true,
  "disposable":  false,
  "mx_found":    true,
  "smtp_check":  true,
  "cached":      false
}

POST/api/verify-email/batchBulk verify — CSV upload or JSON list (async job)▶

Body

Example

Response

Field	Type	Status	Description
file	File	Option A	CSV file upload via multipart/form-data (max 25 MB)
emails	array	Option B	JSON array of email strings
csv	string	Option C	Raw CSV content as string in request body
force_refresh	boolean	Optional	Bypass cache for all emails in batch

cURL · JSON Array

curl -X POST https://doott.jaqyi.com/api/verify-email/batch \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"emails":["a@example.com","b@test.org","c@domain.com"]}'

cURL · CSV File Upload

curl -X POST https://doott.jaqyi.com/api/verify-email/batch \
  -H "Authorization: Bearer <TOKEN>" \
  -F "file=@/path/to/emails.csv"

ℹ️

Batch jobs are asynchronous. Poll GET /api/verify-email/batch/:jobId until status === "done".

202 Accepted · JSON

{ "success": true, "jobId": "job_a1b2c3d4", "status": "pending", "total": 250 }

GET/api/verify-email/batch/:jobIdPoll batch job status & results▶

Response

200 OK · JSON (completed)

{
  "jobId":       "job_a1b2c3d4",
  "status":      "done",
  "total":       250, "processed": 250,
  "valid":       198, "invalid": 52,
  "downloadUrl": "/api/verify-email/batch/job_a1b2c3d4/download"
}

🔑 Authentication API

Register, login, and manage user sessions.

POST/api/auth/registerCreate new account▶

Body

Example

Field	Type	Status	Description
name	string	Required	Full name
email	string	Required	Email address
password	string	Required	Minimum 8 characters
orgName	string	Optional	Organization / company name

cURL

curl -X POST https://doott.jaqyi.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","email":"jane@company.com","password":"secure123","orgName":"Acme Corp"}'

POST/api/auth/loginLogin and receive Bearer token▶

Example

Response

cURL

curl -X POST https://doott.jaqyi.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@company.com","password":"secure123"}'

200 OK · JSON

{
  "success": true,
  "token":   "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": { "id": "usr_xxx", "name": "Jane Doe", "email": "jane@company.com" },
  "org":  { "id": "org_yyy", "name": "Acme Corp" }
}

📋 HTTP Status Codes

Standard HTTP codes used across all endpoints.

Code	Meaning	When to Expect
200 OK	Success	Request completed, data returned
201 Created	Created	New resource created (e.g. user account)
202 Accepted	Async Started	Job accepted (e.g. batch email verification)
400 Bad Request	Invalid Input	Missing required fields or validation error
401 Unauthorized	Auth Required	Missing or invalid Bearer token
403 Forbidden	Access Denied	Token valid but lacks permissions
429 Too Many Requests	Rate Limited	Request quota exceeded — implement back-off
500 Server Error	Internal Error	Unexpected server-side failure
503 Unavailable	DB Unreachable	Database connection failed

⚡ Rate Limits

Per-IP rate limits protect the platform and ensure fair usage for all users.

Endpoint Group	Limit	Window
/api/final-companies, /api/final-people*	300 requests	per 15 minutes per IP
/api/verify-email (single)	100 requests	per 15 minutes per IP
/api/verify-email/batch	10 requests	per 15 minutes per IP
/api/auth/register, /api/auth/login	20 requests	per 15 minutes per IP
All other /api/* endpoints	500 requests	per 15 minutes per IP

⚠️

When rate limited you'll receive 429 Too Many Requests. Use exponential back-off before retrying.

Data Fetching API Reference

Bearer Token (JWT)

Operator Suffixes