Organization.find · SalesBuilder

POST https://api.sb/{your-domain}/organizations/find

Options and prices

You get	Input that selects it	Price	Success rate
Companies that fit your filters	`{"where":{}}`	About 3.8¢ per 100 rows	100% of 185,187 calls
Companies that fit a sentence	`{"question":"…"}`	About 20¢ per 100 rows	99.99% of 38,696 calls
Companies like ones you already have	`{"similarTo":["harborview-pm.com"]}`	About 0.04¢ a row	100% of 738 calls
Companies that run a product	`{"where":{"technologies":["…"]}}`	About $1.00 per 100 rows	100% of 3,320 calls
Companies that raised this month	`{"where":{"event":{"kind":"funded"}}}`	About 4¢ a row	98.8% of 345 calls
Companies hiring for a role	`{"where":{"hiringFor":["…"]}}`	About 5¢ per 100 rows	99.9% of 5,524 calls
Local businesses near a place	`{"where":{"near":{"place":"…"},"category":"…"}}`	About 1¢ per 100 places	99.98% of 1,840,000 calls

Inputs

Name	Type	Default	Meaning
`icp`	`string`	None.	An ICP id; its saved filters fill `where`. Pass one of `icp`, `where`, `question` or `similarTo`.
`where`	`OrganizationFilter`	None.	The filters every Organization call takes. Selects the Companies that fit your filters job.
`where.event`	`{ kind: 'funded' \| 'hiring' \| 'technology-added' \| 'news'; within: string; rounds?: string[] }`	`within: '30d'`	Only companies with this dated fact in the window. With `funded`, list `rounds`, or debt rounds fill the list.
`where.near`	`{ place: string; radiusKm: number }`	`radiusKm: 25`	Local businesses around a place; pair it with `where.category`.
`question`	`string`	None.	Your customer in one sentence. Each row gains `fit` and `evidence`, read from the company’s own site.
`similarTo`	`Hostname[]`	None.	Up to 10 companies you already like; the rows are their lookalikes, best first.
`limit`	`number`	`25`	Rows a page, at most 100. You pay for rows returned, never rows asked for.
`after`	`Cursor`	None.	The cursor from the last page.
`save`	`number`	`0`	Save the first n rows as Prospects. Saving is a write, so it follows the call’s Mode; it is free.
`maxCost`	`number`	`1.00`	The most this call may spend, in USD. Over it, the call is refused before it spends, or stops early with what it has.
`strict`	`boolean`	`false`	Refuse with `filter-unsupported`, at $0, instead of listing an unapplied filter in `ignored`.

Outputs

Field	Type	What `null` means
`organizations`	`Organization[]`	Never null: empty when nothing matched, at $0.
`organizations[].hostname`	`Hostname`	Never null: a company is keyed by its domain.
`organizations[].name`	`string`	Never null.
`organizations[].industry`	`string \| null`	Unknown: no source classifies it.
`organizations[].headcount`	`number \| null`, in people	Unknown, never zero.
`organizations[].country`	`string \| null`, in ISO 3166-1	Unknown.
`organizations[].region`	`string \| null`, in ISO 3166-2	Unknown.
`organizations[].fit`	`{ score: number; verdict: 'strong' \| 'possible' \| 'no' \| 'unknown' }`, in score 0 to 1	Absent without `question`. `unknown` means no quote on the site could be confirmed word for word.
`organizations[].evidence`	`{ quote: string; url: string }[]`	Absent without `question`. Every quote appears verbatim on the page it cites.
`organizations[].similarity`	`{ score: number; reason: string }`	Absent without `similarTo`.
`organizations[].event`	`{ kind: string; date: string; summary: string; url: string }`	Absent without `where.event`.
`organizations[].place`	`{ address: string; phone: string \| null; rating: number \| null; reviews: number \| null }`	Absent without `where.near`.
`organizations[]`	`Observed`	Each row also carries `observedAt` and `method`, and `venue` and `locale` where the reading has them.
`after`	`Cursor`	The last page: there are no more rows.
`total`	`number \| null`, in companies	The source does not report a total.
`ignored`	`string[]`	Never null: empty when every filter you sent was applied.
`cost`	`Cost`, in USD	Never null. In try mode `usd` is 0 and `maxUsd` is what the call would have cost.

Read the result

