Retrieve Leads - Markifact

Retrieves TikTok Instant Form lead submissions and answers for CRM workflows. Requires ad account admin access (Business Center admin for migrated leads). Handles export jobs and regional storage; supports a UTC date filter and row limit. TikTok API does not allow creating forms, ask user to do via ads manager UI.


App	TikTok Ads
Operation ID	`tiktok_ads_retrieve_leads`
Type	Action
Connection	`tiktok_ads` (required)
Credits per run	1
Agent / MCP tool	Yes

Inputs

Field	Type	Required	Default	Description
`account`	DynamicAccount	Yes	-	TikTok advertiser account that owns the Instant Form.
`page_id`	string or SelectItem	Yes	-	Instant Form page_id from tiktok_ads_list_pages with page_type=LEAD_GEN.
`region`	enum (`ALL`, `US`, `EU`, `OTHER`)	No	`ALL`	Lead storage region: ALL checks every region; US is United States; EU is EEA, Switzerland and UK; OTHER is all remaining countries. Based on where leads were collected, not account currency. Defaults to ALL.
`library_id`	string	No	-	Form library ID if leads have been migrated to a Business Center. Replaces advertiser_id in the export request and requires Business Center admin access.
`date_range`	LeadDateRange	No	-	Optional inclusive UTC submission date filter. Applied after downloading TikTok’s export; does not reduce export size. Omit for all available dates.
`limit`	integer	No	`1000`	Maximum leads returned after the date filter, in TikTok export order. Default 1000; maximum 10000. Export download is still required. Exports above 50 MiB are rejected rather than silently truncated.

LeadDateRange

Field	Type	Required	Default	Description
`start`	string	No	-	Inclusive start date in UTC, YYYY-MM-DD.
`end`	string	No	-	Inclusive end date in UTC, YYYY-MM-DD.
`preset`	string	No	-	Date preset such as LAST_7_DAYS or LAST_30_DAYS. FIXED/CUSTOM uses start and end.

SelectItem

Field	Type	Required	Default	Description
`value`	string	Yes	-	The value of the selectable item.
`label`	string	Yes	-	The label of the selectable item, used for display purposes. If not provided, defaults to the value.

Output

Type: List[Dict] Lead rows from TikTok CSV exports, including lead id, created_time, ad/campaign/form identifiers and names, and question answers. All values remain strings to preserve IDs and phone numbers.