Source API Reference

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:

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

Success Response (200):

{
  "success": true,
  "lead_id": "64f2a3b1c9e77d001234abcd",
  "message": "Lead created successfully."
}

Duplicate Response (200):

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

Validation Error Response (400):

{
  "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):

{
  "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:

Open the Source API Help tab within the database source.
Click Regenerate API Key.
Confirm the action.
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:

{
  "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:

{
  "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.

Welcome to Pingtree

Dashboard

Campaign Management

Call Management

Creative Library

Funnel Builder

Analytics

Account Billing

System Database

Settings

Team Management

Reporting Hub

Marketing Partner Portal

Domain Management

Platform

Integrations

Overview

Authentication

Endpoints

Create Lead (Submit)

Fetch Leads (Retrieve)

Token Regeneration

Suppression List Management

Add to Suppression List

Remove from Suppression List

Fetch Suppression List

Rate Limiting

Best Practices

​Overview

​Authentication

​Endpoints

​Create Lead (Submit)

​Fetch Leads (Retrieve)

​Token Regeneration

​Suppression List Management

​Add to Suppression List

​Remove from Suppression List

​Fetch Suppression List

​Rate Limiting

​Best Practices

Overview

Authentication

Endpoints

Create Lead (Submit)

Fetch Leads (Retrieve)

Token Regeneration

Suppression List Management

Add to Suppression List

Remove from Suppression List

Fetch Suppression List

Rate Limiting

Best Practices