> ## Documentation Index
> Fetch the complete documentation index at: https://api.agentflow-enterprise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect AgentFlow to Your CRM and Downstream Workflows

> Configure AgentFlow to push qualified lead data, AI scores, and operator decisions to your CRM or any downstream workflow tool via webhook handoff.

AgentFlow sits between lead capture and your CRM — it qualifies, scores, and routes incoming leads so that by the time a record reaches your sales or operations team, it already carries the context they need to act. The handoff step is how AgentFlow delivers that enriched record to whatever system owns the next part of your workflow.

## What the handoff delivers

When AgentFlow triggers a handoff, it sends a structured payload containing everything your downstream system needs to create or update a contact, open an opportunity, or kick off an automation sequence:

* **Lead identity** — name, email, company, and any additional fields captured at intake
* **AI qualification score** — the numeric score (0–100) and confidence rating from the OpenAI qualification step
* **Operator decision** — the outcome your team recorded: `approved`, `rejected`, or `review_requested`
* **Summary notes** — the plain-language explanation generated by the AI scoring model
* **Recommended action** — the AI-suggested next step
* **Timestamps** — when the lead was received, scored, and decided on
* **Lead ID** — a stable identifier for idempotent downstream processing

## Integration options

AgentFlow uses **webhook-based handoff**, which means it works with any system that can receive an HTTP POST request. You do not need a native integration or a marketplace connector — if your CRM or operations tool has a webhook URL, AgentFlow can deliver to it.

Commonly used destinations include:

<CardGroup cols={3}>
  <Card title="HubSpot" icon="h">
    Use HubSpot's inbound webhook or a Zapier/Make intermediary to create contacts and deals.
  </Card>

  <Card title="Salesforce" icon="cloud">
    Route through Salesforce Flow or an integration middleware to create leads and opportunities.
  </Card>

  <Card title="Notion" icon="n">
    Push qualified leads into a Notion database for lightweight pipeline tracking.
  </Card>

  <Card title="Airtable" icon="table">
    Append rows to an Airtable base for team-visible lead review and tracking.
  </Card>

  <Card title="Zapier / Make" icon="bolt">
    Use an intermediary automation layer to fan out to multiple destinations or transform the payload.
  </Card>

  <Card title="Custom endpoint" icon="code">
    POST directly to any internal service, data warehouse ingestion endpoint, or ops API.
  </Card>
</CardGroup>

## Configure the CRM handoff

<Steps>
  <Step title="Define the handoff trigger">
    In your AgentFlow dashboard, navigate to **Settings → Handoff**. Choose when AgentFlow should dispatch the outbound payload:

    * **On operator approval** *(recommended)* — fires only when an operator marks a lead `approved`
    * **On any decision** — fires on `approved`, `rejected`, and `review_requested`
    * **On qualification complete** — fires immediately after AI scoring, before operator review

    For most teams, triggering on operator approval keeps your CRM clean and ensures only validated leads enter your pipeline.
  </Step>

  <Step title="Configure your destination endpoint">
    Enter your CRM or workflow tool's webhook URL in the **Destination URL** field. AgentFlow sends a `POST` request to this URL with a JSON body each time the trigger fires.

    <Warning>
      Your destination endpoint must use HTTPS. AgentFlow will not dispatch handoff payloads to plain HTTP endpoints.
    </Warning>

    If your downstream system requires authentication headers — for example, an `Authorization: Bearer <token>` — add them in the **Custom Headers** section. These headers are stored server-side and are never exposed in the dashboard response payloads.
  </Step>

  <Step title="Map payload fields to your CRM schema">
    AgentFlow sends a standardized payload (see below), but your CRM may expect different field names or a nested structure. Use the **Field Mapping** panel to translate AgentFlow fields to your destination schema. If you are routing through Zapier or Make, you can handle mapping in your automation workflow instead.
  </Step>

  <Step title="Test with a sample qualified lead">
    Use the **Send Test Payload** button to dispatch a representative payload to your destination endpoint. Check your CRM or workflow tool to confirm the record arrived, the fields populated correctly, and any downstream automation fired as expected.

    <Tip>
      Before pointing at your live CRM, test against a webhook inspection tool like [Webhook.site](https://webhook.site) or [RequestBin](https://pipedream.com/requestbin). This lets you inspect the full payload structure and headers without creating noise in your production data.
    </Tip>
  </Step>
</Steps>

## Example handoff payload

AgentFlow sends the following JSON structure to your configured endpoint:

```json theme={null}
{
  "event": "lead.qualified",
  "lead_id": "lead_01HX7KQZPW9N3V4MBCR6TY8EJ",
  "timestamp": "2024-11-14T10:15:42Z",
  "operator_decision": "approved",
  "contact": {
    "name": "Priya Nair",
    "email": "priya.nair@horizonops.io",
    "company": "Horizon Ops",
    "message": "We need a faster way to triage inbound demo requests. Currently drowning in Typeform submissions with no prioritization.",
    "source": "website_contact_form"
  },
  "qualification": {
    "score": 87,
    "confidence": "high",
    "summary": "Strong fit: mid-market SaaS RevOps team with an active pain point and implicit urgency. No budget signal, but intent is clear.",
    "recommended_action": "approve",
    "scored_at": "2024-11-14T10:14:58Z"
  },
  "next_action_context": "Schedule discovery call within 24 hours. Reference triage pain point in outreach."
}
```

Your downstream system receives this payload as the `POST` request body with `Content-Type: application/json`.

## Troubleshooting handoff delivery

If your CRM or workflow tool is not receiving payloads, work through these checks:

<Accordion title="No payload arriving at the destination">
  * Confirm the destination URL is correct and publicly reachable (not `localhost` or an internal network address).
  * Check that the handoff trigger you configured is actually firing — visit the lead record in the AgentFlow dashboard and verify its status matches the trigger condition.
  * Review the **Handoff Logs** panel under Settings for delivery attempts and HTTP response codes.
</Accordion>

<Accordion title="Payload arriving but fields are missing or wrong">
  * Check your field mapping configuration in AgentFlow. A misconfigured mapping can silently drop or rename fields.
  * Inspect the raw payload using a webhook inspection tool to confirm AgentFlow is sending the expected structure before the issue is diagnosed as a CRM-side problem.
</Accordion>

<Accordion title="CRM returning a non-200 response">
  * A `401` or `403` usually means authentication headers are missing or incorrect. Verify the `Authorization` header value in the Custom Headers panel.
  * A `422` or `400` typically means a required field in your CRM's schema is missing from the payload or failing validation. Check your CRM's inbound webhook documentation for required fields.
  * AgentFlow logs the response code for every delivery attempt. Retry failed deliveries from the Handoff Logs panel once you have corrected the configuration.
</Accordion>

<Accordion title="Duplicate records appearing in the CRM">
  * Use the `lead_id` field as a deduplication key in your CRM or automation workflow. AgentFlow guarantees that `lead_id` is stable and unique per lead record.
  * If you have configured the trigger to fire on multiple events (e.g., both `approved` and `any decision`), you may be dispatching multiple payloads for the same lead. Scope the trigger to a single event type.
</Accordion>