Insertion API

Update Lead

Partially updates a single lead. The :id path param accepts EITHER the AdBuy lead UUID (leads.id) or the partner-supplied external_lead_id — whichever you have on hand. Identity fields (campaign_id, external_lead_id) themselves are not patchable. Every successful PATCH writes an audit row to lead_events with before/after/diff JSON for forensic review.

Endpoint

PATCH/api/v1/insertion/leads/:id

Authentication

Same as Create Lead. PATCH requires the leads:write scope; GET on this resource requires leads:read. See the dedicated Authentication guide for HMAC and Bearer signing recipes.

Path Parameters

Name	Type	Description
`id`required	string	Either the AdBuy lead UUID (leads.id) OR the partner-supplied external_lead_id. Scoped to your account; cross-account lookups return 404.

Request Body

All fields are optional. At least one patchable field is required (empty bodies are rejected with 400 invalid_payload).

Name	Type	Description
`phone`	string	10–50 chars.
`email`	string	Up to 320 chars.
`first_name`	string	Up to 100 chars.
`last_name`	string	Up to 100 chars.
`source`	string	Lead source label.
`source_form_url`	string	URL the lead originated from.
`ip_address`	string	Client IP.
`tcpa_consent`	boolean	Consent flag.
`tcpa_consent_text`	string	Consent string.
`tcpa_consent_timestamp`	string	ISO 8601 timestamp.
`custom_fields`	object	Arbitrary JSON.

Identity fields (campaign_id, external_lead_id) cannot be modified — to re-key a lead, create a new one with the desired identifiers. Unknown fields are rejected by the Zod schema.

Response

Response Schema

{
  "ok": true,
  "lead": {
    "id": "uuid",
    "account_id": "uuid",
    "campaign_id": 123,
    "external_lead_id": "uuid",
    "phone": "+15551234567",
    "email": "lead@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "source": "...",
    "source_form_url": "...",
    "ip_address": "...",
    "tcpa_consent": true,
    "tcpa_consent_text": "...",
    "tcpa_consent_timestamp": "2024-01-15T10:30:00Z",
    "custom_fields": { },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-16T14:20:00Z"
  },
  "event": { "id": "uuid" }
}

The event.id field is the lead_events row recording the before/after/diff for this mutation. It may be absent if the audit insert was best-effort skipped. See Errors & Idempotency for the full error envelope.

Example

cURL (Bearer)

curl -X PATCH "https://api.adbuy.ai/api/v1/insertion/leads/f6b1d3c0-1234-4abc-9def-0123456789ab" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+15559998888",
    "tcpa_consent": true
  }'

cURL (HMAC)

BODY='{"phone":"+15559998888","tcpa_consent":true}'
TS=$(date +%s)
SIG=$(printf "%s.%s" "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $2}')

curl -X PATCH "https://api.adbuy.ai/api/v1/insertion/leads/f6b1d3c0-1234-4abc-9def-0123456789ab" \
  -H "X-AdBuy-Public-Key: pk_live_..." \
  -H "X-AdBuy-Timestamp: $TS" \
  -H "X-AdBuy-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Response (200 OK)

{
  "ok": true,
  "lead": {
    "id": "1d8e1c2a-9b3e-4a4f-9c1e-2b0a1d8e1c2a",
    "account_id": "0a1b2c3d-4e5f-6789-abcd-ef0123456789",
    "campaign_id": 123,
    "external_lead_id": "f6b1d3c0-1234-4abc-9def-0123456789ab",
    "phone": "+15559998888",
    "tcpa_consent": true,
    "updated_at": "2024-01-16T14:20:00Z"
  },
  "event": { "id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210" }
}