Local Businesses

curl --request POST \
  --url https://win.oneshotagent.com/v1/tools/find/business \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "address": "<string>",
  "city": "<string>",
  "region": "<string>",
  "postal_code": "<string>",
  "phone": "<string>",
  "category": [
    "<string>"
  ],
  "keywords": [
    "<string>"
  ],
  "location": [
    "<string>"
  ],
  "min_rating": 123,
  "min_review_count": 123,
  "is_chain": true,
  "operating_status": {},
  "has_domain": true,
  "limit": 123
}
'

import requests

url = "https://win.oneshotagent.com/v1/tools/find/business"

payload = {
    "name": "<string>",
    "address": "<string>",
    "city": "<string>",
    "region": "<string>",
    "postal_code": "<string>",
    "phone": "<string>",
    "category": ["<string>"],
    "keywords": ["<string>"],
    "location": ["<string>"],
    "min_rating": 123,
    "min_review_count": 123,
    "is_chain": True,
    "operating_status": {},
    "has_domain": True,
    "limit": 123
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    address: '<string>',
    city: '<string>',
    region: '<string>',
    postal_code: '<string>',
    phone: '<string>',
    category: ['<string>'],
    keywords: ['<string>'],
    location: ['<string>'],
    min_rating: 123,
    min_review_count: 123,
    is_chain: true,
    operating_status: {},
    has_domain: true,
    limit: 123
  })
};

fetch('https://win.oneshotagent.com/v1/tools/find/business', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://win.oneshotagent.com/v1/tools/find/business",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'address' => '<string>',
    'city' => '<string>',
    'region' => '<string>',
    'postal_code' => '<string>',
    'phone' => '<string>',
    'category' => [
        '<string>'
    ],
    'keywords' => [
        '<string>'
    ],
    'location' => [
        '<string>'
    ],
    'min_rating' => 123,
    'min_review_count' => 123,
    'is_chain' => true,
    'operating_status' => [
        
    ],
    'has_domain' => true,
    'limit' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://win.oneshotagent.com/v1/tools/find/business"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"address\": \"<string>\",\n  \"city\": \"<string>\",\n  \"region\": \"<string>\",\n  \"postal_code\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"category\": [\n    \"<string>\"\n  ],\n  \"keywords\": [\n    \"<string>\"\n  ],\n  \"location\": [\n    \"<string>\"\n  ],\n  \"min_rating\": 123,\n  \"min_review_count\": 123,\n  \"is_chain\": true,\n  \"operating_status\": {},\n  \"has_domain\": true,\n  \"limit\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://win.oneshotagent.com/v1/tools/find/business")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"address\": \"<string>\",\n  \"city\": \"<string>\",\n  \"region\": \"<string>\",\n  \"postal_code\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"category\": [\n    \"<string>\"\n  ],\n  \"keywords\": [\n    \"<string>\"\n  ],\n  \"location\": [\n    \"<string>\"\n  ],\n  \"min_rating\": 123,\n  \"min_review_count\": 123,\n  \"is_chain\": true,\n  \"operating_status\": {},\n  \"has_domain\": true,\n  \"limit\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://win.oneshotagent.com/v1/tools/find/business")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"address\": \"<string>\",\n  \"city\": \"<string>\",\n  \"region\": \"<string>\",\n  \"postal_code\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"category\": [\n    \"<string>\"\n  ],\n  \"keywords\": [\n    \"<string>\"\n  ],\n  \"location\": [\n    \"<string>\"\n  ],\n  \"min_rating\": 123,\n  \"min_review_count\": 123,\n  \"is_chain\": true,\n  \"operating_status\": {},\n  \"has_domain\": true,\n  \"limit\": 123\n}"

response = http.request(request)
puts response.read_body

POST

tools

find

business

Local Businesses

curl --request POST \
  --url https://win.oneshotagent.com/v1/tools/find/business \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "address": "<string>",
  "city": "<string>",
  "region": "<string>",
  "postal_code": "<string>",
  "phone": "<string>",
  "category": [
    "<string>"
  ],
  "keywords": [
    "<string>"
  ],
  "location": [
    "<string>"
  ],
  "min_rating": 123,
  "min_review_count": 123,
  "is_chain": true,
  "operating_status": {},
  "has_domain": true,
  "limit": 123
}
'

import requests

url = "https://win.oneshotagent.com/v1/tools/find/business"

