Fullpilot

API Reference

Fullpilot API

Parse a natural-language prompt into a search query, search local businesses with it, then unlock or enrich a company's contact data. Every request is a single authenticated POST.

Base URL https://api.fullpilot.com

Set your API key

export FULLPILOT_API_KEY="fp_live_..."

Authentication

Authenticate with a bearer token

Fullpilot API requests use Bearer token authentication. Keep your key server-side and export it as an environment variable before making requests.

Credit behavior

One credit unlocks one company record with its available email and phone data. Parsing and searching are free.

Set your API key

export FULLPILOT_API_KEY="fp_live_..."

Parse a prompt

POST/v1/search/parse

Send a plain-English description of the businesses you want. Parse returns a structured query object (the exact shape the search endpoint accepts), so you can preview, tweak, and store it before running a search.

Parameters

promptstringbodyrequired

Natural-language description of the businesses to find, e.g. "med spas in Texas with strong reviews and a website".

curl https://api.fullpilot.com/v1/search/parse \
  -H "Authorization: Bearer $FULLPILOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Find med spas in Texas with strong reviews, a website, and owner contact data."
  }'

Response

{
  "query": {
    "category": "med spa",
    "location": "Texas, US",
    "filters": {
      "rating_min": 4.5,
      "reviews_min": 25,
      "website_status": "active",
      "has_contact_data": true
    }
  }
}
Primary

Unlock contact info

POST/v1/unlock

The primary Fullpilot route. Reveal an accurate email or phone for one business from a search result. One credit unlocks one record; a record your workspace already unlocked is returned for free.

Parameters

business_idstringbodyrequired

Id of the business to unlock, from a search result, e.g. "biz_9qH2a1".

field"email" | "phone"bodyrequired

Which contact field to reveal.

curl https://api.fullpilot.com/v1/unlock \
  -H "Authorization: Bearer $FULLPILOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "business_id": "biz_9qH2a1",
    "field": "email"
  }'

Response

{
  "business_id": "biz_9qH2a1",
  "status": "unlocked",
  "field": "email",
  "email": "owner@lonestaraesthetics.com",
  "phone": "+1 512-555-0142",
  "email_quality": "owner_personal",
  "owner_name": "Jane Okafor"
}

Unlock in bulk

POST/v1/unlock/batch

Unlock a whole result set in one call. Pass an explicit `business_ids` array, or a `results_id` from /v1/search (optionally capped with `limit`) and Fullpilot resolves the stored set. Every business returns a status; records already unlocked by your workspace are reused for free, so only new unlocks are charged.

Parameters

results_idstringbodyoptional

Id returned by /v1/search. Unlocks the businesses in that result set. Use this OR business_ids.

business_idsstring[]bodyoptional

Explicit business ids to unlock. Use this OR results_id.

field"email" | "phone"bodyrequired

Which contact field to reveal across the batch.

limitintegerbodyoptional

With results_id, cap how many businesses to unlock.

curl https://api.fullpilot.com/v1/unlock/batch \
  -H "Authorization: Bearer $FULLPILOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "results_id": "res_9f2c8a1b4e7d",
    "field": "email",
    "limit": 25
  }'

Response

{
  "object": "list",
  "field": "email",
  "data": [
    {
      "business_id": "biz_9qH2a1",
      "status": "unlocked",
      "email": "owner@lonestaraesthetics.com",
      "email_quality": "owner_personal"
    },
    {
      "business_id": "biz_V81kLs",
      "status": "already_unlocked",
      "email": "hello@brightsmiledental.com"
    },
    {
      "business_id": "biz_77Xz2",
      "status": "not_found"
    }
  ],
  "unlocked_count": 1,
  "already_unlocked_count": 1,
  "not_found_count": 1,
  "insufficient_count": 0,
  "lookup_failed_count": 0,
  "credits_charged": 1
}

Enrich a company

POST/v1/enrich

A secondary route for when you already know the business. Provide a domain, company name, or other identifying details and Fullpilot resolves the matching company, returning its profile along with an available email or phone number.

Parameters

domainstringbodyoptional

Company website domain, e.g. "lonestaraesthetics.com". Provide at least one of domain, name, or location.

namestringbodyoptional

Business name to resolve.

locationstringbodyoptional

City, region, or address to disambiguate the match.

curl https://api.fullpilot.com/v1/enrich \
  -H "Authorization: Bearer $FULLPILOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "lonestaraesthetics.com"
  }'

Response

{
  "company": {
    "id": "biz_9qH2a1",
    "name": "Lone Star Aesthetics",
    "category": "med spa",
    "location": "Austin, TX",
    "website": "lonestaraesthetics.com"
  },
  "email": "owner@lonestaraesthetics.com",
  "phone": "+1 512-555-0142"
}

Errors

Use predictable responses

StatusMeaning
400

Invalid request body or unsupported filter.

401

Missing or invalid API key.

402

Not enough credits to unlock a record.

404

Company not found.

429

Rate limit exceeded.

500

Unexpected server error.

503

The contact lookup didn't complete (upstream hiccup). Nothing was charged; retry the request.