Offer Campaign APIs

Lead List API

GEThttps://api.pingtree.com/api/lead/list/{org-id}/{cid}

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 <your-api-token>

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

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

{
  "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

{
  "status": 400,
  "message": "Campaign not found or access denied"
}

Error — Unauthorized#

JSON

{
  "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.