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.

Request Headers:

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.

Query Parameters:

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#

Request Body:

{
  "type": "email",
  "value": "optout@example.com"
}

Remove from Suppression List#

Request Body:

{
  "type": "email",
  "value": "optout@example.com"
}

Fetch Suppression List#

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:

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.