Built-in Operator & use cases

The in-app Operator is not limited to a single scenario. It applies deterministic plans (preview → apply) on top of the same CRM, workflows, and connectors you use from the REST API and external agents. You can drive any Ops workflow those primitives support—lead capture is one high-leverage example of an intake path, not the product boundary.

Instant quickstart (see results in minutes)

New users should start with Operator instant quickstart: Start guided setup → choose a built-in goal (intake, qualification, routing, nurture) → apply the plan → use the activity log (Edit, Re-run plan, View public form).

Example use cases

Operator and the shared platform work across typical workflows. Starting points:

Inbound lead capture & bulk intake — Hosted forms and Google Sheets import create the same Crm::Lead records as the API; optional workflow enrollment on submit. This page documents that path in detail below.
Lead qualification — Pipelines and enrollments on the same CRM layer; Lead qualification recipe.
Opportunity routing & handoff — Assign, stage, and move deals with shared workflows; Opportunity routing recipe.
Nurture & follow-up — Enrollment-driven sequences after intake or stage changes; Nurture & follow-up recipe.

Open Dashboard → Tools → Operator to verify defaults, preview/apply starter plans, and use CSV or Sheets import—regardless of which use case you are implementing first.

Coexistence (external agents + Operator)

External agents and API keys keep using the same CRM and workflow APIs.
The Operator applies deterministic plans (preview → apply) on top of those primitives—no parallel “Operator CRM.”
Form submissions are audited with actor_type: lead_form; API traffic remains user / api_key as today.

Hosted lead capture form (example intake channel)

Each form has a public token. Endpoints on your API host:

GET  /public/lead_forms/:token   # minimal HTML form
POST /public/lead_forms/:token   # form POST, multipart, or JSON

Optional headers:

X-DripPulse-Form-Secret when the form has a rotated signing secret.
Idempotency-Key stored in lead metadata for client-side dedupe bookkeeping.

Configure HCAPTCHA_SECRET and HCAPTCHA_SITE_KEY on the API to enforce hCaptcha when hcaptcha_required is set on the form. Authenticated management: /api/v1/lead_forms (JWT or org API key).

Operator (dashboard)

Open Dashboard → Tools → Operator (/dashboard/operator). From there you can ensure the default opportunity pipeline, run Start guided setup (wizard: goal → intake → pipeline → configure → preview & apply), preview/apply deterministic plans, and jump to CRM import for CSV or Google Sheets.

Activity log & guided setup snapshot

The Operator page includes an organization-scoped activity log stored on the server (newest first). Typical row kinds include plan_apply, ensure_defaults, and lead_form_created.

plan_apply — When the UI applies a plan, it may send a wizard_setup object with the guided-setup choices (goal, intake path, form name, workflow options, pipeline preferences, flags). The API persists that under metadata.wizard_setup and adds human-readable Setup — … lines to detail_lines. Older rows may lack a snapshot; the UI explains that and offers Edit to change defaults and apply again.
Summary actions (per row) — Under each row’s summary: Edit opens guided setup (restores saved choices when available). Re-run plan when a stored plan_applied exists (plan_apply rows). For lead_form_created, View public form when a token is stored. Delete removes only the audit row, not the form record.
Hosted form creation logging — Creating a lead form from flows that send X-Operator-Ui-Log: 1 (or equivalent) appends a lead_form_created row with form id and public URL metadata.

Operator REST API (authenticated)

Same auth as the rest of the app: session JWT or organization API key in Authorization: Bearer …. Base path: /api/v1/operator/….

GET /api/v1/operator/quick_start/status — readiness (pipelines, lead count, caps).
POST /api/v1/operator/quick_start/ensure_defaults — ensure default opportunity pipeline; logs ensure_defaults.
POST /api/v1/operator/plans/preview — JSON body { "intent": "…" } (and wizard-driven options as implemented by the client).
POST /api/v1/operator/plans/apply — JSON body { "plan": { … } } and optional "wizard_setup" with permitted keys: v, wizard_goal, wizard_intake, wizard_form_name, wizard_workflow_id, wizard_create_workflow, wizard_new_workflow_name, wizard_generate_secret, wizard_hcaptcha, wizard_ensure_default_pipeline, wizard_preferred_pipeline_id. Successful or failed applies can log plan_apply with redacted plan/results in metadata.
GET /api/v1/operator/activity_events — list persisted log rows for the org.
DELETE /api/v1/operator/activity_events/:id — delete one log row.
POST /api/v1/operator/activity_events/:id/rerun — re-execute the stored plan_applied from a plan_apply row; copies wizard_setup into the new audit entry when present.

Secrets in plans/results are redacted in stored metadata. Full API surface for CRM and lead forms remains under /api/v1/crm/… and /api/v1/lead_forms.

Sources vs CRM import (batch data)

Sources (/dashboard/sources) stores CSV or Postgres settings and column mapping for agent batch runs—it does not import CRM records or run agents. After saving a source, open AI Agents → [agent] → Batch to load rows and submit the batch. Details: Sources & batch data.

Google Sheets

Create a connection with provider: "google_sheets" and OAuth access_token (Sheets read scope) on CRM → Import & export (inline form) or Settings → Integrations in the dashboard—not under Sources (Sources is for agent CSV/Postgres data sources).
POST /api/v1/crm/sheets_leads/preview with integration_connection_id, spreadsheet_id or URL, and A1 range.
POST /api/v1/crm/sheets_leads/import with the same fields; optional mapping from lead attribute to column header slug.

First row must be headers. Rows without an email value are skipped.

Workflow auto-enroll

If a LeadForm references a workflow, new leads create an active WorkflowEnrollment with lead_ref set to the lead public_id, consistent with POST /api/v1/workflows/:id/enrollments/bulk.

← Documentation home