The Public API

The public API is served from https://api.fullpilot.com and speaks JSON.

Authenticate with an API key in the Authorization header: Authorization: Bearer fp_live_your_key. Every request needs it.

Create and revoke keys in the dashboard under Account settings, on the API keys page. A key is shown once at creation, so copy it then. Keys are stored hashed, and revoking a key takes effect immediately.

POST /v1/search/parse turns a natural-language prompt into a structured query. Send a body like { prompt: "med spas in Texas with 50+ reviews and a website" }.

It returns a structured query (category, location, optional title, and filters) plus an unsupported list of any criteria it could not express, so you know what was dropped.

POST /v1/search runs a search from a structured query. Send { query, limit } where query has category, location, optional title, and filters (rating_min, reviews_min, website_status, has_contact_data). Limit is 1 to 100 and defaults to 25.

The response includes a results_id, a total count, the list of matching companies, and has_more for paging. Contact fields stay locked in search results until you unlock them.

POST /v1/unlock reveals one field for one business. Send { business_id, field } where field is email or phone. The response status is unlocked, already_unlocked, not_found, or insufficient_credits.

POST /v1/unlock/batch unlocks many at once, up to 100 per request. Pass either an explicit business_ids list or a results_id from a search, plus the field. The response summarizes how many were newly unlocked, already unlocked, not found, or skipped for insufficient credits, and how many credits were charged.

For large jobs, an asynchronous batch route accepts up to 1,000 ids, returns a batch_id right away, and lets you poll its status until it completes. As everywhere, you are charged one credit per newly revealed field, and already-unlocked and not-found fields are free.

POST /v1/enrich resolves a company you already know, without running a search first. Send at least one of domain, name, or location, for example { domain: "example.com" }.

It returns the matched company with its available owner contact data. This is the API equivalent of looking up a single business you already have.

There are no hard request-rate limits today, but please be reasonable. The natural guardrails are credits (one per newly revealed field) and the batch caps (100 per synchronous batch, 1,000 per asynchronous batch).

Errors come back as a JSON envelope shaped like { error: { type, message } } with standard HTTP status codes: 400 for bad input, 401 for a missing or invalid key, 402 for insufficient credits, 404 for an unknown business, and 500 for an unexpected error.