Offer Campaign APIs

Create Form API

POSThttps://api.pingtree.com/api/lead/{cid}

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#

Parameter	Type	Required	Description
`source-unique-id`	string	Yes	The unique link identifier for the campaign source

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	Consumer's email address
`mobile`	string	Conditional	10-digit mobile number (digits only)
`address`	string	Conditional	Street address
`city`	string	Conditional	City name
`state`	string	Conditional	State abbreviation (e.g. `CA`)
`zip_code`	string	Conditional	5-digit ZIP code
`country`	string	No	Country code (default: `US`)
`date_of_birth`	string	No	Date of birth (YYYY-MM-DD)
`transaction_id`	string	No	Pre-generated transaction ID; one is created if omitted
`sub1` – `sub5`	string	No	Publisher sub-parameters for tracking
`adv1` – `adv5`	string	No	Advertiser sub-parameters
`utm_source`	string	No	UTM source
`utm_medium`	string	No	UTM medium
`utm_campaign`	string	No	UTM campaign
`utm_term`	string	No	UTM term
`utm_content`	string	No	UTM content
`gclid`	string	No	Google Click ID
`fbclid`	string	No	Facebook Click ID
`ttclid`	string	No	TikTok Click ID
`jornaya`	string	No	Jornaya lead ID token
`xxTrustedFormCertUrl`	string	No	TrustedForm certificate URL
`tcpa_consent`	string	No	TCPA consent flag
`tcpa_consent_date`	string	No	TCPA consent timestamp

Required fields depend on the campaign configuration. Check your posting spec for the exact list of required fields.

Example Request#

Bash

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#

JSON

{
  "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#

JSON

{
  "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#

JSON

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

Error — Unauthorized#

JSON

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

Status Codes#

HTTP Code	Lead Status	Description
201	`accepted`	Lead was accepted and distributed
201	`unsold`	Lead was recorded but not distributed (e.g. duplicate, cap reached)
400	`missingField`	One or more required fields are absent
400	`invalidField`	One or more fields failed format validation
400	`rejected`	Lead was rejected by the campaign rules
401	`rejected`	Invalid or missing authorization token
405	`rejected`	HTTP method not allowed
500	`rejected`	Internal 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.