Lead Fetch API

Overview#

The Database Source Lead Fetch API retrieves lead records stored in a database source. It is designed for use cases such as lead validation lookups, deduplication checks, CRM syncs, and data exports. Leads can be looked up by field value (e.g. email or mobile) or retrieved as a paginated list.

Authentication uses the same database source API key as the Lead Posting API.

Endpoint#

GET /api/lead/fetch/{db-source-id}

Replace {db-source-id} with the MongoDB Object ID of the database source.

Authentication#

Include the database source API key in the Authorization header:

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

Request Parameters#

Path Parameters#

Query Parameters#

At least one filter parameter is recommended. Calling the endpoint without any filters returns a paginated list of all leads in the source.

Example Requests#

Look Up by Email#

curl -G "https://api.pingtree.com/api/lead/fetch/64a1b2c3d4e5f6a7b8c9d0e1" \
  -H "Authorization: Bearer sk_live_abc123xyz789..." \
  --data-urlencode "email=sarah.connor@example.com"

Look Up by Mobile#

curl -G "https://api.pingtree.com/api/lead/fetch/64a1b2c3d4e5f6a7b8c9d0e1" \
  -H "Authorization: Bearer sk_live_abc123xyz789..." \
  --data-urlencode "mobile=3105559876"

Paginated List with Date Range#

curl -G "https://api.pingtree.com/api/lead/fetch/64a1b2c3d4e5f6a7b8c9d0e1" \
  -H "Authorization: Bearer sk_live_abc123xyz789..." \
  --data-urlencode "from=2025-08-01" \
  --data-urlencode "to=2025-08-31" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=50"

Example Responses#

Success — Lead Found#

{
  "status": 200,
  "message": "Lead found",
  "data": {
    "leads": [
      {
        "transaction_id": "db_txn_7f3a2b1c-4d56-78ef-9012-abcdef123456",
        "first_name": "Sarah",
        "last_name": "Connor",
        "email": "sarah.connor@example.com",
        "mobile": "3105559876",
        "state": "CA",
        "zip_code": "90210",
        "db_source_id": "64a1b2c3d4e5f6a7b8c9d0e1",
        "createdAt": "2025-08-14T10:32:00.000Z"
      }
    ],
    "totalRecord": 1
  }
}

Success — No Leads Found#

{
  "status": 200,
  "message": "No leads found",
  "data": {
    "leads": [],
    "totalRecord": 0
  }
}

Error — Invalid Source ID#

{
  "status": 400,
  "message": "Database source not found or invalid ID"
}

Error — Unauthorized#

{
  "status": 401,
  "message": "Unauthorized"
}

Status Codes#

Deduplication Check Endpoint#

For a lightweight existence check (without retrieving the full record), use the dedupe check endpoint:

GET /api/lead/check/:sourceID?email=sarah.connor@example.com

This returns a boolean isDuplicate flag and is faster than the full fetch for real-time deduplication at point of submission.

Tips#

• Use specific filters. Fetching without filters pulls all leads and may be slow on large sources. Always filter by email, mobile, or transaction_id for point lookups.
• Pagination for exports. When exporting all leads, iterate through pages using page and limit. Check totalRecord to determine how many pages to fetch (Math.ceil(totalRecord / limit)).
• Field visibility. PII fields (email, mobile) are stored encrypted. The API decrypts and returns them in the response, but ensure your integration handles this data in compliance with your data privacy obligations.
• Atlas Search. Database sources with Elasticsearch/Atlas Search enabled support faster and case-insensitive field lookups. Contact your account manager to enable this for high-volume sources.
• Allowed fields. Only fields in the source's allowed fields list are stored and returned. Fields outside this list are not present in fetch results.