Skip to main content
POST
/
api
/
lead
/
ping
/
{source-unique-id}
cURL
curl --request POST \
  --url https://api.pingtree.com/api/lead/ping/{source-unique-id}

​
Overview

The Source Ping API is the first step in a two-call ping-post flow. It submits partial lead data to determine whether buyers are willing to purchase the lead and at what price — before any PII (personally identifiable information) is committed. If the ping is accepted, you receive a transaction_id and bid information, which you then use to complete the submission via the Source Post API. Use ping-post when you want buyer intent confirmation before collecting or submitting full consumer data.

​
Endpoint

POST /api/lead/ping/{source-unique-id}
Replace {source-unique-id} with the linkUniqueId for your source, found in your posting specification under the Ping API section.

​
Authentication

Include the ping-specific API token in the Authorization header: 
Authorization: Bearer <your-ping-token>
The ping token is separate from the form and post tokens. All three are listed in your posting specification.

​
Request Parameters

​
Path Parameters

ParameterTypeRequiredDescription
source-unique-idstringYesLink unique ID for this source-campaign pairing

​
Body Parameters (JSON)

Ping requests typically include non-PII fields sufficient for buyer evaluation. Required fields are defined in your posting specification.
ParameterTypeRequiredDescription
statestringConditional2-letter state code (used for geo-targeting)
zip_codestringConditional5-digit ZIP code
ageintegerNoConsumer age (alternative to date_of_birth)
sub1 – sub5stringNoPublisher sub-tracking parameters
adv1 – adv5stringNoAdvertiser sub-parameters
utm_sourcestringNoUTM source
utm_mediumstringNoUTM medium
transaction_idstringNoPublisher-generated ID; auto-generated if omitted
Custom campaign-specific fields (e.g. loan_amount, insurance_type, home_owner) are often included in pings as they affect buyer bid logic. Check your posting spec for the full list.

​
Example Request

curl -X POST "https://api.pingtree.com/api/lead/ping/lnk_abc123xyz" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "state": "CA",
    "zip_code": "90001",
    "loan_amount": 15000,
    "credit_score": "good",
    "home_owner": true,
    "sub1": "pub-campaign-001"
  }'

​
Example Responses

​
Success — Ping Accepted

{
  "status": "201",
  "message": "Ping accepted",
  "data": {
    "leadStatus": "ping_accept",
    "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456",
    "isDeDupe": false,
    "message": "Ping accepted",
    "amount": "45.00",
    "buyerTcpa": "By submitting this form you agree to be contacted by XYZ Lenders..."
  }
}

​
Success — Ping Rejected (no buyers)

{
  "status": "201",
  "message": "Ping rejected",
  "data": {
    "leadStatus": "ping_reject",
    "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456",
    "isDeDupe": false,
    "message": "No buyers available for this lead"
  }
}

​
Error — Missing Required Field

{
  "status": "400",
  "message": "Missing required field: state",
  "data": {
    "leadStatus": "missingField"
  }
}

​
Error — Unauthorized

{
  "status": "401",
  "message": "Unauthorized",
  "data": {
    "leadStatus": "rejected"
  }
}

​
Status Codes

HTTP CodeLead StatusDescription
201ping_acceptAt least one buyer bid on this lead; proceed to post
201ping_rejectNo buyers matched; do not post
400missingFieldRequired field absent
400invalidFieldField failed format validation
400rejectedCampaign or source rule rejected the ping
401rejectedInvalid or missing ping token
405rejectedHTTP method not allowed
500rejectedInternal server error

​
Tips

  • Ping before collecting PII: Submit only the non-identifying lead attributes during the ping. Only proceed to collect name, email, and phone if the ping returns ping_accept.
  • Store the transaction_id: This ID must be included in the subsequent Post API call to link the two steps together.
  • amount field: The bid amount returned in the ping response (data.amount) can be used to display personalized offer messaging to the consumer before they complete the form.
  • buyerTcpa: Some campaigns return buyer-specific TCPA consent language in the ping response. Display this text to the consumer before they submit their full details in the post step.
  • Ping TTL: A ping acceptance has a limited validity window (typically a few minutes). If too much time passes before the post call, the lead may be rejected or re-evaluated.
  • Do not post on rejection: If leadStatus is ping_reject, do not proceed with the post call. Instead, consider an alternative buyer path or inform the consumer that offers are unavailable.