Lead.qualify · SalesBuilder

POST https://api.sb/{your-domain}/leads/qualify

Opens a deal for a lead that fits one of your offers, with its value and the reason it fits. The hub’s definition of Lead.qualify.

Inputs

Name	Type	Default	Meaning
`lead`	`Lead`	Required	The lead to qualify.
`offer`	`Offer`	Required	The offer whose ICP the lead matches.

Outputs

Field	Type	What `null` means
`deal`	`Deal`	Never null.
`lead`	`Lead`	Never null.
`deal.status`	`string`	Never null: `Open` when the deal starts.
`deal.value`	`money`, in USD	Never null: the offer’s first-year price, from its price and interval.
`deal.nextStep`	`text`	Null when no dated step is agreed yet; a booked Meeting sets it.
`lead.status`	`string`	Never null: `working` once qualified.
`lead.fit`	`string`	Never null once graded: `strong` or `partial`. A lead graded `none` is not qualified.

Effects

Action class

None: no approval rule names it, so it runs within its seat’s Permissions and Limits

Modes

try: Grades the lead’s fit against the offer’s ICP and returns the deal it would open; nothing is stored.
send: Opens the deal at once and returns it.
do: Opens the deal at once and returns it.

Idempotency

Only with a key: the same Idempotency-Key and input return the first Action, and the same key with other input returns 409. A lead with an open deal for the same offer returns that deal; it never opens a second.

Saved or shared

The deal is saved with the lead and its Contact, and mirrored to your CRM when one is connected.

Emits

Lead.qualified with { lead, deal, offer, fit }

Performed by

Sales Engineer

Price

Free on your own account: the platform charges nothing for the call.

On each Venue

Site	Fields	Formats
Facebook	`interest`	1
LinkedIn	`interest`	3
Facebook and Instagram	`interest`	5
The CRM you already use	`status`, `fit`, `owner`	None.

Facebook

Through Facebook.

Our field	Facebook’s field
`Lead.interest`	`leadgen.field_data` (Each form question and answer, as you wrote the form)

Lead-form entries. Arrive by webhook within seconds; the agent qualifies each and drafts the first reply within 5 minutes.
Your role on the page. Posting needs a role that can post; a role removed in Meta’s settings ends the connection with needs-reauth.

Feed image ad, 1440 × 1800, 4:5

Through LinkedIn Ads.

Our field	LinkedIn Ads’s field
`Lead.interest`	`leadFormResponse answers`

Feed post Single image ad, 1200 × 628, 1200 × 1200 or 720 × 900 Document ad

Facebook and Instagram

Through Meta Ads.

Our field	Meta Ads’s field
`Lead.interest`	`leadgen.field_data`

Facebook: Feed image ad, 1440 × 1800, 4:5 Instagram: Feed image, 320 to 1,440 pixels wide, 4:5 to 1.91:1 Instagram: Carousel Instagram: Reel, 9:16 Instagram: Story, 9:16

The CRM you already use

Through The CRM you already use.

Our field	The CRM you already use’s field
`Lead.status`	`lead status or lifecycle stage` (Whichever your CRM keeps)
`Lead.fit`	`fit` (A field the platform adds: `strong`, `partial` or `none`)
`Lead.owner`	`owner`

Direction. One per Integration. Your records stay the record in both modes, and the side you declared leads every conflict.
Stages. Map one to one onto the pipeline you picked; a stage with no match refuses with venue-rejected and names it.

What try does

Account	What try does
Facebook	Returns the post as your page will show it, with the time it goes live; nothing is posted or scheduled.
LinkedIn Ads	Reads your ad account, the matched count of each audience and the targeting facets, and checks the campaign against LinkedIn’s budget minimums; LinkedIn has no validate-only call, so nothing is sent to it and nothing is created.
Meta Ads	Sends the whole build with Meta’s `validate_only` execution option: Meta runs every check and creates nothing, and the response names any field it would reject.
The CRM you already use	Reads your CRM and returns what one sync would change on each side, record by record; nothing is written to either.

Refuses when

This call has no refusals of its own. Every call through an account can also meet the shared account refusals: grant-missing, needs-reauth, account-not-connected, over-mandate, quota-reached, venue-rejected.

When it waits

Returns in one response; nothing waits.

Example

Text

Rosa booked Tuesday’s call: qualify Northgate Rentals for Leaseline and
open the Deal.

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

Test values

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

Test value	Always returns	What it is for
`lead_test_strong`	`{"fit":"strong","deal":{"status":"Open","value":{"amount":1788,"currency":"USD"}}}`	A strong-fit test lead opens the same $1,788 deal every time, so your pipeline steps run against a known value.
`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.

Used by

Workflows: Inbound routing
Agent tasks: Answer every inbound
Services: Booked first calls
Integrations: Facebook · LinkedIn Ads · Meta Ads · The CRM you already use

None.

InputsCopy Anchor Link

OutputsCopy Anchor Link

EffectsCopy Anchor Link

On each VenueCopy Anchor Link

FacebookCopy Anchor Link

LinkedInCopy Anchor Link

Facebook and InstagramCopy Anchor Link

The CRM you already useCopy Anchor Link

What try doesCopy Anchor Link

Refuses whenCopy Anchor Link

When it waitsCopy Anchor Link

ExampleCopy Anchor Link

Used byCopy Anchor Link

RelatedCopy Anchor Link