Create Source Ping API

POST

api

lead

ping

{source-unique-id}

cURL

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

import requests

url = "https://api.pingtree.com/api/lead/ping/{source-unique-id}"

response = requests.post(url)

print(response.text)

const options = {method: 'POST'};

fetch('https://api.pingtree.com/api/lead/ping/{source-unique-id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pingtree.com/api/lead/ping/{source-unique-id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pingtree.com/api/lead/ping/{source-unique-id}"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.pingtree.com/api/lead/ping/{source-unique-id}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pingtree.com/api/lead/ping/{source-unique-id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

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

Parameter	Type	Required	Description
`source-unique-id`	string	Yes	Link 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.

Parameter	Type	Required	Description
`state`	string	Conditional	2-letter state code (used for geo-targeting)
`zip_code`	string	Conditional	5-digit ZIP code
`age`	integer	No	Consumer age (alternative to `date_of_birth`)
`sub1` – `sub5`	string	No	Publisher sub-tracking parameters
`adv1` – `adv5`	string	No	Advertiser sub-parameters
`utm_source`	string	No	UTM source
`utm_medium`	string	No	UTM medium
`transaction_id`	string	No	Publisher-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 Code	Lead Status	Description
201	`ping_accept`	At least one buyer bid on this lead; proceed to post
201	`ping_reject`	No buyers matched; do not post
400	`missingField`	Required field absent
400	`invalidField`	Field failed format validation
400	`rejected`	Campaign or source rule rejected the ping
401	`rejected`	Invalid or missing ping token
405	`rejected`	HTTP method not allowed
500	`rejected`	Internal 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.

Create Source Post APIThe API URL serves as the endpoint where the traffic source submits lead data. This URL must be installed and used by the source sending the data to ensure it’s received properly by Pingtree. [Find detailed documentation here](/documentation/campaign/source-single-view/Ping-+-Post-API-(CS,-MC,-MP)). Use [Generate Specs](/documentation/campaign/source-single-view/Generate-Specs-(CS,-MC,-MP)) feature to get the api specification for this endpoint.

cURL

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

import requests

url = "https://api.pingtree.com/api/lead/ping/{source-unique-id}"

response = requests.post(url)

print(response.text)

const options = {method: 'POST'};

fetch('https://api.pingtree.com/api/lead/ping/{source-unique-id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pingtree.com/api/lead/ping/{source-unique-id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pingtree.com/api/lead/ping/{source-unique-id}"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.pingtree.com/api/lead/ping/{source-unique-id}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pingtree.com/api/lead/ping/{source-unique-id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

API Documentation

Offer Campaign APIs

Database Source

Global Event Postback API

Overview

Endpoint

Authentication

Request Parameters

Path Parameters

Body Parameters (JSON)

Example Request

Example Responses

Success — Ping Accepted

Success — Ping Rejected (no buyers)

Error — Missing Required Field

Error — Unauthorized

Status Codes

Tips

​Overview

​Endpoint

​Authentication

​Request Parameters

​Path Parameters

​Body Parameters (JSON)

​Example Request

​Example Responses

​Success — Ping Accepted

​Success — Ping Rejected (no buyers)

​Error — Missing Required Field

​Error — Unauthorized

​Status Codes

​Tips

Overview

Endpoint

Authentication

Request Parameters

Path Parameters

Body Parameters (JSON)

Example Request

Example Responses

Success — Ping Accepted

Success — Ping Rejected (no buyers)

Error — Missing Required Field

Error — Unauthorized

Status Codes

Tips