Create Source Form API

POST

api

lead

add

{source-unique-id}

cURL

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

import requests

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

response = requests.post(url)

print(response.text)

const options = {method: 'POST'};

fetch('https://api.pingtree.com/api/lead/add/{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/add/{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/add/{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/add/{source-unique-id}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pingtree.com/api/lead/add/{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 Form API is the primary lead submission endpoint for a specific campaign source. It accepts a full lead record from a publisher or media partner and routes it through the campaign’s distribution logic. This endpoint is equivalent to the Create Form API but is scoped to a source identified by its unique link ID rather than a campaign ID. It is the endpoint listed in your posting specification under “Form API”.

Endpoint

POST /api/lead/add/{source-unique-id}

Replace {source-unique-id} with the linkUniqueId provided in your posting specification. This value is unique per source-campaign pairing.

Authentication

Include the source API token in the Authorization header:

Authorization: Bearer <your-source-token>

The token is listed in your posting specification under the Form API section.

Request Parameters

Path Parameters

Parameter	Type	Required	Description
`source-unique-id`	string	Yes	Link unique ID for this source-campaign pairing

Body Parameters (JSON or form-encoded)

Parameter	Type	Required	Description
`first_name`	string	Conditional	Consumer’s first name
`last_name`	string	Conditional	Consumer’s last name
`email`	string	Conditional	Valid email address
`mobile`	string	Conditional	10-digit phone number (digits only)
`address`	string	Conditional	Street address
`city`	string	Conditional	City name
`state`	string	Conditional	2-letter state code (e.g. `TX`)
`zip_code`	string	Conditional	5-digit ZIP code
`country`	string	No	Country code (default: `US`)
`date_of_birth`	string	No	YYYY-MM-DD format
`transaction_id`	string	No	Publisher-generated transaction ID; auto-generated if omitted
`sub1` – `sub5`	string	No	Publisher sub-tracking parameters
`adv1` – `adv5`	string	No	Advertiser sub-parameters
`utm_source`	string	No	UTM source value
`utm_medium`	string	No	UTM medium value
`utm_campaign`	string	No	UTM campaign value
`utm_term`	string	No	UTM term value
`utm_content`	string	No	UTM content value
`gclid`	string	No	Google Click ID
`fbclid`	string	No	Facebook Click ID
`ttclid`	string	No	TikTok Click ID
`jornaya`	string	No	Jornaya LeadiD token
`xxTrustedFormCertUrl`	string	No	TrustedForm certificate URL
`tcpa_consent`	string	No	TCPA consent value
`tcpa_consent_date`	string	No	TCPA consent timestamp

Campaign-specific custom fields (e.g. loan_amount, home_owner, insurance_type) may also be required. Your posting specification lists all active fields with their required status.

Example Request

curl -X POST "https://api.pingtree.com/api/lead/add/lnk_abc123xyz" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@example.com",
    "mobile": "4085559876",
    "address": "456 Oak Avenue",
    "city": "Austin",
    "state": "TX",
    "zip_code": "73301",
    "loan_amount": 20000,
    "credit_score": "fair",
    "sub1": "pub-campaign-001",
    "transaction_id": "pub_txn_998877"
  }'

Example Responses

Success — Lead Accepted (Sold)

{
  "status": "201",
  "message": "Lead successfully created",
  "transaction_id": "pub_txn_998877",
  "data": {
    "transaction_id": "pub_txn_998877",
    "leadStatus": "accepted",
    "redirect_url": "https://offer.example.com/debt?tid=pub_txn_998877"
  },
  "isDeDupe": false
}

Success — Lead Unsold

{
  "status": "201",
  "message": "Lead accepted",
  "transaction_id": "pub_txn_998877",
  "data": {
    "transaction_id": "pub_txn_998877",
    "leadStatus": "unsold",
    "redirect_url": "https://fallback.example.com"
  },
  "isDeDupe": false
}

Error — Invalid Field

{
  "status": "400",
  "message": "Invalid field: mobile",
  "transaction_id": "pub_txn_998877",
  "data": {
    "leadStatus": "invalidField"
  },
  "isDeDupe": false
}

Status Codes

HTTP Code	Lead Status	Description
201	`accepted`	Lead distributed to at least one buyer
201	`unsold`	Lead recorded but not distributed (cap, filters, no buyers)
400	`missingField`	Required field absent from the request
400	`invalidField`	Field value did not pass format validation
400	`rejected`	Lead rejected by campaign rules
401	`rejected`	Invalid or missing API token
405	`rejected`	HTTP method not allowed
500	`rejected`	Internal server error

Tips

Check your posting spec: The exact list of required and optional fields, acceptable values, and field descriptions are auto-generated in your campaign’s posting specification page.
Mobile number format: Send only digits. The API strips non-digit characters, but a 10-digit number is required (e.g. 4085559876 not +1 (408) 555-9876).
Custom transaction IDs: If you supply a transaction_id, it must be unique per lead. Reusing an ID may overwrite or conflict with existing records.
Redirect handling: Store the redirect_url from the response and immediately redirect the consumer to it for optimal conversion.
ZIP code lookup: The API can resolve city and state from zip_code if those fields are not submitted, depending on campaign configuration.

Create Source Ping 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/add/{source-unique-id}

import requests

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

response = requests.post(url)

print(response.text)

const options = {method: 'POST'};

fetch('https://api.pingtree.com/api/lead/add/{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/add/{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/add/{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/add/{source-unique-id}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pingtree.com/api/lead/add/{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 or form-encoded)

Example Request

Example Responses

Success — Lead Accepted (Sold)

Success — Lead Unsold

Error — Invalid Field

Status Codes

Tips

​Overview

​Endpoint

​Authentication

​Request Parameters

​Path Parameters

​Body Parameters (JSON or form-encoded)

​Example Request

​Example Responses

​Success — Lead Accepted (Sold)

​Success — Lead Unsold

​Error — Invalid Field

​Status Codes

​Tips

Overview

Endpoint

Authentication

Request Parameters

Path Parameters

Body Parameters (JSON or form-encoded)

Example Request

Example Responses

Success — Lead Accepted (Sold)

Success — Lead Unsold

Error — Invalid Field

Status Codes

Tips