Ping/Post API
The Ping/Post API enables real-time lead auctions where buyers bid on leads using non-PII data (ping), and winning bidders receive full lead data (post). This two-phase approach maximizes revenue while protecting consumer privacy.
https://api.synaptis.io/v1Authentication
All API requests require authentication using a Bearer token in the Authorization header.
Authorization: Bearer your_api_keySend Ping
Broadcast non-PII lead attributes to your buyer network and collect real-time bids.
/pingRequest Body
{
"ping_id": "ping_abc123",
"lead_type": "auto_insurance",
"attributes": {
"state": "GA",
"zip": "30301",
"age_range": "25-34",
"homeowner": true,
"credit_range": "good",
"coverage_type": "full"
},
"auction_settings": {
"timeout_ms": 500,
"floor_price": 25.00,
"max_winners": 1
}
}Response
{
"ping_id": "ping_abc123",
"status": "bids_received",
"auction": {
"total_buyers_pinged": 8,
"bids_received": 4,
"highest_bid": 45.00,
"auction_duration_ms": 234
},
"bids": [
{
"buyer_id": "buyer_alpha",
"buyer_name": "Alpha Insurance",
"bid_amount": 45.00,
"response_time_ms": 89,
"rank": 1
},
{
"buyer_id": "buyer_beta",
"buyer_name": "Beta Coverage",
"bid_amount": 38.50,
"response_time_ms": 156,
"rank": 2
}
],
"winner": {
"buyer_id": "buyer_alpha",
"buyer_name": "Alpha Insurance",
"bid_amount": 45.00
}
}Bid Response Format
Buyers respond to pings with the following bid format. Bids must be returned within the configured timeout.
{
"ping_id": "ping_abc123",
"bid": {
"amount": 45.00,
"currency": "USD",
"accept": true
},
"buyer_reference": "BID-2024-001234"
}If a buyer does not want to bid, they should return "accept": false or simply not respond within the timeout window.
Post Lead
Send full lead data including PII to the winning bidder after auction completion.
/postRequest Body
{
"ping_id": "ping_abc123",
"buyer_id": "buyer_alpha",
"lead": {
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@email.com",
"phone": "+15551234567",
"address": {
"street": "123 Main St",
"city": "Atlanta",
"state": "GA",
"zip": "30301"
},
"ip_address": "192.168.1.1",
"consent_timestamp": "2024-01-15T10:30:00Z",
"custom_fields": {
"current_insurer": "State Farm",
"vehicles": 2
}
}
}Response
{
"status": "accepted",
"ping_id": "ping_abc123",
"lead_id": "lead_xyz789",
"buyer": {
"id": "buyer_alpha",
"name": "Alpha Insurance",
"reference": "ALI-2024-001234"
},
"transaction": {
"amount": 45.00,
"currency": "USD",
"timestamp": "2024-01-15T10:30:05Z"
}
}Auction Settings
Configure auction parameters to control bidding behavior.
timeout_msintegerdefault: 500Maximum time to wait for bid responses (100-2000ms)
floor_pricedecimaldefault: 0.00Minimum bid amount to accept. Bids below floor are rejected.
max_winnersintegerdefault: 1Number of winning bidders (for shared lead distribution)
second_pricebooleandefault: falseUse second-price auction (winner pays second-highest bid + $0.01)
exclusivebooleandefault: trueWhether lead is exclusive to single buyer or can be shared
Timeout Handling
Buyers who do not respond within the timeout window are excluded from the auction.
Bid Timeout
If a buyer does not respond to a ping within timeout_ms, they are marked as "no_bid" and excluded from winner selection.
Post Timeout
If a winning buyer does not accept the post within 5 seconds, the lead can be re-routed to the next highest bidder using the waterfall mechanism.
Retry Logic
Configure automatic retries for failed posts with exponential backoff. Maximum 3 retry attempts with 1s, 2s, 4s delays.
Response Codes
200OKPing/post processed successfully201CreatedLead created and delivered400Bad RequestInvalid request parameters401UnauthorizedInvalid or missing API key404Not FoundPing ID not found408TimeoutNo bids received within timeout422No BidsNo valid bids above floor price429Rate LimitedToo many requestsDemo Platform: This is a demonstration of our custom development capabilities. We build tailored solutions for your specific needs.