> ## 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 List API > The Campaign Lead List API retrieves a comprehensive list of leads linked to a particular campaign. This enables easy access to lead data for analysis, reporting, or follow-up tasks, ensuring campaign data is organized and accessible. ## Overview The Lead List API returns a paginated list of leads associated with a specific offer campaign. Use it to pull lead records for reporting dashboards, data exports, CRM syncs, or campaign performance reviews. Results include lead details, status, source attribution, and timestamps. ## Endpoint ``` GET /api/lead/list/{org-id}/{cid} ``` | Segment | Description | | ---------- | ---------------------------------------- | | `{org-id}` | Your organization (advertiser) unique ID | | `{cid}` | The campaign unique ID | ## Authentication Include your API token in the `Authorization` header: ``` Authorization: Bearer ``` ## Request Parameters ### Path Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ---------------------- | | `org-id` | string | Yes | Organization unique ID | | `cid` | string | Yes | Campaign unique ID | ### Query Parameters | Parameter | Type | Required | Description | | ------------ | ------- | -------- | --------------------------------------------------------------- | | `page` | integer | No | Page number (default: `1`) | | `limit` | integer | No | Records per page (default: `10`, max: `100`) | | `sort` | string | No | Sort field (e.g. `createdAt`) | | `order` | string | No | Sort direction: `asc` or `desc` (default: `desc`) | | `search` | string | No | Filter by email, mobile, or name | | `from` | string | No | Start date filter (ISO 8601: `YYYY-MM-DD`) | | `to` | string | No | End date filter (ISO 8601: `YYYY-MM-DD`) | | `leadStatus` | string | No | Filter by status: `accepted`, `unsold`, `rejected`, `duplicate` | | `pid` | string | No | Filter by source unique ID | ## Example Request ```bash theme={null} curl -G "https://api.pingtree.com/api/lead/list/org_5f1a2b3c/cmp_9z8y7x6w" \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \ --data-urlencode "page=1" \ --data-urlencode "limit=25" \ --data-urlencode "from=2025-08-01" \ --data-urlencode "to=2025-08-31" \ --data-urlencode "leadStatus=accepted" ``` ## Example Response ```json theme={null} { "status": 200, "message": "Leads retrieved successfully", "data": { "leads": [ { "transaction_id": "txn_7f3a2b1c-4d56-78ef-9012-abcdef123456", "first_name": "Jane", "last_name": "Doe", "email": "jane.doe@example.com", "mobile": "5551234567", "state": "CA", "zip_code": "90001", "leadStatus": "accepted", "isDeDupe": false, "pid": "src_abc123", "cid": "cmp_9z8y7x6w", "sub1": "campaign-abc", "createdAt": "2025-08-14T10:32:00.000Z" } ], "totalRecord": 412, "page": 1, "limit": 25 } } ``` ### Error — Invalid Campaign ```json theme={null} { "status": 400, "message": "Campaign not found or access denied" } ``` ### Error — Unauthorized ```json theme={null} { "status": 401, "message": "Unauthorized" } ``` ## Status Codes | HTTP Code | Description | | --------- | ------------------------------------------------ | | 200 | Lead list returned successfully | | 400 | Invalid campaign ID, org ID, or query parameters | | 401 | Invalid or missing API token | | 500 | Internal server error | ## Tips * **Pagination:** Always use the `page` and `limit` parameters when working with large campaigns to avoid timeouts. Start at page 1 and increment until you reach all records (`totalRecord / limit` pages). * **Date filters:** Use `from` and `to` together to pull leads for a specific reporting window. Both accept `YYYY-MM-DD` format and filter on the lead's creation timestamp in UTC. * **Source filtering:** Use the `pid` parameter to pull leads from a single source within a campaign — useful when comparing source performance. * **Status filtering:** Combine `leadStatus=accepted` with date filters for accurate sold-lead counts without pulling rejected or duplicate records. ## OpenAPI ````yaml GET /api/lead/list/{org-id}/{cid} 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/list/{org-id}/{cid}: get: description: >- The Campaign Lead List API retrieves a comprehensive list of leads linked to a particular campaign. This enables easy access to lead data for analysis, reporting, or follow-up tasks, ensuring campaign data is organized and accessible. parameters: - name: org-id required: true in: path description: Your organization ID schema: type: string - name: cid required: true in: path description: Your campaign unique ID schema: type: string - name: page in: query description: Selected page number default 1 schema: type: string - name: limit in: query description: 'No of leads in the page, default: 10, min:10, max:100' schema: type: string - name: sortField in: query description: Sort the list of leads based on field default _id schema: type: string - name: sortOrder in: query description: >- Sort order of list based on sort field default: descending, valid values are desc , asc schema: type: string - name: date required: true in: query description: >- For date filter anyone of these combination is rquired ["dateRange","singleDayDate","startDate and endDate"] from below list schema: type: string - name: dateRange in: query description: Valid date range format YYYY-MM-DD - YYYY-MM-DD schema: type: string - name: startDate in: query description: Valid startDate format YYYY-MM-DD schema: type: string - name: endDate in: query description: Valid endDate format YYYY-MM-DD schema: type: string - name: singleDayDate in: query description: Valid singleDayDate format YYYY-MM-DD schema: type: string responses: '201': description: Lead list successfully received content: application/json: schema: 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 leadsList: type: object description: Lead Details Array totalRecord: type: string description: Total leads count '400': description: >- Unexpected error, Campaign not found or Organization not found or Please enter valid date range content: application/json: schema: $ref: '#/components/schemas/lead-response' '401': description: Access token is missing or invalid content: application/json: schema: $ref: '#/components/schemas/lead-response' '429': description: >- Too many requests for fetch leads for organization Please wait 60 seconds before trying again 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 ````