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

If you were given a dedicated source URL when your integration was set up, post there instead:

POST https://app.avoca.ai/api/outbound/speed-to-lead/ingest/<source_key>

A dedicated source URL identifies both your team and which lead source the payload came from — you don’t need to send a lead_source field, and it’s not possible to misattribute leads to the wrong source. If you operate at the portfolio or enterprise level, the routing rules below don’t apply on this URL either, since the team is already fixed by the key. Ask your Avoca contact whether a dedicated source URL exists for your integration; if not, use the shared endpoint above.

Authentication

Avoca issues your API key already in its full, final form, including the avoca_ prefix (e.g. avoca_3f1a9c2e6b7d4e2a9c3f8d5b1a2e4f6c...), when you (or the Avoca team) generate it in the dashboard. Copy it exactly as given; there’s nothing to prepend or assemble yourself. Set it as an environment variable and authenticate with either header:

Authorization: Bearer $AVOCA_API_KEY
# or
X-API-Key: $AVOCA_API_KEY

Rate limits

Avoca does not currently enforce rate limits on this endpoint. There is no documented or guaranteed limit, so if you anticipate very high-volume or bursty delivery, check with your Avoca contact first.

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	Type	Required	Description
`customer_name` (or `first_name` / `last_name`)	string	Yes (by default)	Customer name. Send either the combined name or both parts: Avoca joins `first_name` + `last_name` when `customer_name` isn’t mapped. Required by default; some accounts (e.g. a missed-call or abandoned-lead feed with only a phone number) have this made optional on request. Ask your Avoca contact if you need this.
`phone_number`	string	Yes	Customer phone. Any common US format is accepted (`(555) 123-4567`, `555-123-4567`, `5551234567`, `+15551234567`) and normalized to `+1XXXXXXXXXX`. Must resolve to a 10-digit US number (11 digits accepted with a leading `1`); anything else is rejected, see Errors. International numbers are not currently supported.
`email`	string	No	Customer email. Not validated as a well-formed email address; any string is accepted and stored as-is.
`address` / `street` / `city` / `state` / `zip` / `country`	string	No	Location. `country` defaults to `USA` when omitted.
`service_type`	string	No	Requested service
`lead_source`	string	No	Source label, mapped to a configured Avoca lead source. Omitted payloads fall back to `API Webhook` (or `API (<utm_source>)` when `utm_source` is present).
`external_id`	string	No, but strongly recommended	Your reference ID. Any string, including a UUID, is accepted; there’s no required format. Combined with the phone number, this is the identity Avoca uses to recognize a repeat delivery as the same lead rather than a new one, see Duplicate and repeat deliveries. Echoed on webhooks and the leads feed.
`notes`	string	No	Free-form notes; can be configured to combine multiple payload fields into one JSON object
`bypass_deduplication`	boolean	No	Set to `true` to have this delivery treated as a brand-new lead even when the same `phone_number` + `external_id` already exists, see Duplicate and repeat deliveries. Read from the top level of your payload as-is (not through field mappings). Omit it for normal deliveries.
`appointment_datetime`	string (ISO 8601, e.g. `2026-09-10T15:00:00-04:00`)	No	Requested appointment time, if any. A `LLL d yyyy h:mm a` format (e.g. `Sep 10 2026 3:00 PM`) is also accepted as a fallback, but ISO 8601 is the only supported contract, so don’t rely on the fallback.
`utm_source` / `utm_medium` / `utm_campaign` / `utm_term` / `utm_content`	string	No	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. Fields outside this table are not lost: the complete raw JSON body you send is always stored on the lead and available in the v1 leads feed and on outbound lead events, whether or not a field mapping exists for it. Mapping only controls what gets used operationally (matching, dedupe, display), not what’s retained.

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 (`201 Created`)

A 201 is returned whenever the request was authenticated and well-formed, whether or not a lead was actually recorded or will be contacted. Always check data.lead_id and skipped rather than treating 201 alone as “a new lead now exists.”

{
  "success": true,
  "message": "Lead created successfully",
  "data": {
    "lead_id": 12345
  },
  "request_id": "3f1a9c2e-6b7d-4e2a-9c3f-8d5b1a2e4f6c"
}

request_id is a UUID generated fresh per request. The example above is illustrative, not a real value to match against.

