Offer Campaign APIs

Create Source Post API

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

Overview#

The Source Post API is the second step in a two-call ping-post flow. After a successful ping returns a ping_accept status and a transaction_id, call this endpoint to submit the full lead — including all PII — and finalise the distribution to the matched buyer(s).

This endpoint must only be called after a successful ping. The transaction_id from the ping response is required to link the two calls together.

Endpoint#

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

Replace {source-unique-id} with the linkUniqueId for your source, found in your posting specification under the Post API section.

Authentication#

Include the post-specific API token in the Authorization header:

Authorization: Bearer <your-post-token>

The post token is separate from the ping and form 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)#

Parameter	Type	Required	Description
`transaction_id`	string	Yes	The transaction ID returned by the Ping API
`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
`zip_code`	string	Conditional	5-digit ZIP code
`date_of_birth`	string	No	YYYY-MM-DD format
`sub1` – `sub5`	string	No	Publisher sub-tracking parameters
`adv1` – `adv5`	string	No	Advertiser sub-parameters
`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

All campaign-specific custom fields sent in the ping should also be included in the post. Your posting specification lists required and optional fields for the Post API specifically.

Example Request#

Bash

curl -X POST "https://api.pingtree.com/api/lead/post/lnk_abc123xyz" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456",
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@example.com",
    "mobile": "4085559876",
    "address": "456 Oak Avenue",
    "city": "Austin",
    "state": "CA",
    "zip_code": "90001",
    "loan_amount": 15000,
    "credit_score": "good",
    "home_owner": true,
    "sub1": "pub-campaign-001"
  }'

Example Responses#

Success — Lead Sold#

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://offer.example.com/debt?tid=txn_7f3a2b1c"
  },
  "isDeDupe": false
}

Success — Lead Unsold#

JSON

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

Error — Missing Transaction ID#

JSON

{
  "status": "400",
  "message": "Missing required field: transaction_id",
  "data": {
    "leadStatus": "missingField"
  }
}

Error — Invalid Field#

JSON

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

Status Codes#

HTTP Code	Lead Status	Description
201	`accepted`	Lead distributed to buyer(s) matched during ping
201	`unsold`	Lead recorded but not distributed (buyer retracted, cap, etc.)
400	`missingField`	Required field (including `transaction_id`) is absent
400	`invalidField`	Field failed format validation
400	`rejected`	Post rejected (ping expired, invalid `transaction_id`, campaign rules)
401	`rejected`	Invalid or missing post token
405	`rejected`	HTTP method not allowed
500	`rejected`	Internal server error

Tips#

Always use the ping's transaction_id. The post call is linked to the ping via this ID. Submitting a new or mismatched ID will result in a rejection.
Post promptly after ping. Ping acceptances have a time-to-live window. If the consumer takes too long to fill in the form, the bid may expire and the post could be rejected or unsold.
Include the same custom fields. Buyer evaluation during ping used the custom fields you sent. Include them again in the post for consistency and to avoid validation errors.
Redirect URL: Store redirect_url from the post response and redirect the consumer immediately to complete the buyer journey.
Do not reuse tokens across steps. The ping token and post token are different credentials. Using the wrong token returns a 401 error.