Skip to main content

​
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.
PropertyValue
MethodPOST
Endpoint/api/v1/database-source/{slug}/create
Request Headers:
HeaderValue
AuthorizationBearer YOUR_API_KEY
Content-Typeapplication/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.
PropertyValue
MethodGET
Endpoint/api/v1/database-source/{slug}/fetch
Query Parameters:
ParameterTypeDescription
pageIntegerPage number for pagination (default: 1).
limitIntegerNumber of leads per page (default: 50, max: 500).
statusStringFilter by lead status (active, sold, duplicate, rejected).
emailStringFilter leads by email address.
phoneStringFilter leads by phone number.
from_dateStringFilter leads created on or after this date (YYYY-MM-DD).
to_dateStringFilter 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:
  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

PropertyValue
MethodPOST
Endpoint/api/v1/database-source/{slug}/suppression/add
Request Body: 
{
  "type": "email",
  "value": "optout@example.com"
}
FieldDescription
typeThe type of suppression: email or phone.
valueThe value to suppress.

​
Remove from Suppression List

PropertyValue
MethodPOST
Endpoint/api/v1/database-source/{slug}/suppression/remove
Request Body: 
{
  "type": "email",
  "value": "optout@example.com"
}

​
Fetch Suppression List

PropertyValue
MethodGET
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:
LimitValue
Create Lead1,000 requests per minute per API key.
Fetch Leads60 requests per minute per API key.
Suppression500 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.