Global Event Postback API - Pingtree Documentation

POST

api

event

global

{org-id}

cURL

curl --request POST \
  --url https://api.pingtree.com/api/event/global/{org-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 Global Event Postback API fires a conversion or tracking event across all campaigns within an organization using a single endpoint. It is designed for buyers and third-party systems that receive leads from multiple campaigns but want to post conversion data back using one consistent URL — without needing a different endpoint per campaign. Pingtree resolves the campaign and lead from the transaction_id automatically. No cid is required in the request body.

Endpoint

POST /api/event/global/{org-id}

Replace {org-id} with your organization’s unique ID (available in your Pingtree dashboard under account settings).

Authentication

No token-based authentication header is required. The org-id path parameter scopes the request to your organization.

Request Parameters

Path Parameters

Parameter	Type	Required	Description
`org-id`	string	Yes	Organization unique ID

Body Parameters (JSON)

Parameter	Type	Required	Description
`event_id`	string	Yes	Unique event identifier as configured in the campaign event settings
`transaction_id`	string	Yes	Transaction ID of the lead record to fire the event against
`revenue`	number	Conditional	Revenue amount for conversion events
`pid`	string	No	Source unique ID (defaults to `organic` if omitted)

Example Request

curl -X POST "https://api.pingtree.com/api/event/global/org_5f1a2b3c" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "sale_completed",
    "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456",
    "revenue": 85.00
  }'

Non-Conversion Event

curl -X POST "https://api.pingtree.com/api/event/global/org_5f1a2b3c" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "application_submitted",
    "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456"
  }'

Example Responses

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
  }
}

Success — Tracking 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
  }
}

Error — Missing Event ID

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

Error — Missing Transaction ID

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

Error — Lead Not Found

{
  "status": 400,
  "message": "No lead found for the provided transaction_id in this organization"
}

Error — Invalid Event ID

{
  "status": 400,
  "message": "Invalid event_id — event not configured for the associated campaign"
}

Error — Duplicate Event

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

Status Codes

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

Comparison with Campaign-Specific Event Postback

Feature	Global Event Postback	Campaign Event Postback
Endpoint	`/api/event/global/{org-id}`	`/api/event/trigger`
Requires `cid`	No	Yes
Scope	All campaigns in the organization	Single campaign
Ideal for	Buyers posting back across multiple campaigns	Campaign-specific event tracking
Authentication	`org-id` in path	`cid` in request body

Tips

Preferred endpoint for buyers. If you are a buyer receiving leads from multiple campaigns within the same organization, use this global endpoint to avoid managing per-campaign event URLs.
Event ID must exist in the matched campaign. Even though you do not pass a cid, Pingtree resolves the campaign from the transaction_id. The event_id must be configured in that campaign’s event settings.
Revenue is required for conversion events. If the matched event is a conversion type, omitting revenue returns a 400 error.
Deduplication. If the campaign event has duplicate conversion disabled, sending the same event_id + transaction_id a second time returns a 400 duplicate error.
Postback URL format. When configuring this as a server-to-server postback URL in a third-party platform, use a template like: https://api.pingtree.com/api/event/global/org_5f1a2b3c?event_id=sale_completed&transaction_id={transaction_id}&revenue={payout}

Path Parameters

org-id

string

required

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

Lead Fetch APIThe Fetch Lead API allows users to retrieve stored lead data from the database source. This functionality is useful for validating data, generating reports, or ensuring seamless follow-ups.

cURL

curl --request POST \
  --url https://api.pingtree.com/api/event/global/{org-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": {}
}

Documentation Index

​Overview

​Endpoint

​Authentication

​Request Parameters

​Path Parameters

​Body Parameters (JSON)

​Example Request

​Non-Conversion Event

​Example Responses

​Success — Conversion Event Fired

​Success — Tracking Event Fired

​Error — Missing Event ID

​Error — Missing Transaction ID

​Error — Lead Not Found

​Error — Invalid Event ID

​Error — Duplicate Event

​Status Codes

​Comparison with Campaign-Specific Event Postback

​Tips

Path Parameters

Body

Response

Overview

Endpoint

Authentication

Request Parameters

Path Parameters

Body Parameters (JSON)

Example Request

Non-Conversion Event

Example Responses

Success — Conversion Event Fired

Success — Tracking Event Fired

Error — Missing Event ID

Error — Missing Transaction ID

Error — Lead Not Found

Error — Invalid Event ID

Error — Duplicate Event

Status Codes

Comparison with Campaign-Specific Event Postback

Tips