Skip to main content
POST
/
api
/
lead
/
{cid}
cURL
curl --request POST \
  --url https://api.pingtree.com/api/lead/{cid} \
  --header 'Content-Type: application/json' \
  --data '
{
  "transaction_id": "<string>",
  "first_name": "<string>",
  "last_name": "<string>",
  "email": "<string>",
  "mobile": "<string>",
  "address": "<string>",
  "state": "<string>",
  "city": "<string>",
  "zip_code": "<string>",
  "date_of_birth": "<string>"
}
'
{
  "status": "<string>",
  "type": "<string>",
  "message": "<string>",
  "isDeDupe": "<string>",
  "lead_status": "<string>",
  "redirect_url": "<string>",
  "buyer_type": "<string>",
  "buyer_name": "<string>",
  "buyer_response": "<string>"
}

​
Overview

The Create Form API submits a lead captured from a landing page or campaign form directly into the Pingtree lead distribution system. The lead is evaluated, distributed to buyers, and a response is returned indicating acceptance status, redirect URL, and deduplication state.

​
Endpoint

POST /api/lead/add/{source-unique-id}
Replace {source-unique-id} with the unique link ID assigned to your campaign source (found in your posting spec).

​
Authentication

Include your API token in the Authorization header: 
Authorization: Bearer <your-api-token>
The token is source-specific and is provided in your campaign’s posting specification.

​
Request Parameters

​
Path Parameters

ParameterTypeRequiredDescription
source-unique-idstringYesThe unique link identifier for the campaign source

​
Body Parameters (JSON or form-encoded)

ParameterTypeRequiredDescription
first_namestringConditionalConsumer’s first name
last_namestringConditionalConsumer’s last name
emailstringConditionalConsumer’s email address
mobilestringConditional10-digit mobile number (digits only)
addressstringConditionalStreet address
citystringConditionalCity name
statestringConditionalState abbreviation (e.g. CA)
zip_codestringConditional5-digit ZIP code
countrystringNoCountry code (default: US)
date_of_birthstringNoDate of birth (YYYY-MM-DD)
transaction_idstringNoPre-generated transaction ID; one is created if omitted
sub1 – sub5stringNoPublisher sub-parameters for tracking
adv1 – adv5stringNoAdvertiser sub-parameters
utm_sourcestringNoUTM source
utm_mediumstringNoUTM medium
utm_campaignstringNoUTM campaign
utm_termstringNoUTM term
utm_contentstringNoUTM content
gclidstringNoGoogle Click ID
fbclidstringNoFacebook Click ID
ttclidstringNoTikTok Click ID
jornayastringNoJornaya lead ID token
xxTrustedFormCertUrlstringNoTrustedForm certificate URL
tcpa_consentstringNoTCPA consent flag
tcpa_consent_datestringNoTCPA consent timestamp
Required fields depend on the campaign configuration. Check your posting spec for the exact list of required fields.

​
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": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "mobile": "5551234567",
    "address": "123 Main St",
    "city": "Los Angeles",
    "state": "CA",
    "zip_code": "90001",
    "sub1": "campaign-abc",
    "utm_source": "google",
    "utm_medium": "cpc"
  }'

​
Example Responses

​
Success — Lead Accepted

{
  "status": "201",
  "message": "Lead successfully created",
  "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456",
  "data": {
    "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456",
    "leadStatus": "accepted",
    "redirect_url": "https://thank-you.example.com?tid=txn_7f3a2b1c"
  },
  "isDeDupe": false
}

​
Success — Duplicate Lead

{
  "status": "201",
  "message": "Lead accepted as duplicate",
  "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456",
  "data": {
    "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456",
    "leadStatus": "unsold",
    "redirect_url": "https://thank-you.example.com"
  },
  "isDeDupe": true
}

​
Error — Missing Required Field

{
  "status": "400",
  "message": "Missing required field: email",
  "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456",
  "data": {
    "leadStatus": "missingField"
  },
  "isDeDupe": false
}

​
Error — Unauthorized

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

​
Status Codes

HTTP CodeLead StatusDescription
201acceptedLead was accepted and distributed
201unsoldLead was recorded but not distributed (e.g. duplicate, cap reached)
400missingFieldOne or more required fields are absent
400invalidFieldOne or more fields failed format validation
400rejectedLead was rejected by the campaign rules
401rejectedInvalid or missing authorization token
405rejectedHTTP method not allowed
500rejectedInternal server error

​
Tips

  • Mobile format: Strip all non-digit characters before submitting. The API normalises the field automatically, but sending 555-123-4567 or (555) 123-4567 both work.
  • Deduplication: If deduplication is enabled for the campaign, the isDeDupe flag in the response indicates whether this lead was seen before.
  • Redirect URL: Use redirect_url from the response to forward the consumer to a thank-you page or offer wall.
  • Custom fields: Additional campaign-specific fields (e.g. loan_amount, home_owner) may be required. Check your posting spec for the complete field list.
  • Rate limits: Each campaign source has a configurable rate limit. Exceeding it returns a 429 Too Many Requests response.

Path Parameters

​
cid
string
required

Your campaign unique ID

Body

application/json

Lead details to add to the campaign

​
transaction_id
string
required

Lead's Transaction ID, Which was generate from click script of Pingtree

​
first_name
string

First name of the lead

​
last_name
string

Last name of the lead

​
email
string

Email of the lead

​
mobile
string

Mobile of the lead

​
address
string

Address of the lead

​
state
string

State of the lead

​
city
string

City of the lead

​
zip_code
string

Zip Code of the lead

​
date_of_birth
string

Date of Birth of the lead

Response

Lead successfully updated

​
status
string

Status code of API response

​
type
string

Type of API response which can be success or error

​
message
string

Message of API response

​
isDeDupe
string

Flag for dedup which confirms that lead is duplicate or not

​
lead_status
string

Current status of lead which can be sold or unsold or new

​
redirect_url
string

Response Redirect URL of API response

​
buyer_type
string

Buyer response type for lead sold

​
buyer_name
string

Current buyer name for lead sold

​
buyer_response
string

Entire buyer response which we get from buyer's endpoint