Event Postback API - Pingtree Documentation

POST

api

event

{campaign-id}

cURL

curl --request POST \
  --url https://api.pingtree.com/api/event/{campaign-id} \
  --header 'Content-Type: application/json' \
  --data '
{
  "transaction_id": "<string>",
  "event_id": "<string>",
  "clid": "<string>",
  "amount": 123,
  "pid": "<string>",
  "conversion_date": "<string>",
  "conversion_timezone": "<string>",
  "sub1": "<string>",
  "sub2": "<string>",
  "sub3": "<string>",
  "sub4": "<string>",
  "sub5": "<string>",
  "adv1": "<string>",
  "adv2": "<string>",
  "adv3": "<string>",
  "adv4": "<string>",
  "adv5": "<string>",
  "utm_source": "<string>",
  "utm_medium": "<string>",
  "utm_campaign": "<string>",
  "utm_adgroup": "<string>",
  "utm_matchtype": "<string>",
  "utm_term": "<string>",
  "utm_content": "<string>",
  "external_clickid": "<string>",
  "utm_creative": "<string>",
  "utm_placement": "<string>",
  "tcpa_consent_date": "<string>",
  "tcpa_consent": 123,
  "cost": 123,
  "cost_operation": "<string>",
  "adSpend": 123,
  "min_price": 123
}
'

{
  "status": "<string>",
  "type": "<string>",
  "message": "<string>",
  "missingFields": {},
  "invalidFields": {}
}

Overview

The Event Postback API fires a named tracking event against an existing lead. Use it to signal downstream actions — such as phone call completions, form steps, quote views, or conversions — that occur after the initial lead submission. When an event is a conversion event, a revenue value can be passed to trigger payout processing and buyer postbacks. The endpoint is typically called from your webflow or landing page JavaScript using the Pingtree SDK, but it can also be called server-side.

Endpoint

POST /api/event/trigger

Authentication

No token-based authentication header is required for this endpoint. Campaign identity is established through the cid field in the request body.

Request Parameters

Body Parameters (JSON)

Parameter	Type	Required	Description
`cid`	string	Yes	Campaign unique ID
`event_id`	string	Yes	Unique event identifier configured in the campaign event settings
`transaction_id`	string	Yes	Transaction ID of the lead this event belongs to
`pid`	string	No	Source unique ID. Defaults to `organic` if omitted
`revenue`	number	Conditional	Revenue amount for conversion events (required when the event is a conversion type)

Example Request

curl -X POST "https://api.pingtree.com/api/event/trigger" \
  -H "Content-Type: application/json" \
  -d '{
    "cid": "cmp_9z8y7x6w",
    "event_id": "quote_viewed",
    "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456",
    "pid": "src_abc123"
  }'

Conversion Event with Revenue

curl -X POST "https://api.pingtree.com/api/event/trigger" \
  -H "Content-Type: application/json" \
  -d '{
    "cid": "cmp_9z8y7x6w",
    "event_id": "sale_completed",
    "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456",
    "pid": "src_abc123",
    "revenue": 45.00
  }'

Example Responses

Success — Event Fired

{
  "status": 200,
  "message": "Event triggered successfully",
  "data": {
    "cid": "cmp_9z8y7x6w",
    "pid": "src_abc123",
    "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456",
    "conversion_id": "",
    "conversion": false
  }
}

Success — Conversion Event Fired

{
  "status": 200,
  "message": "Event triggered successfully",
  "data": {
    "cid": "cmp_9z8y7x6w",
    "pid": "src_abc123",
    "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456",
    "conversion_id": "conv_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "conversion": true
  }
}

Error — Missing Event ID

{
  "status": 400,
  "message": "event_id is required"
}

Error — Missing Transaction ID

{
  "status": 400,
  "message": "transaction_id is required"
}

Error — Invalid Event ID

{
  "status": 400,
  "message": "Invalid event_id for this campaign"
}

Error — Duplicate Event (deduplication enabled)

{
  "status": 400,
  "message": "Duplicate event for this transaction_id"
}

Error — Source Inactive

{
  "status": 403,
  "message": "Source Inactive"
}

Status Codes

HTTP Code	Description
200	Event fired successfully
400	Missing or invalid `event_id`, `transaction_id`, `cid`, or `revenue`
403	Source is inactive or concurrent event in progress
500	Internal server error

Tips

Event IDs must be pre-configured. The event_id value must match an event defined in the campaign’s event settings. Contact your campaign manager to confirm available event IDs.
Conversion events require revenue. If the event is marked as a conversion type in the campaign settings, omitting revenue returns a 400 error.
Deduplication: If the campaign event has duplicate conversion disabled, firing the same event_id + transaction_id combination a second time returns a 400 duplicate error. Enable isDuplicate in event settings to allow repeated firing.
Concurrent lock: The API applies a 2-second lock per transaction_id + event_id pair to prevent race conditions from duplicate HTTP requests. Retries within this window return a 403.
SDK usage: When using the Pingtree JS SDK on a webflow, events are typically fired automatically based on user interactions. Direct API calls are for server-side or non-webflow implementations.

