Create Source Ping API

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#

Body Parameters (JSON)#

Ping requests typically include non-PII fields sufficient for buyer evaluation. Required fields are defined in your posting specification.

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#

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.