---
name: fuseai
description: Use when building prospect search and list management workflows,
  creating outbound email and LinkedIn campaigns, running signal agents to
  monitor buying signals, enriching contact data, or automating sales pipeline
  operations through API or MCP integration with Claude, Cursor, or other AI
  assistants.
metadata:
  mintlify-proj: fuseai
  version: "1.0"
---

# FuseAI Skill

## Product summary

FuseAI is a sales automation API that lets you search 500M+ prospect profiles, organize them into lists, enrich contact data, attach AI-powered smart columns, launch email and LinkedIn campaigns, run signal agents to monitor buying signals, and sync everything to your CRM. The REST API is authenticated with API keys (HTTP Basic auth); the MCP server lets Claude, Cursor, and other AI assistants drive the same capabilities through natural language. Base URL: `https://api.tryfuse.ai/api/v1/business`. MCP server: `https://mcp.fuseai.com`. Key config: API keys created in Settings → API Cockpit. Primary docs: https://docs.fuseai.com.

## When to use

Reach for this skill when:
- Building prospect search workflows that filter by title, seniority, industry, location, company size, skills
- Creating and managing prospect lists (search, import, upload, enrich)
- Launching email or LinkedIn outbound campaigns (manual or AI-generated)
- Running signal agents to monitor job changes, funding announcements, hiring, headcount growth, LinkedIn posts
- Enriching contact data (emails, phones, demographics) via waterfall providers
- Attaching AI smart columns to research prospects and score leads
- Syncing contacts and engagement to Salesforce, HubSpot, Attio, Zoho, or Pipedrive
- Exporting lists to CSV or building dynamic campaigns that auto-enroll new prospects
- Polling long-running jobs (exports, enrichment, campaign initialization, agent runs)

## Quick reference

### Authentication
- Create API key in Fuse app: Settings → API Cockpit
- Use HTTP Basic auth: `-u "af_YOUR_KEY:"`
- Raw form also accepted: `-H "Authorization: Basic af_YOUR_KEY"`
- Keys are workspace-level; never commit to source control

### Core endpoints by surface

| Surface | Key endpoints | Rate limit |
| --- | --- | --- |
| **Lists** | `POST /lists`, `GET /lists/{id}`, `GET /lists/{id}/rows`, `POST /lists/{id}/enrich`, `POST /lists/{id}/export` | 120/min, 10k/day |
| **Prospect search** | `POST /prospects/search`, `POST /prospects/search/save-to-list` | 20/min, 1k/day |
| **Campaigns** | `POST /campaigns`, `GET /campaigns/{id}`, `PATCH /campaigns/{id}/steps/{id}`, `POST /campaigns/{id}/approve` | 30/min, 1k/day |
| **Agents** | `POST /agents/{type}`, `GET /agents`, `POST /agents/{id}/activate` | 30/min, 2k/day |
| **Smart columns** | `POST /lists/{id}/smart-columns`, `GET /lists/{id}/smart-columns/{id}/status` | 120/min (lists bucket) |
| **Enrichment** | `POST /lists/{id}/enrich` | 120/min (lists bucket) |
| **CRM sync** | `POST /lists/{id}/crm-push`, `GET /integrations` | 120/min (lists bucket) |

### Async job polling

| Job type | Returns | Poll with |
| --- | --- | --- |
| Export | `jobId` | `GET /exports/{jobId}` |
| Save search to list | `listIds` | `GET /lists/{listId}` (check `completionStatus`) |
| Enrich list | `listIds` | `GET /lists/{listId}` (check `completionStatus`) |
| Campaign init | `campaignId` | `GET /campaigns/{campaignId}` (check `initializationStatus`) |
| Smart column | `jobId` | `GET /lists/{listId}/smart-columns/{jobId}/status` |
| Agent start | agent object | `GET /agents/{agentId}` (check `status`) |
| Research run | `runId` | `GET /research/runs/{runId}/events` |

### Credit costs (per operation)

