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
}

Pass Ping Reply Values Into the Post

Many destinations answer an accepted ping with an ID, such as a lead ID or a ping token, and refuse the post unless it sends that same ID back. Use the {{ld_ping_response:FIELD}} token to copy any value from the destination's ping reply into the post.

The format is the one you picked for the ping's reply in Ping Configuration (JSON, XML, or Text). A Post Body Template for the JSON example above looks like this:

{
  "lead_id": "{{ld_ping_response:response.lead_id}}",
  "first_name": "{{first_name}}",
  "phone": "{{phone}}"
}

Find the Real Field Names

• In Ping Configuration, click Test Ping once.
• In the Post Body Template, type {{ (or open the field picker). The fields from the destination's reply are listed under Ping Response Fields. Once live leads have been pinged, the list comes from the destination's most recent accepted ping.
• To test the post on its own, run Test Ping first, then Execute Test. A standalone test post uses the reply from your last Test Ping. Without one, the token goes out empty and the destination refuses the test because the post does not match an accepted ping.
• After a real lead goes out, open the lead and check its Delivery Log (or go to Logs → Delivery). The request body shows the value that was sent.

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%).