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

# Lead Posting API

> The Create Lead API is used to add new lead data directly to the database source. This API is essential for maintaining comprehensive lead records and ensuring data is accurately stored across database source.

## Overview

The Database Source Lead Posting API creates a new lead record directly in a database source. Unlike the offer campaign form API, this endpoint stores leads in a standalone database source — used as a centralised lead repository, suppression list, or feed for downstream campaigns. Both GET and POST HTTP methods are supported.

Authentication is via the database source's API key, which is auto-generated when the source is created.

## Endpoint

```
POST /api/lead/create/{db-source-id}
GET  /api/lead/create/{db-source-id}
```

Replace `{db-source-id}` with the MongoDB Object ID of the database source. This is available in the Pingtree dashboard under Database Sources.

## Authentication

Include the database source API key in the `Authorization` header:

```
Authorization: Bearer <db-source-api-key>
```

The API key is generated when the database source is created and can be found on the source's detail page.

## Request Parameters

### Path Parameters

| Parameter      | Type   | Required | Description                              |
| -------------- | ------ | -------- | ---------------------------------------- |
| `db-source-id` | string | Yes      | MongoDB Object ID of the database source |

### Body / Query Parameters

Fields accepted depend on the required fields configured for the database source. Common system fields include:

| Parameter        | Type   | Required    | Description                                       |
| ---------------- | ------ | ----------- | ------------------------------------------------- |
| `first_name`     | string | Conditional | Consumer's first name                             |
| `last_name`      | string | Conditional | Consumer's last name                              |
| `email`          | string | Conditional | Email address (validated as a valid email format) |
| `mobile`         | string | Conditional | 10-digit phone number (digits only)               |
| `address`        | string | Conditional | Street address                                    |
| `city`           | string | Conditional | City name (letters and spaces only)               |
| `state`          | string | Conditional | 2-letter state abbreviation                       |
| `zip_code`       | string | Conditional | 5-digit ZIP code                                  |
| `transaction_id` | string | No          | Custom transaction ID; auto-generated if omitted  |

For GET requests, pass parameters as query string values. For POST requests, send as a JSON body or form-encoded body.

The exact required fields are configured per database source. Invalid or missing required fields result in rejection with a list of affected field names.

## Example Request — POST

```bash theme={null}
curl -X POST "https://api.pingtree.com/api/lead/create/64a1b2c3d4e5f6a7b8c9d0e1" \
  -H "Authorization: Bearer sk_live_abc123xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Sarah",
    "last_name": "Connor",
    "email": "sarah.connor@example.com",
    "mobile": "3105559876",
    "address": "999 Future Rd",
    "city": "Los Angeles",
    "state": "CA",
    "zip_code": "90210"
  }'
```

## Example Request — GET

```bash theme={null}
curl "https://api.pingtree.com/api/lead/create/64a1b2c3d4e5f6a7b8c9d0e1?first_name=Sarah&last_name=Connor&email=sarah.connor%40example.com&mobile=3105559876&zip_code=90210" \
  -H "Authorization: Bearer sk_live_abc123xyz789..."
```

## Example Responses

### Success — Lead Created

```json theme={null}
{
  "status": 201,
  "message": "Lead successfully created",
  "data": {
    "leadStatus": "accept",
    "transaction_id": "db_txn_7f3a2b1c-4d56-78ef-9012-abcdef123456"
  }
}
```

### Success — Duplicate Lead

```json theme={null}
{
  "status": 201,
  "message": "Duplicate lead",
  "data": {
    "leadStatus": "duplicate",
    "transaction_id": "db_txn_7f3a2b1c-4d56-78ef-9012-abcdef123456"
  }
}
```

### Error — Missing Required Field

```json theme={null}
{
  "status": 400,
  "message": "Missing required fields",
  "data": {
    "leadStatus": "missingField",
    "missingFields": ["email", "mobile"]
  }
}
```

### Error — Invalid Field

```json theme={null}
{
  "status": 400,
  "message": "Invalid field value",
  "data": {
    "leadStatus": "invalidField",
    "invalidFields": ["email"]
  }
}
```

### Error — Unauthorized

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

### Error — Source Not Found or Inactive

```json theme={null}
{
  "status": 400,
  "message": "Database source not found or inactive"
}
```

## Status Codes

| HTTP Code | Lead Status    | Description                                             |
| --------- | -------------- | ------------------------------------------------------- |
| 201       | `accept`       | Lead created successfully                               |
| 201       | `duplicate`    | Lead already exists (deduplication enabled and matched) |
| 400       | `missingField` | One or more required fields are absent                  |
| 400       | `invalidField` | One or more fields failed format validation             |
| 401       | —              | Invalid or missing API key                              |
| 500       | —              | Internal server error                                   |

## Deduplication

If the database source has deduplication enabled, the configured duplicate field (e.g. `email` or `mobile`) is checked against existing records before the lead is stored. If a match is found, the lead status is `duplicate` and the record is not stored again.

## Tips

* **API key security.** The database source API key grants write access to that source. Keep it confidential and rotate it if compromised (via the Pingtree dashboard).
* **GET vs POST.** GET requests are useful for simple server-to-server integrations or pixel-style firing. POST with a JSON body is recommended for production use.
* **Allowed fields list.** The source can be configured with an allowed fields list that restricts which fields are accepted. Fields outside this list are silently ignored.
* **TrustedForm fields.** `xxTrustedFormToken`, `xxTrustedFormCertUrl`, and `xxTrustedFormPingUrl` are automatically mapped to internal fields if present in the request.
* **Rate limiting.** Database source endpoints are rate-limited per source. Contact your account manager if you need higher throughput limits.


## OpenAPI

````yaml POST /api/lead/create/{db-source-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/lead/create/{db-source-id}:
    post:
      description: >-
        The Create Lead API is used to add new lead data directly to the
        database source. This API is essential for maintaining comprehensive
        lead records and ensuring data is accurately stored across database
        source.
      parameters:
        - name: db-source-id
          required: true
          in: path
          description: Your database source ID
          schema:
            type: string
      requestBody:
        description: Lead details to add to the database source
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/lead-without-tid'
      responses:
        '201':
          description: Lead successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Status code of API response
                  message:
                    type: string
                    description: Message of API response
                  data:
                    type: object
                    description: >-
                      Created lead information such as transaction_id,
                      lead_status, etc.
        '400':
          description: Database source not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lead-response'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lead-response'
      security:
        - bearerAuth: []
components:
  schemas:
    lead-without-tid:
      type: object
      properties:
        first_name:
          description: First name of the lead
          type: string
        last_name:
          description: Last name of the lead
          type: string
        email:
          description: Email of the lead
          type: string
        mobile:
          description: Mobile of the lead
          type: string
        address:
          description: Address of the lead
          type: string
        state:
          description: State of the lead
          type: string
        city:
          description: City of the lead
          type: string
        zip_code:
          description: Zip Code of the lead
          type: string
        date_of_birth:
          description: Date of Birth of the lead
          type: string
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````