| Operation | Cost |
| --- | --- |
| Prospect search (per result) | 2 credits |
| Company search (per result) | 2 credits |
| Enrich email found | 50 credits (100 if personal emails prioritized) |
| Enrich phone found | 200 credits |
| Re-verify email | 10 credits |
| Smart column (per row) | Varies by engine; `deep_research` costs more |
| Signal agent | Varies by kind; capped by `maxCreditSpend` |
| Deep Research run | Per provider action; capped by `effort` (1k/2k/5k) |

### Common merge tokens in campaigns

- Built-in: `{Contact First Name}`, `{Contact Last Name}`, `{Contact Company}`, `{Contact Job Title}`, `{Contact Industry}`, `{Sender First Name}`, `{CTA Link}`
- Custom columns: `{Column: Column Name}` (exact name required)

## Decision guidance

### When to use manual vs. AI-generated campaigns

| Aspect | Manual | AI-generated |
| --- | --- | --- |
| **Copy control** | You write every subject and body | Fuse writes from your prompt + knowledge hub |
| **Setup time** | Faster to create, slower to write copy | Slower to initialize, faster to launch |
| **Personalization** | Use column tokens for dynamic content | AI reads knowledge hub + LinkedIn posts + custom columns |
| **Best for** | Templated sequences, brand-specific voice | Niche markets, high personalization, rapid iteration |
| **Editing** | `PATCH` subject/body on each step | `PATCH` topic on each step; regenerate copy |

### When to preview vs. save a prospect search

| Scenario | Use |
| --- | --- |
| Tuning filters before commit | `POST /prospects/search` with small `limit` (cheap preview) |
| Ready to populate a list | `POST /prospects/search/save-to-list` (runs search + enrichment server-side) |
| **Never** | Preview with same filters, then save same filters (pays for search twice) |

### When to use signal agents vs. manual campaigns

| Signal | Agent type | Enrollment |
| --- | --- | --- |
| People starting new jobs | `person-starting-new-job` | Continuous; results list grows |
| Funding announcements | `funding-announcements` | Continuous; company list grows |
| Job postings in region | `job-postings` | Continuous; people list grows |
| LinkedIn posts on topic | `linkedin-posts` | Continuous; people list grows |
| Watch your existing list | `people-watcher` or `companies-watcher` | Continuous; monitors for changes |

Pair with `isDynamic: true` campaigns to auto-enroll results as they arrive.

### When to use smart columns vs. custom columns

| Need | Use |
| --- | --- |
| Store data you write or import | Custom column (`POST /lists/{id}/columns`) |
| AI research every row (e.g., "pain point") | Smart column with `engine: "standard"` or `"deep_research"` |
| Score leads against ICP | Smart column with yes/no prompt + filter rows |
| Personalize emails with research | Smart column + `{Column: Name}` token in campaign step |

## Workflow

### Build and launch an AI campaign from scratch

1. **Search for prospects** — `POST /prospects/search` with filters (preview first with small `limit`)
2. **Save to list** — `POST /prospects/search/save-to-list` with full `limit`; returns `listIds[0]`
3. **Poll for enrichment** — `GET /lists/{listId}` until `completionStatus: "complete"`
4. **Create campaign draft** — `POST /campaigns` with `campaignType: "ai-generated"`, `userPrompt`, `websiteUrls`, `knowledgeHubId`
5. **Poll initialization** — `GET /campaigns/{campaignId}` until `initializationStatus: "completed"`
6. **Review steps** — `GET /campaigns/{campaignId}/steps`; optionally `PATCH` topics or other fields
7. **Preview a step** — `POST /campaigns/{campaignId}/steps/{stepId}/generate` to see rendered copy
8. **Approve** — `POST /campaigns/{campaignId}/approve` (this activates sending)

### Run a signal agent and enroll results in a dynamic campaign

1. **Create agent draft** — `POST /agents/{type}` with `start: false` (no credits spent yet)
2. **Review config** — `GET /agents/{agentId}` to inspect before activation
3. **Activate** — `POST /agents/{agentId}/activate` (credits spent; results list created)
4. **Poll for results** — `GET /agents` and find agent by id; watch `contactsFound` and `listId`
5. **Create dynamic campaign** — `POST /campaigns` with `isDynamic: true`, `listId` from agent
6. **Initialize and approve** — Follow steps 5–8 above
7. **Auto-enrollment** — Campaign checks source list every ~30 minutes; new results enroll automatically

