> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pingtree.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Global Event Postback API

> The Event Postback API is designed to trigger events that track and update lead data. It also supports converting leads into successful conversions, ensuring real-time data synchronization and improved campaign insights.

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

```bash theme={null}
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

```bash theme={null}
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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "status": 400,
  "message": "event_id is required"
}
```

### Error — Missing Transaction ID

```json theme={null}
{
  "status": 400,
  "message": "transaction_id is required"
}
```

### Error — Lead Not Found

```json theme={null}
{
  "status": 400,
  "message": "No lead found for the provided transaction_id in this organization"
}
```

### Error — Invalid Event ID

```json theme={null}
{
  "status": 400,
  "message": "Invalid event_id — event not configured for the associated campaign"
}
```

### Error — Duplicate Event

```json theme={null}
{
  "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}`


## OpenAPI

````yaml POST /api/event/global/{org-id}
openapi: 3.1.0
info:
  title: Pingtree API Explore
  description: >-
    The Pingtree API Explore is a comprehensive guide designed to help you
    understand and integrate the Pingtree API effectively. It provides detailed
    insights into API endpoints, request parameters, and response structures to
    facilitate seamless lead distribution and tracking. Whether you're building
    custom integrations, automating lead flows, or optimizing campaign
    performance, this guide empowers you with the knowledge to leverage
    Pingtree's capabilities for enhanced lead management and improved results.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.pingtree.com
security: []
paths:
  /api/event/global/{org-id}:
    post:
      description: >-
        The Event Postback API is designed to trigger events that track and
        update lead data. It also supports converting leads into successful
        conversions, ensuring real-time data synchronization and improved
        campaign insights.
      parameters:
        - name: org-id
          required: true
          in: path
          description: Your organization ID
          schema:
            type: string
      requestBody:
        description: Lead details to add to the campaign
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/lead-event-data'
      responses:
        '201':
          description: Event successfully fired
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Status code of API response
                  type:
                    type: string
                    description: Type of API response which can be success or error
                  message:
                    type: string
                    description: Message of API response
                  missingFields:
                    type: object
                    description: Missing lead's fields
                  invalidFields:
                    type: object
                    description: Missing lead's fields
        '400':
          description: >-
            Unexpected error, transaction_id or cid not found in the requested
            data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lead-response'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lead-response'
components:
  schemas:
    lead-event-data:
      required:
        - transaction_id
        - event_id
      type: object
      properties:
        transaction_id:
          description: >-
            Lead's Transaction ID, Which was generate from click script of
            Pingtree
          type: string
        event_id:
          description: Event ID which you want to fire for the lead
          type: string
        clid:
          description: clid of the offer
          type: string
        amount:
          description: Amount is conversion amount for lead
          type: number
        pid:
          description: PID is partner ID
          type: string
        conversion_date:
          description: >-
            conversion_date should be as following, 'YYYY-MM-DD' or 'YYYY-MM-DD
            HH:MM:SS'
          type: string
        conversion_timezone:
          description: >-
            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)
          type: string
        sub1:
          description: Sub ID 1 of lead's partner tracking URL
          type: string
        sub2:
          description: Sub ID 2 of lead's partner tracking URL
          type: string
        sub3:
          description: Sub ID 3 of lead's partner tracking URL
          type: string
        sub4:
          description: Sub ID 4 of lead's partner tracking URL
          type: string
        sub5:
          description: Sub ID 5 of lead's partner tracking URL
          type: string
        adv1:
          description: Adv ID 1 of lead's partner tracking URL
          type: string
        adv2:
          description: Adv ID 2 of lead's partner tracking URL
          type: string
        adv3:
          description: Adv ID 3 of lead's partner tracking URL
          type: string
        adv4:
          description: Adv ID 4 of lead's partner tracking URL
          type: string
        adv5:
          description: Adv ID 5 of lead's partner tracking URL
          type: string
        utm_source:
          description: UTM Source of lead's partner tracking URL
          type: string
        utm_medium:
          description: UTM Medium of lead's partner tracking URL
          type: string
        utm_campaign:
          description: UTM Campaign of lead's partner tracking URL
          type: string
        utm_adgroup:
          description: UTM AdGroup of lead's partner tracking URL
          type: string
        utm_matchtype:
          description: UTM MatchType of lead's partner tracking URL
          type: string
        utm_term:
          description: UTM Term of lead's partner tracking URL
          type: string
        utm_content:
          description: UTM Content of lead's partner tracking URL
          type: string
        external_clickid:
          description: External Click ID of lead's partner tracking URL
          type: string
        utm_creative:
          description: UTM Creative of lead's partner tracking URL
          type: string
        utm_placement:
          description: UTM Placement of lead's partner tracking URL
          type: string
        tcpa_consent_date:
          description: TCPA Consent Date in YYYY-MM-DD format
          type: string
        tcpa_consent:
          description: TCPA consent field as 0 or 1
          type: number
        cost:
          description: Cost of the lead
          type: number
        cost_operation:
          description: >-
            Cose Operation for of the lead's cost. Possible values are 'add',
            'substract', and 'override'.
          type: string
        adSpend:
          description: Adspend of the lead
          type: number
        min_price:
          description: >-
            Send minimum buying price to buyer, if buyer is ready to buy lead at
            min price or greater, then only we will sell lead
          type: number
      additionalProperties:
        description: >-
          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.
        oneOf:
          - type: string
          - type: number
          - type: boolean
    lead-response:
      type: object
      properties:
        status:
          type: string
          description: Status code of API response
        type:
          type: string
          description: Type of API response which can be success or error
        message:
          type: string
          description: Message of API response

````