Skip to main content
Advertiser sign-in Start advertising
Advertisers · Integration

Integration options.

Leads delivered within 2 seconds of consumer submission, via the integration path that fits your existing stack. Choose one or combine multiple — leads can be delivered to several destinations in parallel.

Delivery

Delivery options.

Five paths; pick the one that matches your stack and operational posture.

  1. 01

    Webhook POST

    HTTPS POST to an endpoint you specify. JSON or form-encoded payload. Optional HMAC signature header for source verification. Configurable retry policy (default: 3 retries with exponential backoff over 5 minutes; configurable up to 10 retries over 4 hours).

  2. 02

    REST API pull

    Authenticated GET endpoint returning queued leads. Acknowledge receipt with POST to mark as delivered. Useful if your firewall posture doesn't allow inbound webhooks.

  3. 03

    CRM push (direct integrations)

    First-party integrations with Salesforce, HubSpot, Pipedrive, Zoho, GoHighLevel. Authentication via OAuth on your end; leads created as records (Lead, Contact, or Custom Object — your choice) with full payload mapped to standard and custom fields.

  4. 04

    Email

    Structured payload delivered as MIME-formatted email. JSON in message body or as attachment. Useful for low-volume advertisers without backend integration capacity.

  5. 05

    Phone-call transfer (selected verticals)

    Live consumer transferred to your inbound number after disclosure. Available in insurance and home services verticals.

Webhook

Webhook payload format.

Leads are delivered as a single JSON object per HTTP request. Example: auto-insurance, shared tier.

POST /leads · application/json 
POST https://your-endpoint.example.com/leads
Content-Type: application/json
X-Aml-Signature: sha256=...
X-Aml-Lead-Id: aml_2026_AB...
X-Aml-Delivery-Attempt: 1

{
  "lead_id":      "aml_2026_AB12345",
  "vertical":     "auto_insurance",
  "sub_vertical": "auto_insurance",
  "tier":         "shared",
  "advertiser_id":"your_account_id",
  "delivered_at_iso":"2026-05-23T14:32:11Z",
  "consumer": {
    "first_name": "Jamie",
    "last_name":  "Rivera",
    "email":      "jamie.rivera@example.com",
    "phone_e164": "+15125550199",
    "address": {
      "line1":  "1234 Main St",
      "city":   "Austin",
      "state":  "TX",
      "zip":    "78704"
    },
    "dob_year": 1989
  },
  "vertical_data": { /* sub-vertical specific */ },
  "consent": {
    "trustedform_cert_url":     "https://cert.trustedform.com/...",
    "consent_language_version": "2026-05",
    "consent_timestamp_iso":    "2026-05-23T14:32:09Z",
    "ip": "203.0.113.42"
  },
  "source": {
    "property_id": "auto_compare_us",
    "user_agent":  "...",
    "session_id":  "..."
  }
}
Response

Expected response.

Your endpoint should respond with HTTP 200 or 202 on accept, and any non-2xx status to indicate failure (triggering retry). Response body is logged but does not affect lead status.

Idempotency via X-Aml-Lead-Id header — duplicate posts of the same lead-id are safe to retry.

Sandbox

Sandbox & testing.

Sandbox endpoint available at https://sandbox.advertisingml.com/v1 for integration testing.

Sandbox leads are clearly marked with "sandbox": true at the top level of the payload and use synthetic consumer data.

Security

HMAC signature verification.

Each webhook includes an X-Aml-Signature header containing an HMAC-SHA256 of the raw request body, keyed with your account's signing secret (rotatable from the advertiser dashboard). Verify in your endpoint to confirm requests originate from AdvertisingML.

verify.js · Node.js 
// Example (Node.js)
import crypto from "node:crypto";

function verifySignature(rawBody, headerSig, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(headerSig),
    Buffer.from(expected)
  );
}
Returns

Return-credit workflow.

To request a credit for an invalid lead, POST to the return endpoint within 48 hours of delivery. Credits applied to account balance within 24 hours of acceptance.

POST /v1/returns 
POST https://api.advertisingml.com/v1/returns
Authorization: Bearer <your_api_key>
Content-Type: application/json

{
  "lead_id": "aml_2026_AB12345",
  "reason":  "disconnected_number",
  "notes":   "Optional free-text"
}
ACCEPTED REASONS
  • disconnected_number
  • wrong_state
  • wrong_vertical
  • duplicate_within_30_days
  • deceased_consumer
Need a walkthrough?

Tell us your stack, we'll script the cleanest path.

Email integrations@advertisingml.com with your endpoint details, ESP, or CRM. We'll send back a working test fire within a business day.

Email integrations →