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

# Create Source Ping API

> The 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/Ping-+-Post-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.

## Overview

The Source Ping API is the first step in a two-call ping-post flow. It submits partial lead data to determine whether buyers are willing to purchase the lead and at what price — before any PII (personally identifiable information) is committed. If the ping is accepted, you receive a `transaction_id` and bid information, which you then use to complete the submission via the [Source Post API](/api-explore/offer-campaign/source-post-api).

Use ping-post when you want buyer intent confirmation before collecting or submitting full consumer data.

## Endpoint

```
POST /api/lead/ping/{source-unique-id}
```

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

## Authentication

Include the ping-specific API token in the `Authorization` header:

```
Authorization: Bearer <your-ping-token>
```

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

Ping requests typically include non-PII fields sufficient for buyer evaluation. Required fields are defined in your posting specification.

| Parameter        | Type    | Required    | Description                                       |
| ---------------- | ------- | ----------- | ------------------------------------------------- |
| `state`          | string  | Conditional | 2-letter state code (used for geo-targeting)      |
| `zip_code`       | string  | Conditional | 5-digit ZIP code                                  |
| `age`            | integer | No          | Consumer age (alternative to `date_of_birth`)     |
| `sub1` – `sub5`  | string  | No          | Publisher sub-tracking parameters                 |
| `adv1` – `adv5`  | string  | No          | Advertiser sub-parameters                         |
| `utm_source`     | string  | No          | UTM source                                        |
| `utm_medium`     | string  | No          | UTM medium                                        |
| `transaction_id` | string  | No          | Publisher-generated ID; auto-generated if omitted |

Custom campaign-specific fields (e.g. `loan_amount`, `insurance_type`, `home_owner`) are often included in pings as they affect buyer bid logic. Check your posting spec for the full list.

## Example Request

```bash theme={null}
curl -X POST "https://api.pingtree.com/api/lead/ping/lnk_abc123xyz" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "state": "CA",
    "zip_code": "90001",
    "loan_amount": 15000,
    "credit_score": "good",
    "home_owner": true,
    "sub1": "pub-campaign-001"
  }'
```

## Example Responses

### Success — Ping Accepted

```json theme={null}
{
  "status": "201",
  "message": "Ping accepted",
  "data": {
    "leadStatus": "ping_accept",
    "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456",
    "isDeDupe": false,
    "message": "Ping accepted",
    "amount": "45.00",
    "buyerTcpa": "By submitting this form you agree to be contacted by XYZ Lenders..."
  }
}
```

### Success — Ping Rejected (no buyers)

```json theme={null}
{
  "status": "201",
  "message": "Ping rejected",
  "data": {
    "leadStatus": "ping_reject",
    "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456",
    "isDeDupe": false,
    "message": "No buyers available for this lead"
  }
}
```

### Error — Missing Required Field

```json theme={null}
{
  "status": "400",
  "message": "Missing required field: state",
  "data": {
    "leadStatus": "missingField"
  }
}
```

### Error — Unauthorized

```json theme={null}
{
  "status": "401",
  "message": "Unauthorized",
  "data": {
    "leadStatus": "rejected"
  }
}
```

## Status Codes

| HTTP Code | Lead Status    | Description                                          |
| --------- | -------------- | ---------------------------------------------------- |
| 201       | `ping_accept`  | At least one buyer bid on this lead; proceed to post |
| 201       | `ping_reject`  | No buyers matched; do not post                       |
| 400       | `missingField` | Required field absent                                |
| 400       | `invalidField` | Field failed format validation                       |
| 400       | `rejected`     | Campaign or source rule rejected the ping            |
| 401       | `rejected`     | Invalid or missing ping token                        |
| 405       | `rejected`     | HTTP method not allowed                              |
| 500       | `rejected`     | Internal server error                                |

## Tips

* **Ping before collecting PII:** Submit only the non-identifying lead attributes during the ping. Only proceed to collect name, email, and phone if the ping returns `ping_accept`.
* **Store the `transaction_id`:** This ID must be included in the subsequent Post API call to link the two steps together.
* **`amount` field:** The bid amount returned in the ping response (`data.amount`) can be used to display personalized offer messaging to the consumer before they complete the form.
* **`buyerTcpa`:** Some campaigns return buyer-specific TCPA consent language in the ping response. Display this text to the consumer before they submit their full details in the post step.
* **Ping TTL:** A ping acceptance has a limited validity window (typically a few minutes). If too much time passes before the post call, the lead may be rejected or re-evaluated.
* **Do not post on rejection:** If `leadStatus` is `ping_reject`, do not proceed with the post call. Instead, consider an alternative buyer path or inform the consumer that offers are unavailable.


## OpenAPI

````yaml POST /api/lead/ping/{source-unique-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: {}

````