Skip to main content
GET
/
api
/
lead
/
fetch
/
{db-source-id}
cURL
curl --request GET \
  --url https://api.pingtree.com/api/lead/fetch/{db-source-id} \
  --header 'Authorization: Bearer <token>'
{
  "status": "<string>",
  "message": "<string>",
  "data": {}
}

​
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

ParameterTypeRequiredDescription
db-source-idstringYesMongoDB Object ID of the database source

​
Query Parameters

ParameterTypeRequiredDescription
emailstringNoFilter by email address
mobilestringNoFilter by 10-digit phone number
transaction_idstringNoFetch a specific lead by transaction ID
lookup_idstringNoFetch by a custom lookup field value
pageintegerNoPage number for paginated results (default: 1)
limitintegerNoRecords per page (default: 10, max: 100)
fromstringNoStart date filter (ISO 8601: YYYY-MM-DD)
tostringNoEnd date filter (ISO 8601: YYYY-MM-DD)
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

HTTP CodeDescription
200Request successful (leads array may be empty if none match)
400Invalid source ID or query parameters
401Invalid or missing API key
500Internal server error

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

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
db-source-id
string
required

Your database source ID

Query Parameters

​
lookup_id
string

Your lead's unique ID

​
transaction_id
string

Your lead's transaction ID

​
mobile
string

Your lead's mobile number

​
email
string

Your lead's email address

​
lookup_postfix
string

Your lead's unique identification code or unque code

Response

Lead successfully created

​
status
string

Status code of API response

​
message
string

Message of API response

​
data
object

Created lead information such as transaction_id, lead_status, etc.