### Enrich a list and filter by smart column

1. **Create smart column** — `POST /lists/{listId}/smart-columns` with `prompt`, `engine`, `runOn: "first_10"` (test first)
2. **Poll run** — `GET /lists/{listId}/smart-columns/{jobId}/status` until terminal status
3. **Review answers** — `GET /lists/{listId}/rows` and inspect `columnValues[columnId]`
4. **Rerun on all rows** — `POST /lists/{listId}/smart-columns/{columnId}/rerun` with `mode: "new_only"`
5. **Filter by answer** — `GET /lists/{listId}/rows` with `filters: { "customColumns": { "columnId": { "dataType": "string", "include": ["yes"] } } }`
6. **Enrich filtered rows** — `POST /lists/{listId}/enrich` with `mode: "email"` and same `filters`

### Export a list to CSV

1. **Start export** — `POST /lists/{listId}/export` with `{}`; returns `jobId`
2. **Poll job** — `GET /exports/{jobId}` until `status: "completed"`
3. **Download** — Use `downloadUrl` (presigned link, valid 15 minutes)

## Common gotchas

- **Preview then save costs credits twice.** `POST /prospects/search` and `POST /prospects/search/save-to-list` are separate operations. Preview with small `limit`, then call `save-to-list` once with full `limit`.
- **Smart columns block contacts if still running.** If a contact's smart-column cell is being researched when their campaign step is due, the contact stops. Let smart columns finish before approving campaigns.
- **Blank cells in columns render as gaps.** An empty custom column or a smart column that found nothing leaves a gap where the token was; the email still sends. Preview steps to see the result.
- **AI campaigns from manual templates lose topics.** If you create an AI campaign from a `templateId` of a manual campaign, it inherits subject/body but no `topic`. Approval fails until you `PATCH` a topic onto each step.
- **List reachability stats lag enrichment.** Creating a campaign immediately after enriching may fail with `LIST_INCOMPATIBLE_WITH_CHANNELS` even though contacts have emails. Wait a minute and retry.
- **Agents have a 10-agent free-plan limit.** Free accounts can hold at most 10 agents (drafts included). Delete unused agents before creating new ones.
- **Enrichment is per-contact, not per-row.** Contacts already carrying the requested data are never re-charged. A fully enriched list answers `409 ALL_CONTACTS_ALREADY_ENRICHED` before anything bills.
- **CRM sync is hourly, not instant.** Engagement fields (opens, clicks, replies) appear on contacts in your CRM about an hour after they occur.
- **Rate limits are per-surface, per-workspace.** Heavy list traffic does not starve campaigns. Check `RateLimit-Remaining` header and back off before hitting `429`.
- **Async jobs answer 202, not 200.** A `202` means the request was accepted, not that the work succeeded. Credits are usually spent by the background job, not the call. Poll to completion.

## Verification checklist

Before submitting work:

- [ ] API key is valid and has required scopes (test with `GET /me`)
- [ ] Credit balance is sufficient for the operation (`GET /credits`)
- [ ] List exists and has the expected row count (`GET /lists/{id}`)
- [ ] Campaign is initialized before approval (`initializationStatus: "completed"`)
- [ ] All campaign steps have required fields (manual: subject + body; AI: topic)
- [ ] Merge tokens are spelled exactly (e.g., `{Contact First Name}`, not `{firstName}`)
- [ ] Smart columns have finished running before campaign approval (check `status`)
- [ ] Sending accounts are connected in the app (approval fails without them)
- [ ] Dynamic campaigns have `isDynamic: true` if auto-enrollment is needed
- [ ] Async jobs are polled to terminal status before reading results
- [ ] Rate limit headers show remaining quota (`RateLimit-Remaining`)
- [ ] CRM sync is enabled and connected if pushing contacts

## Resources

- **Comprehensive page index:** https://docs.fuseai.com/llms.txt
- **API Reference:** https://docs.fuseai.com/api-reference
- **Workflows (end-to-end recipes):** https://docs.fuseai.com/workflows/overview

---

> For additional documentation and navigation, see: https://docs.fuseai.com/llms.txt