Offer Campaign APIs

Create Source Form API

POSThttps://api.pingtree.com/api/lead/add/{source-unique-id}

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#

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": "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)#

JSON

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

JSON

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

JSON

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