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

# Source API Reference

> API documentation for programmatic lead submission, retrieval, and suppression list management for a Pingtree database source.

## Overview

Every database source in Pingtree exposes a set of HTTP API endpoints for programmatic interaction. You can submit new leads, fetch existing leads, manage suppression lists, and regenerate authentication tokens — all via REST API.

The API documentation specific to your source is accessible directly from the **Source API Help** tab within any database source.

***

## Authentication

All API requests require your database source's unique API key. Include it in the request header:

```
Authorization: Bearer YOUR_API_KEY
```

The API key is generated when the database source is created. Keep it secure — treat it like a password.

> **Tip:** If you suspect an API key has been compromised, regenerate it immediately from the Source API Help tab. All future requests must use the new key.

***

## Endpoints

### Create Lead (Submit)

Submit a new lead to the database source.

| Property     | Value                                   |
| ------------ | --------------------------------------- |
| **Method**   | `POST`                                  |
| **Endpoint** | `/api/v1/database-source/{slug}/create` |

**Request Headers:**

| Header          | Value                 |
| --------------- | --------------------- |
| `Authorization` | `Bearer YOUR_API_KEY` |
| `Content-Type`  | `application/json`    |

**Request Body:**

```json theme={null}
{
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane.smith@example.com",
  "phone": "5551234567",
  "state": "CA",
  "zip": "90210"
}
```

**Success Response (200):**

```json theme={null}
{
  "success": true,
  "lead_id": "64f2a3b1c9e77d001234abcd",
  "message": "Lead created successfully."
}
```

**Duplicate Response (200):**

```json theme={null}
{
  "success": false,
  "reason": "duplicate",
  "message": "A lead with this email already exists in the source."
}
```

**Validation Error Response (400):**

```json theme={null}
{
  "success": false,
  "reason": "validation_error",
  "errors": {
    "email": "Email field is required.",
    "phone": "Phone must be a 10-digit number."
  }
}
```

***

### Fetch Leads (Retrieve)

Retrieve leads from the database source with optional filtering.

| Property     | Value                                  |
| ------------ | -------------------------------------- |
| **Method**   | `GET`                                  |
| **Endpoint** | `/api/v1/database-source/{slug}/fetch` |

**Query Parameters:**

| Parameter   | Type    | Description                                                        |
| ----------- | ------- | ------------------------------------------------------------------ |
| `page`      | Integer | Page number for pagination (default: 1).                           |
| `limit`     | Integer | Number of leads per page (default: 50, max: 500).                  |
| `status`    | String  | Filter by lead status (`active`, `sold`, `duplicate`, `rejected`). |
| `email`     | String  | Filter leads by email address.                                     |
| `phone`     | String  | Filter leads by phone number.                                      |
| `from_date` | String  | Filter leads created on or after this date (`YYYY-MM-DD`).         |
| `to_date`   | String  | Filter leads created on or before this date (`YYYY-MM-DD`).        |

**Example Request:**

```
GET /api/v1/database-source/home-insurance-leads/fetch?status=active&from_date=2025-01-01&limit=100
Authorization: Bearer YOUR_API_KEY
```

**Success Response (200):**

```json theme={null}
{
  "success": true,
  "total": 1432,
  "page": 1,
  "limit": 100,
  "leads": [
    {
      "lead_id": "64f2a3b1c9e77d001234abcd",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@example.com",
      "phone": "5551234567",
      "status": "active",
      "created_at": "2025-03-15T10:22:00Z"
    }
  ]
}
```

***

## Token Regeneration

If your API key needs to be rotated for security reasons:

1. Open the **Source API Help** tab within the database source.
2. Click **Regenerate API Key**.
3. Confirm the action.
4. Copy the new API key and update all systems that use it.

> **Warning:** Regenerating the API key immediately invalidates the old key. Any system still using the old key will receive authentication errors until it is updated.

***

## Suppression List Management

The suppression list prevents specific identifiers (email addresses, phone numbers) from being ingested into the source. Any lead submission matching a suppressed value is automatically rejected.

### Add to Suppression List

| Property     | Value                                            |
| ------------ | ------------------------------------------------ |
| **Method**   | `POST`                                           |
| **Endpoint** | `/api/v1/database-source/{slug}/suppression/add` |

**Request Body:**

```json theme={null}
{
  "type": "email",
  "value": "optout@example.com"
}
```

| Field   | Description                                  |
| ------- | -------------------------------------------- |
| `type`  | The type of suppression: `email` or `phone`. |
| `value` | The value to suppress.                       |

### Remove from Suppression List

| Property     | Value                                               |
| ------------ | --------------------------------------------------- |
| **Method**   | `POST`                                              |
| **Endpoint** | `/api/v1/database-source/{slug}/suppression/remove` |

**Request Body:**

```json theme={null}
{
  "type": "email",
  "value": "optout@example.com"
}
```

### Fetch Suppression List

| Property     | Value                                        |
| ------------ | -------------------------------------------- |
| **Method**   | `GET`                                        |
| **Endpoint** | `/api/v1/database-source/{slug}/suppression` |

Returns a paginated list of all suppressed values for this source.

***

## Rate Limiting

To maintain platform stability, API requests to database source endpoints are subject to rate limits:

| Limit           | Value                                  |
| --------------- | -------------------------------------- |
| **Create Lead** | 1,000 requests per minute per API key. |
| **Fetch Leads** | 60 requests per minute per API key.    |
| **Suppression** | 500 requests per minute per API key.   |

When a rate limit is exceeded, the API returns a `429 Too Many Requests` response. Implement exponential backoff in your integration to handle rate limit responses gracefully.

***

## Best Practices

* **Validate data before submission**: Pre-validate email format, phone length, and required fields on your end to minimize rejected leads.
* **Handle duplicate responses**: A duplicate response is not an error — log it and continue processing your batch.
* **Use pagination for large fetches**: Always paginate fetch requests rather than requesting all leads in a single call.
* **Secure your API key**: Never expose the API key in client-side code, public repositories, or unencrypted storage.
* **Monitor response codes**: Log all non-200 responses and alert on sustained error rates to detect integration issues early.