# Build a GTM workflow

> Chain the main capabilities — brand and offer context, prospecting, playbooks, and outcomes — into one attributable end-to-end workflow.

Canonical guide: <https://engine.neraperla.com/docs/gtm-workflow>

Raw Markdown: <https://engine.neraperla.com/docs/raw/gtm-workflow.md>

OpenAPI: <https://engine.neraperla.com/v1/openapi.json>

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](https://engine.neraperla.com/docs/agent-resources).

## 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](https://engine.neraperla.com/docs/feature-flags).

```bash
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](https://engine.neraperla.com/docs/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](https://engine.neraperla.com/docs/offers).

These two objects are the GTM graph's anchor. [Campaigns](https://engine.neraperla.com/docs/campaigns)
bind a brand, an offer, and saved targeting into a reusable container and run
[Audience](https://engine.neraperla.com/docs/audiences) cycles when you want reviewable, exportable lists.

## Step 2: Discover and qualify prospects

Create a [Prospecting](https://engine.neraperla.com/docs/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.

```bash
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](https://engine.neraperla.com/docs/jobs). 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](https://engine.neraperla.com/docs/prospecting#when-a-run-delivers-nothing).
Prospects come without outreach drafts, so write first-touch copy with
[Message Templates](https://engine.neraperla.com/docs/message-templates). To keep a reviewable, exportable
list, materialize the successful run into an audience snapshot
([Audiences](https://engine.neraperla.com/docs/audiences)).

## Step 3: Generate a playbook per prospect

For each qualified prospect (for example, today's call list), create a
[Playbooks](https://engine.neraperla.com/docs/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](https://engine.neraperla.com/docs/documents)) and evidence-bound
[Message Templates](https://engine.neraperla.com/docs/message-templates) compose the same way.

## Step 4: Record what happened

Close the loop with [Outcomes](https://engine.neraperla.com/docs/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](https://engine.neraperla.com/docs/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.
