---
title: "Turn local businesses into leads"
method: POST
path: "/api/v2/local-business-search/convert"
tags: ["LocalBusiness"]
---

# Turn local businesses into leads

`POST /api/v2/local-business-search/convert`

## Request

- Base URL: `https://api.instantly.ai`
- URL: `https://api.instantly.ai/api/v2/local-business-search/convert`
- Auth: HTTP bearer

Starts converting the businesses matching `filters` into up to `count` leads, each with a verified email, in one lead list or one campaign. Runs in the background: read its progress with `GET /local-business-search/convert/{id}`. Costs 2 credits per lead created; businesses without an email cost nothing, and a workspace may scan up to 20000 of them a day (429 `local_business_convert_daily_limit`). Answers 402 when the balance cannot pay for one lead. A request repeated with the same `idempotency_key` returns the same conversion. `campaign_name` also needs the `campaigns:create` scope.


Requires one of the following scopes: `supersearch_enrichments:create`, `supersearch_enrichments:all`, `all:create`, `all:all`

## Request body

- object
  - `filters` object, required: A search needs a category, a query or a name, and a location (a city, a state, or `lat`/`long`).
    - `query` string, nullable: Free text, used only when no category is set
    - `categories` string[], nullable: Exact business categories
    - `location` object, nullable: A city or state, or a point and a radius. Build it from `GET /local-business-search/places`.
      - `label` string, nullable: What the location filter shows
      - `country` string, nullable
      - `state` string, nullable
      - `city` string, nullable
      - `lat` number, nullable
      - `long` number, nullable
      - `radius_km` number, nullable: Searched around `lat`/`long`
    - `keywords` string[], nullable: Ranks businesses that mention these first
    - `name` string, nullable: Part of the business name
    - `min_rating` number, nullable: 0 to 5
    - `max_rating` number, nullable: 0 to 5
    - `min_reviews` number, nullable
    - `max_reviews` number, nullable
    - `min_locations` integer, nullable
    - `max_locations` integer, nullable: 1 leaves chains and franchises out
    - `exclude_keywords` string[], nullable
    - `opened_within_months` integer, nullable: Only businesses that opened within this many months
    - `updated_within_months` integer, nullable: Only records refreshed within this many months
  - `count` integer, required
  - `campaign_id` string, uuid
  - `campaign_name` string: Creates a draft campaign with this name and the default schedule, and adds the leads to it.
  - `list_id` string, uuid
  - `list_name` string
  - `idempotency_key` string, required

## Response `200`

Default Response

- object
  - `job` object, required
    - `id` string, uuid, required: Read the conversion with `GET /local-business-search/convert/{id}`
    - `status` 'running' | 'done' | 'out_of_credits' | 'daily_limit' | 'failed', required: `running` until the conversion ends
    - `requested` integer, required: Leads asked for
    - `scanned` integer, required: Businesses read so far
    - `created` integer, required: Leads created, each with an email; each costs 2 credits
    - `lookup_pending` integer, required: Businesses whose email is being looked up right now
    - `verify_pending` integer, required: Emails being verified before the leads are written
    - `verifying_count` integer, required: Leads of a finished conversion still being verified
    - `credits_spent` number, required
    - `list_id` string, uuid, nullable, required
    - `campaign_id` string, uuid, nullable, required
    - `updated_at` number, required: Unix time in milliseconds
    - `error_code` string
    - `pool_exhausted` boolean: Every matching business was read: a conversion that ended short could not have found more

## Other responses

- `202`: Default Response
- `400`: The request is invalid (e.g. missing required fields, invalid field values, or an invalid state for the operation)
- `401`: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)
- `402`: Default Response
- `403`: Default Response
- `404`: The requested resource was not found
- `429`: Default Response

## Changes

- **2026-11-03** `c781051105a8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/instantly/apis/api-explorer/changes/api/v2/local-business-search/convert/post.md)

---

[API](https://skmtc.dev/instantly/apis/api-explorer.md) - [All operations](https://skmtc.dev/instantly/apis/api-explorer/llms.txt) - [OpenAPI document](https://skmtc.dev/instantly/apis/api-explorer/revisions/406ab2c4f714?raw)