payload = {
    "name": "<string>",
    "address": "<string>",
    "city": "<string>",
    "region": "<string>",
    "postal_code": "<string>",
    "phone": "<string>",
    "category": ["<string>"],
    "keywords": ["<string>"],
    "location": ["<string>"],
    "min_rating": 123,
    "min_review_count": 123,
    "is_chain": True,
    "operating_status": {},
    "has_domain": True,
    "limit": 123
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    address: '<string>',
    city: '<string>',
    region: '<string>',
    postal_code: '<string>',
    phone: '<string>',
    category: ['<string>'],
    keywords: ['<string>'],
    location: ['<string>'],
    min_rating: 123,
    min_review_count: 123,
    is_chain: true,
    operating_status: {},
    has_domain: true,
    limit: 123
  })
};

fetch('https://win.oneshotagent.com/v1/tools/find/business', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://win.oneshotagent.com/v1/tools/find/business",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'address' => '<string>',
    'city' => '<string>',
    'region' => '<string>',
    'postal_code' => '<string>',
    'phone' => '<string>',
    'category' => [
        '<string>'
    ],
    'keywords' => [
        '<string>'
    ],
    'location' => [
        '<string>'
    ],
    'min_rating' => 123,
    'min_review_count' => 123,
    'is_chain' => true,
    'operating_status' => [
        
    ],
    'has_domain' => true,
    'limit' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://win.oneshotagent.com/v1/tools/find/business"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"address\": \"<string>\",\n  \"city\": \"<string>\",\n  \"region\": \"<string>\",\n  \"postal_code\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"category\": [\n    \"<string>\"\n  ],\n  \"keywords\": [\n    \"<string>\"\n  ],\n  \"location\": [\n    \"<string>\"\n  ],\n  \"min_rating\": 123,\n  \"min_review_count\": 123,\n  \"is_chain\": true,\n  \"operating_status\": {},\n  \"has_domain\": true,\n  \"limit\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://win.oneshotagent.com/v1/tools/find/business")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"address\": \"<string>\",\n  \"city\": \"<string>\",\n  \"region\": \"<string>\",\n  \"postal_code\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"category\": [\n    \"<string>\"\n  ],\n  \"keywords\": [\n    \"<string>\"\n  ],\n  \"location\": [\n    \"<string>\"\n  ],\n  \"min_rating\": 123,\n  \"min_review_count\": 123,\n  \"is_chain\": true,\n  \"operating_status\": {},\n  \"has_domain\": true,\n  \"limit\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://win.oneshotagent.com/v1/tools/find/business")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"address\": \"<string>\",\n  \"city\": \"<string>\",\n  \"region\": \"<string>\",\n  \"postal_code\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"category\": [\n    \"<string>\"\n  ],\n  \"keywords\": [\n    \"<string>\"\n  ],\n  \"location\": [\n    \"<string>\"\n  ],\n  \"min_rating\": 123,\n  \"min_review_count\": 123,\n  \"is_chain\": true,\n  \"operating_status\": {},\n  \"has_domain\": true,\n  \"limit\": 123\n}"

response = http.request(request)
puts response.read_body

Business Search finds main-street businesses by category and location. Business Resolve turns a business name and address into its website domain, phone and operating status. Both are async: POST, get a request_id, poll GET /v1/requests/{request_id}. Both return the same LocalResult shape.

Both endpoints accept optional memo (≤ 1000 chars) and decisionContext (object) body fields, stored on the receipt. See Audit Trail.

Business Resolve

POST /v1/tools/resolve/business

string

required

Business name, e.g. "TAQUERIA LOS AMIGOS"

string

Street address, e.g. "2334 Mission St"

string

City

string

State / province. Not locating on its own.

string

Postal code

string

Phone number, the strongest match signal after the name.

name plus at least one of address, city, postal_code, or phone is required.

curl -X POST https://win.oneshotagent.com/v1/tools/resolve/business \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64 x402 payment>" \
  -d '{
    "name": "Franklin Barbecue",
    "address": "900 E 11th St",
    "city": "Austin",
    "region": "TX"
  }'

Response Structure

