What this is
The Contact Ad Clicks API returns contact-associated Propensity Display Network click activity for a selected date range. Use it to bring eligible engagement records into your reporting or follow-up workflow.
Each row represents a stored engagement record, not necessarily one click or one unique person. A record can represent multiple clicks. The response does not include a click-count field, clicked URLs, or creative names. Do not calculate total clicks by counting rows.
Where to find it
- Open your workspace menu and go to Workspace Settings → Connections.
- Open the API access link and select Contact Ad Clicks.
- Use the endpoint and workspace API key shown for the workspace you want to query. Keep the key private.
Build a request
Send a GET request to /contact_ad_clicks on the API base URL provided in your workspace.
GET {API_BASE_URL}/contact_ad_clicks?workspace_api_key={WORKSPACE_API_KEY}&start_date=2026-10-01&end_date=2026-10-07&limit=100| Parameter | How to use it |
|---|---|
| workspace_api_key | Required. The API key for the workspace whose data you need. |
| start_date / end_date | Required dates in YYYY-MM-DD format. Both dates are included; each request can cover 1–31 calendar days. |
| campaign_id / play_id | Optional native Propensity IDs. Use these to narrow the request to a campaign or play. |
| limit | Optional page size from 1 to 500. The default is 100. A returned page can contain fewer rows. |
| cursor | Use the returned next_cursor value to request the next page. |
Read the response
The data array contains the returned activity records. Fields include engagement ID and type, date, campaign and play IDs and names, contact ID and available contact details, and account identity, name, and website.
The date is the analytics reporting date. Missing profile or account details are not an instruction to guess a value. Source rows without one eligible contact match, or associated with an opted-out contact, are excluded. meta.excluded_source_rows reports exclusions for the page.
Retrieve every page
- Process the returned
dataarray. - If
has_moreis true, copynext_cursorinto the next request while keeping the same workspace, dates, and campaign/play filters. - Continue until
has_moreis false. A short or empty data array can still have a continuation cursor because some source rows are excluded.
Do not build or edit cursor values. Pagination is not a frozen snapshot: source data can change while you are reading it. Keep the engagement ID when storing records so you can reconcile repeated retrievals.
Troubleshooting
- Invalid key or unauthorized: confirm that the API key belongs to the intended workspace.
- Invalid date range: use valid dates in order and split longer periods into windows of at most 31 days.
- Invalid cursor or cursor/query mismatch: restart from the first page with the intended filters.
- source_changed: restart that date range from the first page and reconcile records already retrieved.
- query_too_large: shorten the date range or add a campaign/play filter.
- Unavailable response: treat the request as failed, not as confirmation of zero activity. Retain the error and request details for Support.