Speed-to-Lead Intake Webhook

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:

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.

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:

{
  "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

{
  "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 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.

Getting Started

Endpoints

Webhooks and Lead Intake

Custom Integration

ServiceTitan Technical Reference

Security and Reliability

Overview

Authentication

Request

Response

Scheduling Behavior

Enterprise Routing

Tracking Leads Downstream

​Overview

​Authentication

​Request

​Response

​Scheduling Behavior

​Enterprise Routing

​Tracking Leads Downstream

Overview

Authentication

Request

Response

Scheduling Behavior

Enterprise Routing

Tracking Leads Downstream