> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avoca.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Speed-to-Lead Intake Webhook

> Push leads into Avoca from any source for instant AI outreach

## Overview

The Speed-to-Lead intake webhook is the endpoint partners and lead providers POST leads to. Each accepted lead is recorded, matched against your configured field mappings, and queued for outbound AI outreach according to your team's scheduling rules.

```
POST https://app.avoca.ai/api/outbound/speed-to-lead/ingest
```

## Authentication

Authenticate with your Avoca API key using either header:

```bash theme={null}
Authorization: Bearer avoca_YOUR_KEY
# or
X-API-Key: avoca_YOUR_KEY
```

## Request

Send any JSON object — field names are resolved through your team's configured **field mappings**, so you can point most lead sources at Avoca without reshaping their payloads. Standard target fields include:

| Field                                                                     | Description                                                                                |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `customer_name` (or `first_name` / `last_name`)                           | Customer name                                                                              |
| `phone_number`                                                            | Customer phone (required for call outreach)                                                |
| `email`                                                                   | Customer email                                                                             |
| `address` / `street` / `city` / `state` / `zip` / `country`               | Location                                                                                   |
| `service_type`                                                            | Requested service                                                                          |
| `lead_source`                                                             | Source label — mapped to a configured Avoca lead source                                    |
| `external_id`                                                             | Your reference ID, echoed on webhooks and the leads feed                                   |
| `notes`                                                                   | Free-form notes; can be configured to combine multiple payload fields into one JSON object |
| `appointment_datetime`                                                    | Requested appointment time, if any                                                         |
| `utm_source` / `utm_medium` / `utm_campaign` / `utm_term` / `utm_content` | Attribution                                                                                |

Each mapping is a first-match-wins alias list (e.g. `phone_number` ← `phone`, `Phone`, `contact.phone`), configured per team by the Avoca team.

```bash theme={null}
curl -X POST https://app.avoca.ai/api/outbound/speed-to-lead/ingest \
  -H "Authorization: Bearer $AVOCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "phone": "(555) 123-4567",
    "email": "john@example.com",
    "source": "Website Form",
    "service": "HVAC Repair",
    "external_id": "form-8812"
  }'
```

## Response

**Success:**

```json theme={null}
{
  "success": true,
  "lead_id": 12345,
  "stl_call_id": 6789,
  "request_id": "0b9ce9a4-…"
}
```

**Errors:**

| Status | Meaning                                   |
| ------ | ----------------------------------------- |
| 400    | Invalid payload shape or validation error |
| 401    | Missing or invalid API key                |
| 409    | Duplicate lead                            |

```json theme={null}
{
  "success": false,
  "error": "…",
  "request_id": "0b9ce9a4-…"
}
```

## Scheduling Behavior

When the AI calls the lead is governed by your team's configured scheduling mode:

* `always` — call as soon as the lead arrives
* `business_hours` — call immediately during business hours; queue otherwise
* `after_hours` — only outside business hours
* `custom` — custom windows configured with the Avoca team

## Enterprise Routing

`enterprise_all_teams` keys can ingest leads for multiple brands through one endpoint. Routing rules on the anchor team's configuration map a payload field value to the target team; unmatched leads are rejected by default or routed to a configured default team. Target teams are validated against the enterprise's membership.

## Tracking Leads Downstream

* Subscribe to [`lead.created`, `lead.booking_created`, and `lead.completed` webhooks](/api-reference/webhooks/event-webhooks) for real-time lifecycle updates.
* Pull historical records (including your original raw payload) from the v1 leads feed: `GET /api/v1/teams/{teamId}/leads`. Join on `external_id` or the returned `lead_id`.