Path Parameters

campaign-id

string

required

Your campaign 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

event_id

string

required

Event ID which you want to fire for the lead

clid

string

clid of the offer

amount

number

Amount is conversion amount for lead

pid

string

PID is partner ID

conversion_date

string

conversion_date should be as following, 'YYYY-MM-DD' or 'YYYY-MM-DD HH:MM:SS'

conversion_timezone

string

conversion_timezone should be as following, 'PST'(For Pacific Stand Time (UTC-8)), 'EST'(For Eastern Standard Time (UTC-5)), 'CST'(For Central Standard Time (UTC-6)), 'MST'(For Mountain Standard Time (UTC-7)), 'AKST'(For laska Standard Time (UTC-9)), 'SST'(For Samoa Standard Time (UTC-11)), 'HST'(For Hawaii-Aleutian Time (UTC-10)), 'AST'(For Atlantic Standard Time (UTC−4)

sub1

string

Sub ID 1 of lead's partner tracking URL

sub2

string

Sub ID 2 of lead's partner tracking URL

sub3

string

Sub ID 3 of lead's partner tracking URL

sub4

string

Sub ID 4 of lead's partner tracking URL

sub5

string

Sub ID 5 of lead's partner tracking URL

adv1

string

Adv ID 1 of lead's partner tracking URL

adv2

string

Adv ID 2 of lead's partner tracking URL

adv3

string

Adv ID 3 of lead's partner tracking URL

adv4

string

Adv ID 4 of lead's partner tracking URL

adv5

string

Adv ID 5 of lead's partner tracking URL

utm_source

string

UTM Source of lead's partner tracking URL

utm_medium

string

UTM Medium of lead's partner tracking URL

utm_campaign

string

UTM Campaign of lead's partner tracking URL

utm_adgroup

string

UTM AdGroup of lead's partner tracking URL

utm_matchtype

string

UTM MatchType of lead's partner tracking URL

utm_term

string

UTM Term of lead's partner tracking URL

utm_content

string

UTM Content of lead's partner tracking URL

external_clickid

string

External Click ID of lead's partner tracking URL

utm_creative

string

UTM Creative of lead's partner tracking URL

utm_placement

string

UTM Placement of lead's partner tracking URL

TCPA Consent Date in YYYY-MM-DD format

TCPA consent field as 0 or 1

cost

number

Cost of the lead

cost_operation

string

Cose Operation for of the lead's cost. Possible values are 'add', 'substract', and 'override'.

adSpend

number

Adspend of the lead

min_price

number

Send minimum buying price to buyer, if buyer is ready to buy lead at min price or greater, then only we will sell lead

{key}

You can send any other lead details like first_name, last_name, address, etc. You can find all lead fields in the 'Field Management' Page inside your Pingree account.

Response

Event successfully fired

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

missingFields

object

Missing lead's fields

invalidFields

object

Missing lead's fields

Create Source Form 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/Form-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/event/{campaign-id} \
  --header 'Content-Type: application/json' \
  --data '
{
  "transaction_id": "<string>",
  "event_id": "<string>",
  "clid": "<string>",
  "amount": 123,
  "pid": "<string>",
  "conversion_date": "<string>",
  "conversion_timezone": "<string>",
  "sub1": "<string>",
  "sub2": "<string>",
  "sub3": "<string>",
  "sub4": "<string>",
  "sub5": "<string>",
  "adv1": "<string>",
  "adv2": "<string>",
  "adv3": "<string>",
  "adv4": "<string>",
  "adv5": "<string>",
  "utm_source": "<string>",
  "utm_medium": "<string>",
  "utm_campaign": "<string>",
  "utm_adgroup": "<string>",
  "utm_matchtype": "<string>",
  "utm_term": "<string>",
  "utm_content": "<string>",
  "external_clickid": "<string>",
  "utm_creative": "<string>",
  "utm_placement": "<string>",
  "tcpa_consent_date": "<string>",
  "tcpa_consent": 123,
  "cost": 123,
  "cost_operation": "<string>",
  "adSpend": 123,
  "min_price": 123
}
'

{
  "status": "<string>",
  "type": "<string>",
  "message": "<string>",
  "missingFields": {},
  "invalidFields": {}
}

​Overview

​Endpoint

​Authentication

​Request Parameters

​Body Parameters (JSON)

​Example Request

​Conversion Event with Revenue

​Example Responses

​Success — Event Fired

​Success — Conversion Event Fired

​Error — Missing Event ID

​Error — Missing Transaction ID

​Error — Invalid Event ID

​Error — Duplicate Event (deduplication enabled)

​Error — Source Inactive

​Status Codes

​Tips

Path Parameters

Body

Response

Overview

Endpoint

Authentication

Request Parameters

Body Parameters (JSON)

Example Request

Conversion Event with Revenue

Example Responses

Success — Event Fired

Success — Conversion Event Fired

Error — Missing Event ID

Error — Missing Transaction ID

Error — Invalid Event ID

Error — Duplicate Event (deduplication enabled)

Error — Source Inactive

Status Codes

Tips