Customer API: search, enrichment and export

Authentication and limits

Create a key in API key settings. Its secret is shown once. Use leads:read for locations, status, results and exports; leads:write for task creation and actions. A workflow doing both needs both scopes. Old keys do not acquire scopes automatically.

Send Authorization: Bearer sk_YOUR_KEY. Keep the secret in a credential store, never a public workflow or URL. Account isolation remains enforced. The production D1 API allows up to 60 requests per minute per account and requires at least 200 ms between requests. Up to three active search/campaign/enrichment tasks share the account concurrency budget.

Every task creation needs an Idempotency-Key containing 8–100 letters, digits, underscores or hyphens. Retry an unchanged request with the same key. Use a fresh key for a new task. Success returns HTTP 202, not completed data.

Discover a supported location

curl "https://ownerclue.com/api/v1/leads/locations?country=US&type=City&q=Phoenix"   -H "Authorization: Bearer $OWNERCLUE_API_KEY"

Use a returned code; do not invent a locationCode. Canadian queries use country=CA. Locations can be narrowed by parentCode and type. This directory returns an array, not a paginated job envelope. Replace the origin in examples with the public app origin you use.

Create a search, then poll

{
  "keyword": "plumber",
  "locationCode": 123456,
  "languageCode": "en",
  "depth": 20
}

POST this body to /api/v1/leads/searches with both headers. The location code above is a placeholder. A successful response has code: 0 and data.id. GET /api/v1/leads/searches/{id} until data.status is completed. queued/running require another poll; failed requires inspecting the error. Do not export an incomplete task.

Routes

Method and path under /api/v1/leads	Purpose
GET /searches, /campaigns, /enrichments	List owned jobs
POST /searches	keyword, locationCode, languageCode, depth; optional exactCategory
POST /campaigns/preview	Preview selected location codes and estimated maximum leads
POST /campaigns	keyword, locations (codes), languageCode, depth, maxLeads
POST /enrichments	rows: [{domain, name?}] or csv string; at most 100 rows
GET /searches/{id}, /campaigns/{id}, /enrichments/{id}	Status and task details
GET /…/{id}/results?limit=100&cursor=…	Results and nextCursor
GET /…/{id}/export?format=full	CSV after completion
POST /campaigns/{id}/pause, /resume, /stop	Campaign control
POST /enrichments/{id}/resume	Resume a paused enrichment

Search depth is 1–700. Campaign depth accepts 20, 50, 100, 300, 500 or 700; select 1–100 location codes and preview the expanded cities before creation. The multi-city guide explains cancellation and deduplication.

Pagination and filters

Job lists and results put items and nextCursor inside data. Keep limit constant across pages, pass the returned cursor unchanged, and stop when nextCursor is null. Results may move during processing because pagination currently uses offsets; read final data after completion. Locations are an exception with a plain array.

Maps results and exports share q, email=true, owner=true, websiteStatus, signal, phoneType and includeExcluded=true filters. The supported signals are no_website, website_unreachable, booking_not_found and reviews_below_20. Export formats are basic, full, gohighlevel, instantly and 1cw. Enrichment results return row outcomes rather than Maps lead filters.

Errors and retry policy

HTTP status	Action
202	Save data.id and poll
400	Fix input, idempotency key, location, credit balance or concurrency condition; inspect message
401	Supply the Bearer header
403	Check key validity, scopes, ownership and export availability
404	Check task ID and account
429	Back off before retrying
503	Capability unavailable; retry only after its availability changes

JSON replies use {code, message, data}; CSV exports return text/csv. Record both HTTP status and code. No task-completion webhook is currently available; use the n8n polling guide. Billing rules apply to API and workspace tasks alike.