leadmarina

Run a live search for local businesses by niche + city (e.g. query 'electrician', location 'Austin, TX'). Returns the first batch immediately with a search_id; more results are found and verified in the background — every email is SMTP-checked and every phone verified with line type + carrier. Spends 1 lead per result. Poll get_search_results until enrichment is 'complete'.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Business niche/category keyword, e.g. 'electrician'."
    },
    "location": {
      "type": "string",
      "description": "City, e.g. 'Austin, TX'. Ignored if location_code is given."
    },
    "location_code": {
      "type": "number",
      "description": "Optional exact location code (skips the city lookup)."
    }
  },
  "required": [
    "query"
  ]
}

{
  "type": "object",
  "properties": {
    "search_id": {
      "type": "string"
    },
    "query": {
      "type": "string"
    },
    "location": {
      "type": [
        "string",
        "null"
      ]
    },
    "delivered_so_far": {
      "type": "number"
    },
    "leads_remaining": {
      "type": "number",
      "description": "Leads spendable now. On a plan with no monthly quota this is what is left in the current 7-day period."
    },
    "enrichment": {
      "type": "string",
      "description": "'pending' until background verification finishes."
    },
    "next_step": {
      "type": "string"
    }
  },
  "required": [
    "search_id",
    "query",
    "delivered_so_far",
    "enrichment"
  ]
}

Fetch a search's leads with verification filled in as enrichment progresses. Poll until enrichment is 'complete'. Each lead includes verified emails (SMTP status), verified phones (line type + carrier), owner name where identified, socials, and the business profile.

{
  "type": "object",
  "properties": {
    "search_id": {
      "type": "string",
      "description": "The search_id returned by search_leads or enrich_domains."
    },
    "limit": {
      "type": "number",
      "description": "Max leads to return (default 25, max 1000)."
    },
    "offset": {
      "type": "number",
      "description": "Pagination offset (default 0)."
    }
  },
  "required": [
    "search_id"
  ]
}

{
  "type": "object",
  "properties": {
    "search_id": {
      "type": "string"
    },
    "query": {
      "type": [
        "string",
        "null"
      ]
    },
    "location": {
      "type": [
        "string",
        "null"
      ]
    },
    "enrichment": {
      "type": "string",
      "description": "'pending' or 'complete'."
    },
    "stage": {
      "type": "string",
      "description": "queued | discovering | enriching | verifying | complete | failed | cancelled. 'verifying' means every row is delivered and contacts are being verified — often the longest phase, not a stall."
    },
    "queue_position": {
      "type": [
        "number",
        "null"
      ],
      "description": "For queued searches, the place in this account's own queue (1 = next)."
    },
    "progress": {
      "type": [
        "object",
        "null"
      ],
      "description": "{ done, total } rows enriched so far."
    },
    "next_offset": {
      "type": [
        "number",
        "null"
      ],
      "description": "Pass as offset to fetch the next page; null on the last page."
    },
    "total_leads": {
      "type": "number"
    },
    "showing": {
      "type": "string",
      "description": "Range shown, e.g. '1–25'."
    },
    "leads_remaining": {
      "type": [
        "number",
        "null"
      ],
      "description": "Leads spendable now. On a plan with no monthly quota this is what is left in the current 7-day period, not a monthly balance."
    },
    "period": {
      "type": [
        "object",
        "null"
      ],
      "description": "On a rate-limited plan: { limit, used, resets_at }. Null on a metered plan."
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "category": {
            "type": [
              "string",
              "null"
            ]
          },
          "website": {
            "type": [
              "string",
              "null"
            ]
          },
          "owner_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "city": {
            "type": [
              "string",
              "null"
            ]
          },
          "state": {
            "type": [
              "string",
              "null"
            ]
          },
          "rating": {
            "type": [
              "number",
              "null"
            ]
          },
          "reviews": {
            "type": [
              "number",
              "null"
            ]
          },
          "emails_data": {
            "description": "Verified emails with SMTP status."
          },
          "phones_data": {
            "description": "Verified phones with line type + carrier."
          },
          "socials": {
            "description": "Social profile links keyed by platform."
          },
          "enrichment_status": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    }
  },
  "required": [
    "search_id",
    "enrichment",
    "total_leads",
    "results"
  ]
}

Already have businesses? Pass up to 10 website domains to run the full enrichment + verification pipeline on them (verified emails + phones, owner name, socials). Costs 1 lead per domain. Returns a search_id to poll with get_search_results.

{
  "type": "object",
  "properties": {
    "domains": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Business domains, e.g. ['acme.com'] (max 10)."
    }
  },
  "required": [
    "domains"
  ]
}

{
  "type": "object",
  "properties": {
    "search_id": {
      "type": "string"
    },
    "enriching": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Domains accepted (balance-capped)."
    },
    "enrichment": {
      "type": "string"
    },
    "next_step": {
      "type": "string"
    }
  },
  "required": [
    "search_id",
    "enriching",
    "enrichment"
  ]
}

