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:

  1. 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.
  2. 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.