Field	Type	Always present	Description
`success`	boolean	Yes	`true` for every `201` response.
`message`	string	Yes	Human-readable summary. See the `message` values in the table below. Not a stable machine-readable field; parse `skipped` / `data.lead_id` instead.
`data.lead_id`	integer	No	The lead’s id. Absent only when the resolved lead source is disabled (see below); that is the one case where a `201` means nothing was stored.
`skipped`	boolean	No	`true` when the lead will not receive AI outreach. Omitted entirely (not `false`) on the normal path.
`skip_reason`	string	No	Present only alongside `skipped: true`, see Skip and ignore reasons.
`request_id`	string (UUID)	Yes	Correlates this request with Avoca-side logs if you need to escalate an issue.

What each outcome looks like

Scenario	`data.lead_id`	`skipped`	`skip_reason`	`message`
New lead, will be contacted	present	n/a	n/a	`"Lead created successfully"`
Repeat delivery (same phone + `external_id` as an existing lead)	present (existing lead’s id)	n/a	n/a	`"Duplicate lead merged into existing lead"`
Repeat delivery with `bypass_deduplication: true`	present (a new lead’s id)	n/a	n/a	`"Lead created successfully"`
Appointment time is already in the past	present	`true`	`"past_appointment"`	`"Lead is ignored: past_appointment"`
Suppressed by cooldown	present	`true`	free-text, contains `"cooldown"` (see below)	`"Lead is ignored: <reason>"`
Resolved lead source is disabled	absent	`true`	`"lead_source_disabled"`	`"Lead source is disconnected; lead was not logged"`

Duplicate and repeat deliveries

Avoca treats team + phone_number + external_id as the identity of a lead. Re-sending a payload with the same phone number and external_id does not create a second lead or error. It updates the existing lead’s name, email, address, and notes in place, and the response reports "Duplicate lead merged into existing lead" with the original lead_id. This is safe to rely on for retries. It does not apply to correcting a phone number: changing the phone number changes the identity, so it always creates a new, separate lead rather than updating the old one. Always send external_id when you have one. When it’s omitted, identity collapses to team + phone_number alone. Two genuinely different leads for the same phone number (e.g. two different service requests) will merge into one lead rather than creating two, since Avoca can’t otherwise tell them apart. external_id is the only thing that disambiguates repeat callers. Forcing a repeat to be treated as new. Send bypass_deduplication: true at the top level of the payload and Avoca skips the identity match and the cooldown window for that one delivery, creating and contacting a new lead even though the same phone_number + external_id already exists. This is intended for testing your integration by replaying the same lead. Do not send it on production retries: a retry carrying it creates a duplicate lead that will be contacted again.

Edge case: occasional 500 on truly simultaneous duplicate deliveries

Two deliveries for the same identity arriving at (or near) the exact same instant are not fully guarded: this endpoint checks for an existing lead and creates a new one as separate steps, so a race between two concurrent requests can, in rare cases, surface as a 500 on one of them rather than both cleanly merging. If you see an occasional 500 on what should be a duplicate, a brief retry will resolve it: the underlying lookup succeeds on the next attempt.

Skip and ignore reasons

skip_reason is not yet a fixed enum. Treat it as one of these categories rather than matching on exact text (only past_appointment and lead_source_disabled are stable literal strings today; the cooldown reason is a generated sentence):

Category	`skip_reason` shape	Meaning
Lead source disabled	exact string `lead_source_disabled`	The lead source this payload resolved to has been disconnected. No lead was stored at all, this is the only case where `data.lead_id` is absent on a `201`.
Past appointment	exact string `past_appointment`	The mapped `appointment_datetime` was already in the past (only evaluated when your team has this check enabled). The lead is stored but not queued for outreach.
Cooldown	free text containing `cooldown` (e.g. `"cooldown time is … for lead source …"`)	A recent lead for the same phone number is still inside the source’s configured cooldown window. The lead is stored but not queued for outreach.

One outreach-affecting state is not visible in this response at all: if the resolved lead source has AI outreach turned off (distinct from being disabled: the source still accepts and stores leads normally), that decision is made asynchronously after this request already returned 201 with a normal, non-skipped response. To detect it, check is_ignored / ignored_reason on the lead via the leads feed after the fact, rather than the synchronous ingest response. The lead.created webhook event does not carry these fields (it fires at insert time, before this state is known), so the leads feed is the only place to observe it.

Errors

Status	Body shape	Meaning
400	`{ "success": false, "error": string, "request_id": string }`. A payload-shape error also includes `"errors": [{ "field": string, "message": string, "code": string }]`.	Invalid payload shape, failed routing rule, or a missing `customer_name` / missing-or-unparseable `phone_number`
401	`{ "success": false, "error": string, "request_id": string }`	Missing or invalid API key
405	`{ "success": false, "error": string, "request_id": string }`	Method other than `POST`
500	Usually `{ "success": false, "error": string, "request_id": string }`. A failure specifically inside lead processing (after payload validation) instead returns `{ "success": false, "message": string, "request_id": string }`. Check for whichever key is present rather than assuming one.	Unexpected server-side failure processing the request