Search ALL leads the account has ever collected (across every search) with filters and sorting — no new search is run and no leads are spent. Filter fields include: name, category, city, state, rating, reviews, website, claimed, owner_name, phone_1, email_1, email_status, phone_1_type, google_cid. Operators: contains, not_contains, is, is_not, starts_with, gt, gte, lt, lte, is_empty, is_not_empty, is_true, is_false. Combine rows with conj 'and'/'or'. Example: find rated-4.5+ plumbers in Austin with a verified email: filters=[{field:'category',operator:'contains',value:'plumb'},{field:'city',operator:'is',value:'Austin',conj:'and'},{field:'email_status',operator:'is',value:'safe',conj:'and'}].

{
  "type": "object",
  "properties": {
    "filters": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "operator": {
            "type": "string"
          },
          "value": {
            "type": "string"
          },
          "conj": {
            "type": "string",
            "enum": [
              "and",
              "or"
            ]
          }
        },
        "required": [
          "field",
          "operator"
        ]
      },
      "description": "Filter conditions (optional — omit for everything, newest data first)."
    },
    "sort": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "dir": {
            "type": "number",
            "enum": [
              1,
              -1
            ]
          }
        },
        "required": [
          "id"
        ]
      },
      "description": "Sort keys, e.g. [{id:'reviews',dir:-1}]. Optional."
    },
    "limit": {
      "type": "number",
      "description": "Max leads to return (default 25, max 1000)."
    },
    "cursor": {
      "type": "string",
      "description": "Opaque pagination cursor from a previous call."
    }
  }
}

{
  "type": "object",
  "properties": {
    "total_matching": {
      "type": [
        "number",
        "null"
      ],
      "description": "Exact match count (first page only; absent on later pages)."
    },
    "returned": {
      "type": "number"
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "description": "Pass back as 'cursor' for the next page."
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "category": {
            "type": [
              "string",
              "null"
            ]
          },
          "website": {
            "type": [
              "string",
              "null"
            ]
          },
          "owner_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "city": {
            "type": [
              "string",
              "null"
            ]
          },
          "state": {
            "type": [
              "string",
              "null"
            ]
          },
          "rating": {
            "type": [
              "number",
              "null"
            ]
          },
          "reviews": {
            "type": [
              "number",
              "null"
            ]
          },
          "emails_data": {
            "description": "Verified emails with SMTP status."
          },
          "phones_data": {
            "description": "Verified phones with line type + carrier."
          },
          "socials": {
            "description": "Social profile links keyed by platform."
          },
          "enrichment_status": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    }
  },
  "required": [
    "returned",
    "results"
  ]
}

Push leads into a connected destination: 'close' (CRM — uses the account's saved field mapping), 'ghl' (GoHighLevel sub-account), 'google_sheets' (new spreadsheet, or pass spreadsheet_id for one LeadMarina created before), or a file — 'csv' | 'xlsx' | 'json' (emailed to the account owner + download link). Exports EITHER one search's leads (pass search_id) or the whole library (set all=true, optionally narrowed with the same filters as query_leads). LIMITS PER CALL, which differ by destination because CRMs take one API call per lead: csv/xlsx 50,000 · json 25,000 · google_sheets 5,000 · close/ghl 1,000. For a big library going to a CRM, export csv and import the file instead. If more leads match than the limit, the response sets truncated=true — relay that to the user, the export was partial. Previously exported leads are UPDATED in place (matched by Google CID) — never duplicated; the user's own CRM notes/columns are never touched.

{
  "type": "object",
  "properties": {
    "destination": {
      "type": "string",
      "enum": [
        "close",
        "ghl",
        "google_sheets",
        "csv",
        "xlsx",
        "json"
      ],
      "description": "Where the leads go."
    },
    "search_id": {
      "type": "string",
      "description": "Export this search's leads."
    },
    "all": {
      "type": "boolean",
      "description": "Export the whole library instead of one search."
    },
    "filters": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "With all=true: narrow the library using query_leads-style filter rows."
    },
    "spreadsheet_id": {
      "type": "string",
      "description": "google_sheets only: add to this existing LeadMarina-created sheet instead of a new one."
    }
  },
  "required": [
    "destination"
  ]
}

{
  "type": "object",
  "properties": {
    "exported": {
      "type": "number",
      "description": "Leads sent to the destination."
    },
    "outcome": {
      "type": "string",
      "description": "Human-readable result, e.g. added/updated counts."
    },
    "download_url": {
      "type": "string",
      "description": "File exports only: 7-day download link."
    },
    "file": {
      "type": "string",
      "description": "File exports only: the file name."
    },
    "truncated": {
      "type": "boolean",
      "description": "True when more leads matched than this destination's limit — the export was PARTIAL."
    },
    "limit": {
      "type": "number",
      "description": "The per-call limit that applied, when truncated."
    },
    "warning": {
      "type": "string",
      "description": "Present when truncated: what happened and how to get the rest."
    },
    "note": {
      "type": "string"
    }
  },
  "required": [
    "exported",
    "outcome"
  ]
}

The account's recent searches (id, niche, location, result count, when) — use a search_id with get_search_results or export_leads.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number",
      "description": "Max searches (default 10, max 25)."
    }
  }
}