{
  "status": "completed",
  "result": {
    "found": true,
    "confidence": 0.97,
    "result": {
      "domain": "franklinbbq.com",
      "operating_status": "open",
      "confidence": 0.97,
      "phone": "(512) 653-1187",
      "category": "Barbecue restaurant",
      "is_chain": null,
      "name": "Franklin Barbecue",
      "address": "900 E 11th St, Austin, TX 78702",
      "socials": {},
      "review_count": 8412,
      "rating": 4.7,
      "id": "loc_3f1c9a2b7d8e4f60",
      "website": "https://franklinbbq.com/",
      "latitude": 30.2701,
      "longitude": -97.7313
    },
    "candidates_considered": 4
  }
}

A miss is a completed job with found: false, result: null and the best confidence seen, never an error. A candidate below the threshold is returned as closest_match.

confidence is 0–1, weighted over the signals you supplied. found requires confidence ≥ 0.65 and name similarity ≥ 0.5.

Business Search

POST /v1/tools/find/business Finds businesses by category and location. Flat price per search, not per result.

string[]

Business categories, e.g. ["hvac contractor", "dental practice"] (max 50). category or keywords is required.

string[]

Free-text keywords (max 50)

string[]

required

Cities, neighborhoods or "City, ST", e.g. ["Austin, TX", "Round Rock, TX"] (max 50)

number

Minimum star rating, 0–5

number

Minimum review count

boolean

true keeps only detected chains; false drops them. Rows with is_chain: null pass a false filter.

'open' | 'any'

default:"open"

open drops businesses detected as closed

boolean

true returns only rows with a website domain

number

default:"100"

Max results, 1–500. See truncated below.

curl -X POST https://win.oneshotagent.com/v1/tools/find/business \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64 x402 payment>" \
  -d '{
    "category": ["hvac contractor"],
    "location": ["Austin, TX"],
    "has_domain": true,
    "is_chain": false,
    "limit": 50
  }'

Response Structure

{
  "status": "completed",
  "result": {
    "results": [
      {
        "domain": "example-hvac.com",
        "operating_status": "open",
        "phone": "(512) 555-0142",
        "category": "HVAC contractor",
        "is_chain": null,
        "name": "Example Heating & Air",
        "address": "4100 Example Ln, Austin, TX 78744",
        "socials": {},
        "review_count": 212,
        "rating": 4.8,
        "id": "loc_a91b2c3d4e5f6a70",
        "website": "https://example-hvac.com/",
        "latitude": 30.19,
        "longitude": -97.75
      }
    ],
    "total_found": 50,
    "truncated": false,
    "filters": { "category": ["hvac contractor"], "location": ["Austin, TX"], "has_domain": true, "is_chain": false, "limit": 50 }
  }
}

A search yields up to ~60 rows. If it stops before limit, truncated is true. Split large territories.

The LocalResult shape

Field	Type	Notes
`domain`	string \| null	Bare website domain, or `null` when the business only has a social or aggregator page (see `socials`). Pass to `lookup/person-email` as `company_domain`.
`operating_status`	`open` \| `closed`	Best-effort closure detection.
`confidence`	number	Resolve results only.
`phone`	string \| null
`category`	string \| null	Free-text category.
`is_chain`	`true` \| null	`true` for a known national brand or a name at 3+ addresses in the result set; `null` when not detected, never `false`.
`name`, `address`	string
`socials`	object	Platform → URL, e.g. `{ "facebook": "https://facebook.com/…" }`.
`review_count`, `rating`	number \| null
`id`	string	Stable across runs. Dedupe on this.
`website`, `latitude`, `longitude`		Raw website URL and coordinates when available.

Not returned

Licence issue date, NPI taxonomy, FMCSA authority type or NAICS code.

SDK

const territory = await agent.businessFind({
  category: ['hvac contractor'],
  location: ['Austin, TX'],
  has_domain: true,
  is_chain: false,
  limit: 50,
});

const match = await agent.businessResolve({
  name: 'TAQUERIA LOS AMIGOS',
  address: '2334 Mission St',
  city: 'San Francisco',
  region: 'CA',
});
if (match.found) {
  const { email } = await agent.personEmail({ full_name: 'Owner Name', company_domain: match.result!.domain! });
}

See Pricing.

Overview

Compute

Data

Monitoring

Research & Enrich

Messaging

Web & Browser

Build

Commerce

Account & billing

Other

Local Businesses

Business Resolve

Response Structure

Business Search

Response Structure

The LocalResult shape

Not returned

SDK

​Business Resolve

​Response Structure

​Business Search

​Response Structure

​The LocalResult shape

​Not returned

​SDK

Business Resolve

Response Structure

Business Search

Response Structure

The LocalResult shape

Not returned

SDK