> ## Documentation Index
> Fetch the complete documentation index at: https://docs.markifact.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve Leads

> Retrieves TikTok Instant Form lead submissions and answers for CRM workflows

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.