There is no 409 response. A payload that matches an existing lead’s identity is merged, not rejected (see Duplicate and repeat deliveries).

Example: 400 (missing required field)

{
  "success": false,
  "error": "Payload validation failed",
  "errors": [
    { "field": "phone_number", "message": "phone_number is required", "code": "MISSING_REQUIRED" }
  ],
  "request_id": "7c2e4a1b-9d3f-4a6c-8e1b-2f5d9a7c3e6b"
}

Example: 400 (invalid phone number format)

{
  "success": false,
  "error": "Payload validation failed",
  "errors": [
    { "field": "phone_number", "message": "Invalid phone number length: 7 digits (expected 10 or 11)", "code": "INVALID_FORMAT" }
  ],
  "request_id": "1e9b3c5a-4f7d-4e2a-9b1c-6a8d3f5e7c2b"
}

Example: 401 (missing or invalid API key)

{
  "success": false,
  "error": "Invalid API key",
  "request_id": "9a3f6c1e-2b5d-4a8c-9e3f-1c6a4b8d2f7e"
}

Examples

Minimal payload (only the required fields)

customer_name and phone_number are required by default.

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": "5551234567"
  }'

{
  "success": true,
  "message": "Lead created successfully",
  "data": { "lead_id": 12345 },
  "request_id": "4d8e2a6c-1f3b-4a9d-8c2e-5b7f1a3d9e6c"
}

No lead_source was sent, so this lead is filed under the API Webhook fallback source.

Phone-only payload (accounts with customer_name made optional)

Some accounts (e.g. a missed-call or abandoned-lead feed that never has a name to send) have customer_name configured as optional. Ask your Avoca contact if this applies to you before omitting it. For every other account, this payload gets a 400.

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 '{
    "phone": "5551234567"
  }'

{
  "success": true,
  "message": "Lead created successfully",
  "data": { "lead_id": 12345 },
  "request_id": "7f2c9e6a-4b1d-4e3c-8a5f-1d6b2e9c7f3a"
}

Payload with extraneous, unmapped fields

Any fields you send beyond the ones Avoca recognizes are not rejected and not dropped. The full payload is always retained.

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",
    "source": "Website Form",
    "external_id": "form-8812",
    "internal_crm_stage": "MQL",
    "assigned_rep_id": "rep-4471",
    "custom_scoring": { "intent": 0.82, "fit": 0.61 }
  }'

internal_crm_stage, assigned_rep_id, and custom_scoring have no configured field mapping, so they don’t affect matching, dedupe, or how the lead displays in Avoca. They’re still stored verbatim on the lead’s raw payload and available through the v1 leads feed and on outbound lead events.

Skipped: cooldown window

{
  "success": true,
  "message": "Lead is ignored: cooldown time is 2026-09-03T14:00:00.000Z for lead source Website Form. Lead was created at 2026-09-03T10:12:00.000Z.",
  "skipped": true,
  "skip_reason": "cooldown time is 2026-09-03T14:00:00.000Z for lead source Website Form. Lead was created at 2026-09-03T10:12:00.000Z.",
  "data": { "lead_id": 12346 },
  "request_id": "8f2c4e6a-3d9b-4a1c-9e6f-2b5d8a3c1f7e"
}

The lead is still stored (data.lead_id present); it just won’t be queued for outreach. See Skip and ignore reasons.

Skipped: lead source disabled (nothing stored)

{
  "success": true,
  "message": "Lead source is disconnected; lead was not logged",
  "skipped": true,
  "skip_reason": "lead_source_disabled",
  "data": {},
  "request_id": "6a1d3f5c-8e2b-4a7d-9c1f-3e6a8b2d4f9c"
}

data.lead_id is absent. This is the one outcome where nothing was actually created, despite the 201 status.

Repeat delivery (merged into an existing lead)

Sending the same phone_number + external_id a second time (e.g. a retry, or the provider re-sending an updated record) updates the existing lead rather than creating a new one:

{
  "success": true,
  "message": "Duplicate lead merged into existing lead",
  "data": { "lead_id": 12345 },
  "request_id": "2c5e7a9d-4f1b-4a3c-8e5d-1a4c7f2b9e6a"
}

lead_id matches the original lead. Name, email, address, and notes are updated from this request’s payload; the phone number and external_id themselves are not changed by a resend.

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

