Integration — AdvertisingML

Delivery options

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).
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.
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.
Email: Structured payload delivered as MIME-formatted email. JSON in message body or as attachment. Useful for low-volume advertisers without backend integration capacity.
Phone-call transfer (selected verticals): Live consumer transferred to your inbound number after disclosure. Available in insurance and home services verticals.

Webhook payload format

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

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": "..."
    }
}

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.

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.

# 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)
    );
}

Return-credit workflow

To request a credit for an invalid lead, POST to the return endpoint within 48 hours of delivery:

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. Credits applied to account balance within 24 hours of acceptance.

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.

Help getting integrated

Email integrations@advertisingml.com with your stack details and we'll walk you through the cleanest setup for your environment.

Integration options