> ## Documentation Index > Fetch the complete documentation index at: https://docs.pingtree.com/llms.txt > Use this file to discover all available pages before exploring further. # Lead Fetch API > The Fetch Lead API allows users to retrieve stored lead data from the database source. This functionality is useful for validating data, generating reports, or ensuring seamless follow-ups. ## 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 ``` ## Request Parameters ### Path Parameters | Parameter | Type | Required | Description | | -------------- | ------ | -------- | ---------------------------------------- | | `db-source-id` | string | Yes | MongoDB Object ID of the database source | ### Query Parameters | Parameter | Type | Required | Description | | ---------------- | ------- | -------- | ------------------------------------------------ | | `email` | string | No | Filter by email address | | `mobile` | string | No | Filter by 10-digit phone number | | `transaction_id` | string | No | Fetch a specific lead by transaction ID | | `lookup_id` | string | No | Fetch by a custom lookup field value | | `page` | integer | No | Page number for paginated results (default: `1`) | | `limit` | integer | No | Records per page (default: `10`, max: `100`) | | `from` | string | No | Start date filter (ISO 8601: `YYYY-MM-DD`) | | `to` | string | No | End 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 ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} 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 ```json theme={null} { "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 ```json theme={null} { "status": 200, "message": "No leads found", "data": { "leads": [], "totalRecord": 0 } } ``` ### Error — Invalid Source ID ```json theme={null} { "status": 400, "message": "Database source not found or invalid ID" } ``` ### Error — Unauthorized ```json theme={null} { "status": 401, "message": "Unauthorized" } ``` ## Status Codes | HTTP Code | Description | | --------- | ----------------------------------------------------------- | | 200 | Request successful (leads array may be empty if none match) | | 400 | Invalid source ID or query parameters | | 401 | Invalid or missing API key | | 500 | Internal 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. ## OpenAPI ````yaml GET /api/lead/fetch/{db-source-id} openapi: 3.1.0 info: title: Pingtree API Explore description: >- The Pingtree API Explore is a comprehensive guide designed to help you understand and integrate the Pingtree API effectively. It provides detailed insights into API endpoints, request parameters, and response structures to facilitate seamless lead distribution and tracking. Whether you're building custom integrations, automating lead flows, or optimizing campaign performance, this guide empowers you with the knowledge to leverage Pingtree's capabilities for enhanced lead management and improved results. license: name: MIT version: 1.0.0 servers: - url: https://api.pingtree.com security: [] paths: /api/lead/fetch/{db-source-id}: get: description: >- The Fetch Lead API allows users to retrieve stored lead data from the database source. This functionality is useful for validating data, generating reports, or ensuring seamless follow-ups. parameters: - name: db-source-id required: true in: path description: Your database source ID schema: type: string - name: lookup_id in: query description: Your lead's unique ID schema: type: string - name: transaction_id in: query description: Your lead's transaction ID schema: type: string - name: mobile in: query description: Your lead's mobile number schema: type: string - name: email in: query description: Your lead's email address schema: type: string - name: lookup_postfix in: query description: Your lead's unique identification code or unque code schema: type: string responses: '201': description: Lead successfully created content: application/json: schema: type: object properties: status: type: string description: Status code of API response message: type: string description: Message of API response data: type: object description: >- Created lead information such as transaction_id, lead_status, etc. '400': description: Database source not found content: application/json: schema: $ref: '#/components/schemas/lead-response' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/lead-response' security: - bearerAuth: [] components: schemas: lead-response: type: object properties: status: type: string description: Status code of API response type: type: string description: Type of API response which can be success or error message: type: string description: Message of API response securitySchemes: bearerAuth: type: http scheme: bearer ````