Field	Value	What it means	What to do
`fit.verdict`	`strong` on fewer than 15 of the first 25 rows	The sentence does not separate your customer from the rest of the industry.	Rewrite the sentence from the words your best calls used before you buy more rows. (a 60% fit floor, our planning number)
`fit.verdict`	`unknown`	No quote on the company’s own pages could be confirmed word for word.	Keep it out of a first batch; it costs the same as a strong row. (the checked-quote rule)
`evidence`	A quote dated in the last 30 days	You have a public reason to write now.	Quote it in the first email; trigger lists are planned to reply at twice the rate. (our planning number, measured by a 50/50 split in month 1)
`ignored`	`fundingStages` listed	Funding stage is the filter routes take least often: fewer than 1 call in 100 reaches a route that applies it.	Ask for `where.event` with `kind: funded` and `rounds` instead; that read applies it on every call. (filter coverage, measured across 463,483 company-search calls)
`event.kind`	`funded`, on a loan or a credit line	Without `rounds`, debt rounds fill a funded list.	Pass `rounds: ['seed', 'series-a']`. (reviews of the funding read)

Effects

Action class

None: it reads, so no approval rule names it

Modes

try: Runs the read and returns real rows; nothing is saved and nothing is billed.
send: Returns a pending Action at once; its Event carries the rows when the read finishes.
do: Waits for the read and returns the rows, billed per result.

Idempotency

The same Idempotency-Key with the same input replays the first answer at $0; with other input it returns 409.

Saved or shared

Rows are returned, not saved, unless you pass save. Company rows are shared across startups for 30 days; fit and evidence are yours.

Emits

Organization.found with { organizations, where, question, total }

Performed by

Prospector

Price

About 3.8¢ per 100 rows. Free: saving rows as Prospects, pages with no rows. maxCost defaults to $1.00. 100 companies that fit a sentence, each with its quote: 100 × 0.2¢ a row is about 20¢.

Reliability

The first route succeeds 100% of 185,187 calls. If it fails, the call refuses with sources-busy and nothing is spent.

Freshness

A reading younger than 30 days returns at $0. Readings are shared across startups for the same subject and locale.

Batch and pages

Up to 100 rows a page. Pages with an after cursor, 25 rows a page by default and 100 at most. A question call over 50 rows reads each site, so it answers in send mode with a pending Action at once

Rate

The shared rate rules: 10 calls a second per key, and an array input counts as one call.

Refuses when

Check	Error	Fix	Then call
A call sent with `strict: true` and a filter no route can apply	`filter-unsupported`	Drop that filter, or send without `strict` and read what comes back in `ignored`.	`Organization.count`

Every data call can also meet the shared data-call refusals: input-missing, limit-exceeded, max-cost, rate-limited, sources-busy, venue-unsupported.

The filter-unsupported payload

JSON

{
  "type": "https://startupbuilder.dev/errors/filter-unsupported",
  "title": "No route can apply a filter you sent",
  "status": 422,
  "detail": "A call sent with `strict: true` and a filter no route can apply.",
  "fix": "Drop that filter, or send without `strict` and read what comes back in `ignored`.",
  "next": {
    "verb": "Organization.count",
    "input": {
      "where": {
        "industries": [
          "property management"
        ],
        "headcount": {
          "min": 20,
          "max": 200
        },
        "countries": [
          "US"
        ]
      }
    }
  },
  "instance": "https://api.sb/leaseline.app/actions/action_1"
}

When it waits

Returns in one response; nothing waits.

Example

Text

List the US property managers that still track rent in spreadsheets,
best first, with the quote that shows it; spend up to 1¢.

To retry, send the same Idempotency-Key: the retry returns the first answer for $0. A new key reads again.

Test values, and watching it

A sk_test_ key answers these the same way every time, at $0 (every test value).

Test value	Always returns	What it is for
`maxCost: 0.0001`	Refuses with `max-cost`	Any priced call with a maxCost of 0.0001 is refused before it spends: the price is above the cap.
`rate-limited.test`	Refuses with `rate-limited`	Any call naming this hostname answers 429 with Retry-After, so your retry logic runs.
`sources-busy.test`	Refuses with `sources-busy`	Any call naming this hostname answers 503 as if every route were busy, and nothing is spent.

Watch it on a schedule: a Monitor runs this call and records an Event only when the reading changes.

TypeScript

await $.Monitor.create({
  verb: 'Organization.find',
  input: { where: { industries: ['property management'], event: { kind: 'funded', within: '7d' } } },
  change: 'funding',
  every: '1w',
})

Used by

Workflows: Champion moved · Build a verified list · Buying-trigger feed · Lookalikes · Pick who to sell to first
Jobs: Find your first customers

Options and pricesCopy Anchor Link

InputsCopy Anchor Link

OutputsCopy Anchor Link

Read the resultCopy Anchor Link

EffectsCopy Anchor Link

Refuses whenCopy Anchor Link

When it waitsCopy Anchor Link

ExampleCopy Anchor Link

Used byCopy Anchor Link

RelatedCopy Anchor Link