Ping-Post Guide

What is Ping-Post?

Ping-post is a two-step lead distribution method where leads are pre-qualified before being fully delivered. Instead of blindly sending leads, the system checks availability, pricing, and filters first — then sends the full lead only when a buyer has committed to purchasing it.

Lead Distro AI supports ping-post on both sides of the transaction — supplier-side (inbound) and buyer-side (outbound). You can use one or both depending on your setup.

Flow 1: Supplier-Side Ping-Post (Inbound)

This flow lets your suppliers check if a lead will be accepted before sending the full data. Useful when suppliers want to avoid wasting bandwidth on leads that will be rejected.

How It Works

• Step 1 — Supplier pings your system. The supplier sends partial lead data (phone, email, state, etc.) to the ping endpoint. No lead record is created.
• Step 2 — System checks eligibility. Lead Distro AI validates the data against campaign filters, suppression lists, and buyer availability. If everything checks out, it returns `accepted: true` along with a signed `ping_id` token.
• Step 3 — Supplier posts the full lead. The supplier sends the complete lead data to the ingest endpoint, including the `flo_ping_id` from step 2. The system verifies the token and processes the lead normally.

Ping Endpoint

POST https://app.leaddistro.ai/api/v1/ping

Ping Request Body

{
  "flo_campaign_id": "your-campaign-id",
  "flo_supplier_id": "your-supplier-id",
  "phone": "5551234567",
  "email": "lead@example.com",
  "state": "CA"
}

Ping Response (Accepted)

{
  "accepted": true,
  "ping_id": "eyJjaWQiOiJkZDJiM2...",
  "message": "Lead accepted"
}

Ping Response (Rejected)

{
  "accepted": false,
  "reason": "filtered",
  "message": "Lead does not meet campaign filters",
  "filter_errors": ["state must be one of: TX, FL, CA"]
}

Posting With the Ping ID

After a successful ping, include the `ping_id` as `flo_ping_id` in your ingest request:

{
  "flo_campaign_id": "your-campaign-id",
  "flo_supplier_id": "your-supplier-id",
  "flo_ping_id": "eyJjaWQiOiJkZDJiM2...",
  "first_name": "Maria",
  "last_name": "Garcia",
  "phone": "5551234567",
  "email": "lead@example.com",
  "state": "CA"
}

Flow 2: Buyer-Side Ping-Post (Outbound)

This flow is configured per-buyer inside a campaign. When a lead is distributed, the system pings the buyer first to check if they want the lead and at what price, then posts the full lead data if they accept.

How It Works

• Step 1 — Lead is ingested. A supplier sends a lead via the ingest API (with or without the supplier-side ping flow above).
• Step 2 — System pings buyers. For each eligible buyer with ping-post enabled, the system sends a ping request to the buyer's configured Ping URL with partial lead data.
• Step 3 — Buyer responds with a bid. The buyer's system returns an accept/reject response. If accepted, they can include a bid price that overrides their default payout.
• Step 4 — Best bid wins. If multiple buyers bid, the highest bidder gets the lead. The system posts the full lead to the winning buyer's delivery endpoint.
• Step 5 — Revenue is recorded. The bid price becomes the lead's revenue. If the supplier uses Revenue Share cost mode, the cost is auto-calculated as a percentage of that bid.

Configuring Buyer-Side Ping-Post

• Go to your Campaign and find the buyer in the Outbound Buyers section.
• Click the buyer's menu (three dots) and select Edit.
• Enable the Ping-Post toggle under the delivery settings.
• Set the Ping URL — this is the endpoint on the buyer's system that receives ping requests.
• Configure Response Parsing — specify which JSON field indicates acceptance (e.g., `accepted` equals `true`).
• Optionally enable Real-Time Price — specify the JSON path for the bid price in the buyer's response (e.g., `bid_price` or `data.price`).

Buyer Ping Request (Sent by Lead Distro AI)

The ping body template is configurable per buyer. Use `{{field}}` placeholders to include lead data:

{
  "first_name": "{{first_name}}",
  "last_name": "{{last_name}}",
  "email": "{{email}}",
  "phone": "{{phone}}",
  "state": "{{state}}"
}

Buyer Ping Response (Expected from Buyer)

{
  "accepted": true,
  "bid_price": 120.00
}

Revenue Share + Ping-Post

Revenue Share is a supplier cost mode where the supplier is paid a percentage of whatever the buyer pays. This is especially powerful with ping-post because the buyer's bid price varies per lead.

Example

To set this up, go to your campaign's Inbound Suppliers section, edit the supplier, and select Revenue Share as the cost mode. Enter the percentage you want to pay the supplier (e.g., 75%).