Portfolio and Enterprise Routing

A single API key can post leads for multiple teams (every brand in an enterprise, or every team in a portfolio) through this one endpoint, instead of needing a separate key per team. This applies to both enterprise_all_teams keys and portfolio_all_teams keys (the key type issued at the portfolio level) identically. If you operate at the portfolio or enterprise level, ask your Avoca contact whether routing is configured for your key before assuming a routing field is optional. Your key’s anchor team is the one specific team it is directly tied to in Avoca (for a portfolio key, the team the key was generated from; for an enterprise key, whichever member team it was issued against). What happens if you omit the routing field depends entirely on whether routing is configured at all: it does not uniformly fall back to the anchor team. See below for the full breakdown. There is no platform-wide team_id field name; which JSON field carries the target team, and how its value maps to a team, is configured once by the Avoca team on your anchor team’s Speed-to-Lead settings (routing_rules), in one of two modes:

Mode	How the payload’s routing field is interpreted	Example
`team_id`	The field’s value is the numeric team id directly.	Field configured as `team_id`, a value of `<your_team_id>` routes to that team.
`custom_field` (default)	The field’s value is an arbitrary string (e.g. a brand or location code) that is looked up against a configured value → team id mapping.	Field configured as `brand`, value `"acme-hvac"` is mapped to a specific team on the Avoca side.

Example: portfolio/enterprise key, team_id mode

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",
    "team_id": "<your_team_id>",
    "source": "Website Form",
    "external_id": "form-8812"
  }'

Replace <your_team_id> with the numeric id of the team this lead belongs to. Assumes your routing field was configured as team_id in team_id mode. The value is validated as a positive integer and must belong to a team inside your portfolio or enterprise. A team id outside it is rejected with 400 unless a fallback default team is configured for your key, in which case (same as custom_field mode below) the lead is routed to that fallback team instead and the request succeeds with 201.

Example: portfolio/enterprise key, custom_field mode

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",
    "brand": "acme-hvac",
    "source": "Website Form",
    "external_id": "form-8812"
  }'

Assumes your routing field was configured as brand, mapped to a specific team on the Avoca side. Ask your Avoca contact to confirm the exact field name and its value-to-team mappings for your account.

What happens when the routing field is missing, invalid, or doesn’t match a configured mapping depends on your configuration:

No routing configured at all: every lead is accepted and lands on the anchor team, silently, with no error. If you’re only seeing one team’s leads and expected several, this is the first thing to check.
Routing is configured, but this request’s value is missing, empty, or doesn’t match any rule: these are treated identically. Rejected with 400 by default (Routing field value "…" did not match any configured rule, or the equivalent missing-field message), unless a fallback default team was configured, in which case the lead routes there instead. It does not fall back to the anchor team.
Value resolves to a team outside your portfolio/enterprise: rejected with 400 unless a fallback default team is configured, in which case it routes to the fallback instead (same as the unmatched case above), applying in both team_id and custom_field modes. The one boundary that is never configurable: a fallback team itself must be inside your portfolio/enterprise, or the request is rejected regardless.

Ask your Avoca contact to confirm whether routing is configured for your key, which field name and mode it uses, and whether a fallback team is set. Working at the portfolio level: routing setup for portfolio_all_teams keys is currently done directly on the anchor team’s own Speed-to-Lead settings in the Avoca dashboard; there is not yet a dedicated portfolio-wide configuration screen (enterprises have one, portfolios don’t yet). Your Avoca contact will need to know which team is your anchor team to make this change.

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

Reporting

Endpoints

Webhooks and Lead Intake

Custom Integration

ServiceTitan Technical Reference

Security and Reliability

Overview

Authentication

Rate limits

Request

Response

Success (`201 Created`)

What each outcome looks like

Duplicate and repeat deliveries

Skip and ignore reasons

Errors

Examples

Scheduling Behavior

Portfolio and Enterprise Routing

Tracking Leads Downstream

​Overview

​Authentication

​Rate limits

​Request

​Response

​Success (201 Created)

​What each outcome looks like

​Duplicate and repeat deliveries

​Skip and ignore reasons

​Errors

​Examples

​Scheduling Behavior

​Portfolio and Enterprise Routing

​Tracking Leads Downstream

Overview

Authentication

Rate limits

Request

Response

Success (`201 Created`)

What each outcome looks like

Duplicate and repeat deliveries

Skip and ignore reasons

Errors

Examples

Scheduling Behavior

Portfolio and Enterprise Routing

Tracking Leads Downstream