> ## 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. # 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 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 ```bash theme={null} 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 ```bash theme={null} 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 ```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 } } ``` ### 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 } } ``` ### 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 — Invalid Event ID ```json theme={null} { "status": 400, "message": "Invalid event_id for this campaign" } ``` ### Error — Duplicate Event (deduplication enabled) ```json theme={null} { "status": 400, "message": "Duplicate event for this transaction_id" } ``` ### Error — Source Inactive ```json theme={null} { "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. ## OpenAPI ````yaml POST /api/event/{campaign-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/{campaign-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: campaign-id required: true in: path description: Your campaign 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 or event_id 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 ````