Build a GTM workflow
Chain the main capabilities — brand and offer context, prospecting, playbooks, and outcomes — into one attributable end-to-end workflow.
This guide shows the main end-to-end path through the platform: establish brand and offer context once, discover and qualify prospects, generate a playbook for each prospect you will work, and record what happened. Each step's typed contract lives in its own guide; this page shows how the steps chain.
It is written to be followed by an AI agent as well as a human. If you are an agent, also read the behavioral rules in Use Blackpearl with your AI agent.
Step 0: Check what is enabled#
Call GET /v1/capabilities before planning. Every generally available
capability is returned with an enabled flag. Plan only with capabilities that
show enabled: true; if something the user wants shows enabled: false, tell
them it exists but needs to be enabled for their organization — do not try to
work around it. See Capabilities and entitlements.
curl --fail-with-body --silent --show-error \
"$BLACKPEARL_API_BASE_URL/v1/capabilities" \
--header "Authorization: Bearer $BLACKPEARL_API_KEY" | jq '.capabilities[] | {key, enabled}'Step 1: Create the context once — a Brand and an Offer#
Almost everything downstream improves when the platform knows what you sell and who you are. Both objects are created once and reused by every later run:
- Brand — create it from the company website and run brand research; the platform derives positioning, audience, and voice as a versioned guideline. The only input you need from a user is their company URL. See Brands.
- Offer — record what is being sold: value propositions, proof points, pricing shape, and ideal-customer hints. Draft it from the brand research rather than asking the user to dictate it, then confirm. See Offers.
These two objects are the GTM graph's anchor. Campaigns bind a brand, an offer, and saved targeting into a reusable container and run Audience cycles when you want reviewable, exportable lists.
Step 2: Discover and qualify prospects#
Create a Prospecting job. Derive product_info and
objective from the Brand guideline and Offer — do not ask the user to
restate them. Leave the structured target empty unless the user explicitly
constrains it: discovering and qualifying the right people is the platform's
job. A run returns every prospect the agent delivers, up to 5,000.
qualification.score is the search agent's own fit score for that run, not
comparable across runs: don't cut prospects by it.
JOB=$(curl --fail-with-body --silent --show-error \
--request POST "$BLACKPEARL_API_BASE_URL/v1/prospects" \
--header "Authorization: Bearer $BLACKPEARL_API_KEY" \
--header "Idempotency-Key: $BLACKPEARL_IDEMPOTENCY_KEY" \
--header "Content-Type: application/json" \
--data '{
"campaign_name": "First prospecting run",
"product_info": "Summarized from the Offer value propositions.",
"objective": "Summarized from the Offer ideal-customer hints.",
"delivery_mode": "draft_only"
}')
JOB_ID=$(printf '%s' "$JOB" | jq -er '.id')Poll GET /v1/jobs/{job_id} to a terminal state as described in
Jobs and resumable polling. A run typically takes several
minutes. A run that delivers no prospects ends failed and is not charged
unless its search finished and found no matches; see
When a run delivers nothing.
Prospects come without outreach drafts, so write first-touch copy with
Message Templates. To keep a reviewable, exportable
list, materialize the successful run into an audience snapshot
(Audiences).
Step 3: Generate a playbook per prospect#
For each qualified prospect (for example, today's call list), create a
Playbooks job for its account. Pass stage,
playbook_template_key, and your offer_id so guidance is tailored to
selling that offer to that account at that stage. Personalised collateral
(Documents) and evidence-bound
Message Templates compose the same way.
Step 4: Record what happened#
Close the loop with Outcomes: append real-world results — meetings booked, replies, wins — against the prospect, account, or campaign, and read deterministic insight aggregates back. Attribution flows through the GTM graph, so the next run is informed by the last one.
Coming soon#
Enrichment (contact and company data completion, including business-email discovery) is in Preview and will slot between Steps 2 and 3 once generally available.
This is the first workflow in what will become a small library. The capability guides above remain the source of truth for exact request and response fields.