{
  "type": "object",
  "properties": {
    "searches": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "keyword": {
            "type": [
              "string",
              "null"
            ]
          },
          "location_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "result_count": {
            "type": [
              "number",
              "null"
            ]
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    }
  },
  "required": [
    "searches"
  ]
}

What the account has left, and when it resets. On a plan with a rate limit (no monthly quota) this is the leads left in the current 7-day period; on a metered plan it is the monthly allotment remaining.

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {
    "leads_remaining": {
      "type": "number"
    },
    "plan": {
      "type": "string"
    },
    "period_limit": {
      "type": "number"
    },
    "period_used": {
      "type": "number"
    },
    "period_resets_at": {
      "type": [
        "string",
        "null"
      ]
    },
    "note": {
      "type": "string"
    }
  },
  "required": [
    "leads_remaining",
    "plan"
  ]
}

The account's saved views from the leads table — each a named set of filters the user already built (e.g. 'Roofers with a mobile number'). Returns each view's filter conditions in the exact shape query_leads and export_leads accept, so "export my Hot Leads view to Close" works without rebuilding the filters by hand.

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {
    "count": {
      "type": "number"
    },
    "views": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "filters": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Pass straight to query_leads or export_leads."
          }
        }
      }
    }
  },
  "required": [
    "count",
    "views"
  ]
}

Which export destinations this account has connected (Close, GoHighLevel, Google Sheets) and whether each is ready to receive leads. Check this BEFORE export_leads or create_automation with a CRM destination — those fail if the integration isn't connected, and Close additionally needs one manual export first to save its field mapping. File destinations (csv/xlsx/json) always work and need nothing connected.

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {
    "integrations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "provider": {
            "type": "string"
          },
          "connected": {
            "type": "boolean"
          },
          "ready": {
            "type": "boolean",
            "description": "Connected AND usable as an export destination right now."
          },
          "note": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "integrations"
  ]
}

The account's automations — saved searches that re-run on a schedule and export themselves. Shows each one's niche, cities, cadence, destination, whether it's active, when it next runs, and how the last run went.

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {
    "count": {
      "type": "number"
    },
    "automations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "keyword": {
            "type": "string"
          },
          "cities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "cadence": {
            "type": "string"
          },
          "destination": {
            "type": "string"
          },
          "active": {
            "type": "boolean"
          },
          "next_run_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_run_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_status": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    }
  },
  "required": [
    "count",
    "automations"
  ]
}

Create an automation: re-run a search on a schedule and send the results somewhere automatically. Pass cities as plain strings (e.g. ['Austin, TX', 'Dallas, TX']) — they're resolved for you. IT SPENDS LEADS ON EVERY RUN, one per result, so confirm the niche, cities and cadence with the user before creating one. A destination of 'close', 'ghl' or 'google_sheets' requires that integration to be connected already (Close also needs one manual export first to save its field mapping); 'csv' | 'xlsx' | 'json' emails a file and needs nothing set up. Up to 20 automations, 25 cities each.

{
  "type": "object",
  "properties": {
    "keyword": {
      "type": "string",
      "description": "The niche to search, e.g. 'roofing contractor'."
    },
    "cities": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Cities to search, e.g. ['Austin, TX'] (max 25)."
    },
    "cadence": {
      "type": "string",
      "enum": [
        "once",
        "daily",
        "weekly",
        "monthly",
        "yearly"
      ],
      "description": "How often it repeats."
    },
    "destination": {
      "type": "string",
      "enum": [
        "none",
        "close",
        "ghl",
        "google_sheets",
        "csv",
        "xlsx",
        "json"
      ],
      "description": "Where each run's leads go. 'none' just saves them to the library."
    },
    "spreadsheet_id": {
      "type": "string",
      "description": "google_sheets only: append to this existing LeadMarina-created sheet."
    },
    "start_at": {
      "type": "string",
      "description": "ISO timestamp for the first run. Defaults to now (runs on the next tick, within 15 min)."
    }
  },
  "required": [
    "keyword",
    "cities",
    "cadence"
  ]
}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "keyword": {
      "type": "string"
    },
    "cities": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "cadence": {
      "type": "string"
    },
    "destination": {
      "type": "string"
    },
    "next_run_at": {
      "type": [
        "string",
        "null"
      ]
    },
    "note": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ]
}

Pause an automation (active=false) so it stops running and stops spending leads, or resume it (active=true). Pausing is the safe way to stop an automation you might want back — use delete_automation only when the user wants it gone for good.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The automation id from list_automations."
    },
    "active": {
      "type": "boolean",
      "description": "false to pause, true to resume."
    }
  },
  "required": [
    "id",
    "active"
  ]
}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "active": {
      "type": "boolean"
    },
    "note": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "active"
  ]
}

Permanently delete an automation. This cannot be undone — confirm with the user first, and prefer update_automation with active=false if they only want it to stop for now. Leads already collected by past runs are kept; only the schedule is removed.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The automation id from list_automations."
    }
  },
  "required": [
    "id"
  ]
}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "deleted": {
      "type": "boolean"
    },
    "note": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "deleted"
  ]
}