Lead Generation API Reference

API Reference

This is the full technical reference. For an overview of Lead Gen Ads, form structure, and the create → attach → export workflow, see the Lead Generation Overview.

The Leads API requires the Campaign user permission. Lead exports are restricted to account administrators.

Lead form create and update requests accept JSON bodies. Set Content-Type to application/json.

Lead Forms

POST accounts/:account_id/lead_forms

Create a lead form associated with the current account. Resource URL https://ads-api.x.com/12/accounts/:account_id/lead_forms

string

required

The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.

string

required

Form name, 1–255 characters.

string

required

What the collected leads are used for, 1–1000 characters.

array

required

Non-empty array of fields the lead fills in. See fields entries. Keys must be unique within the form. At least one field must be required (optional is false or omitted).

object

required

object

Introduction card shown before the form fields. See introduction.

object

Final page shown after the form is submitted. See final_page.

Example Request POST https://ads-api.x.com/12/accounts/18ce54d4x5t/lead_forms

{
  "name": "Fall launch form",
  "purpose": "Collect newsletter signups",
  "introduction": {
    "headline": "Sign up",
    "description": "Get our newsletter"
  },
  "final_page": {
    "headline": "Thanks for signing up",
    "description": "We will be in touch soon",
    "cta_button": {
      "url": "https://example.com/welcome",
      "title": "Visit our site"
    }
  },
  "fields": [
    { "key": "EMAIL" },
    { "key": "FULL_NAME", "optional": true }
  ],
  "privacy_policy": {
    "url": "https://example.com/privacy",
    "company_name": "Example Inc"
  }
}

Example Response

Example response

{
  "data": {
    "id": "3f2b8c1a-8f4e-4a0b-9df2-0123456789ab",
    "name": "Fall launch form",
    "purpose": "Collect newsletter signups",
    "introduction": {
      "headline": "Sign up",
      "description": "Get our newsletter"
    },
    "final_page": {
      "headline": "Thanks for signing up",
      "description": "We will be in touch soon",
      "cta_button": {
        "url": "https://example.com/welcome",
        "title": "Visit our site"
      }
    },
    "fields": [
      { "key": "EMAIL", "optional": false },
      { "key": "FULL_NAME", "optional": true }
    ],
    "privacy_policy": {
      "url": "https://example.com/privacy",
      "company_name": "Example Inc"
    },
    "deleted": false,
    "created_at": "2026-08-14T18:22:01Z",
    "updated_at": "2026-08-14T18:22:01Z"
  }
}

Nested objects

introduction

Parameter	Required	Description
`headline`	Yes	1–190 characters, non-blank.
`description`	No	Up to 1000 characters.

final_page

Shown to the lead after a successful submission. The optional CTA button links the lead onward (for example, to the advertiser’s site).

Parameter	Required	Description
`headline`	Yes	1–190 characters, non-blank.
`description`	No	Up to 1000 characters.
`cta_button`	No	Call-to-action button. When present, both of its properties are required.
`cta_button.url`	Yes*	Must be an `https://` URL.
`cta_button.title`	Yes*	Button label, 1–100 characters, non-blank.

* Required only when cta_button itself is present.

fields entries

Parameter	Required	Description
`key`	Yes	The kind of information the field collects. See Field keys. Keys must be unique within the form.
`optional`	No	Defaults to `false`. At least one field must be required (`optional=false`), so the form cannot be submitted empty.

Field keys

Contact fields

Key	Description
`EMAIL`	Email address
`PHONE_NUMBER`	Phone number
`STREET_ADDRESS`	Street address
`CITY`	City
`STATE`	State or region
`COUNTRY`	Country
`ZIP_CODE`	Postal code

User information

Key	Description
`FULL_NAME`	Full name
`FIRST_NAME`	First name
`LAST_NAME`	Last name
`DATE_OF_BIRTH`	Date of birth
`COMPANY_NAME`	Company name
`JOB_TITLE`	Job title
`WORK_EMAIL`	Work email address
`WORK_PHONE_NUMBER`	Work phone number
`GENDER`	Gender
`HANDLE`	X handle

privacy_policy

Parameter	Required	Description
`url`	Yes	Must be an `https://` URL.
`company_name`	Yes	1–255 characters, non-blank.

PUT accounts/:account_id/lead_forms/:lead_form_id

Update a lead form associated with the current account. Takes the same parameters as create; every one of them is optional. Omitted parameters keep their current value. Object parameters (introduction, final_page, privacy_policy) and the fields array are replaced wholesale when provided — there is no partial update within a nested object, and no way to unset one once set. A provided fields array must not be empty, and a provided final_page is validated the same way as on create. Archived (deleted) lead forms are immutable and return a not-found error. Resource URL https://ads-api.x.com/12/accounts/:account_id/lead_forms/:lead_form_id

string

required

string

required

The UUID of the lead form to update.

string

Form name, 1–255 characters.

string

What the collected leads are used for, 1–1000 characters.

array

Replaces the form’s fields wholesale. Must not be empty. See fields entries.

object

Replaces the privacy policy wholesale. See privacy_policy.

object

Replaces the introduction wholesale. See introduction.

object

Replaces the final page wholesale. See final_page.

Example Request PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/lead_forms/3f2b8c1a-8f4e-4a0b-9df2-0123456789ab

{
  "name": "Fall launch form (updated)",
  "fields": [
    { "key": "EMAIL" },
    { "key": "PHONE_NUMBER", "optional": true }
  ]
}

GET accounts/:account_id/lead_forms

List the account’s lead forms, newest first. Resource URL https://ads-api.x.com/12/accounts/:account_id/lead_forms

string

required

int

default:"100"

Number of forms per page.
Min: 1, Max: 200

string

Opaque pagination cursor from a previous response. Pass next_cursor back as cursor to fetch the next page; it is null on the last page. See Pagination.

boolean

default:"false"

Pass true to include archived forms.

Example Request GET https://ads-api.x.com/12/accounts/18ce54d4x5t/lead_forms?count=2 Example Response

Example response

{
  "data": [
    {
      "id": "3f2b8c1a-8f4e-4a0b-9df2-0123456789ab",
      "name": "Fall launch form",
      "purpose": "Collect newsletter signups",
      "introduction": {
        "headline": "Sign up",
        "description": "Get our newsletter"
      },
      "final_page": {
        "headline": "Thanks for signing up",
        "description": "We will be in touch soon",
        "cta_button": {
          "url": "https://example.com/welcome",
          "title": "Visit our site"
        }
      },
      "fields": [
        { "key": "EMAIL", "optional": false },
        { "key": "FULL_NAME", "optional": true }
      ],
      "privacy_policy": {
        "url": "https://example.com/privacy",
        "company_name": "Example Inc"
      },
      "deleted": false,
      "created_at": "2026-08-14T18:22:01Z",
      "updated_at": "2026-08-14T18:22:01Z"
    },
    {
      "id": "7a1d3e92-2b5c-4c17-8e64-fedcba987654",
      "name": "Webinar registration",
      "purpose": "Collect webinar signups",
      "fields": [{ "key": "WORK_EMAIL", "optional": false }],
      "privacy_policy": {
        "url": "https://example.com/privacy",
        "company_name": "Example Inc"
      },
      "deleted": false,
      "created_at": "2026-08-01T12:04:11Z",
      "updated_at": "2026-08-01T12:04:11Z"
    }
  ],
  "next_cursor": "8x7dpl"
}

GET accounts/:account_id/lead_forms/:lead_form_id

Retrieve a single lead form associated with the current account. Resource URL https://ads-api.x.com/12/accounts/:account_id/lead_forms/:lead_form_id

string

required

string

required

The UUID of the lead form to retrieve.

boolean

default:"false"

Pass true to retrieve an archived form. Archived forms return not-found when this is false.

Example Request GET https://ads-api.x.com/12/accounts/18ce54d4x5t/lead_forms/3f2b8c1a-8f4e-4a0b-9df2-0123456789ab Example Response

Example response

{
  "data": {
    "id": "3f2b8c1a-8f4e-4a0b-9df2-0123456789ab",
    "name": "Fall launch form",
    "purpose": "Collect newsletter signups",
    "introduction": {
      "headline": "Sign up",
      "description": "Get our newsletter"
    },
    "final_page": {
      "headline": "Thanks for signing up",
      "description": "We will be in touch soon",
      "cta_button": {
        "url": "https://example.com/welcome",
        "title": "Visit our site"
      }
    },
    "fields": [
      { "key": "EMAIL", "optional": false },
      { "key": "FULL_NAME", "optional": true }
    ],
    "privacy_policy": {
      "url": "https://example.com/privacy",
      "company_name": "Example Inc"
    },
    "deleted": false,
    "created_at": "2026-08-14T18:22:01Z",
    "updated_at": "2026-08-14T18:22:01Z"
  }
}

DELETE accounts/:account_id/lead_forms/:lead_form_id

Soft-delete (archive) a lead form. Archived forms stop accepting submissions and can no longer be updated. Resource URL https://ads-api.x.com/12/accounts/:account_id/lead_forms/:lead_form_id

string

required

string

required

The UUID of the lead form to archive.

Example Request DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/lead_forms/3f2b8c1a-8f4e-4a0b-9df2-0123456789ab Example Response

Example response

{
  "data": {
    "id": "3f2b8c1a-8f4e-4a0b-9df2-0123456789ab",
    "name": "Fall launch form",
    "purpose": "Collect newsletter signups",
    "deleted": true,
    "created_at": "2026-08-14T18:22:01Z",
    "updated_at": "2026-09-15T16:10:44Z"
  }
}

Attach a lead form to a card

Use POST accounts/:account_id/cards to create a post card that opens a lead form. Set the destination type to LEAD_FORM and pass the form id. The LEAD_FORM destination can be used anywhere a destination is accepted, including DETAILS and BUTTON components and buttons in a BUTTON_GROUP component. Invalid lead form ids are rejected with one error per invalid id.

{
  "type": "LEAD_FORM",
  "id": "3f2b8c1a-8f4e-4a0b-9df2-0123456789ab"
}

Parameter	Required	Description
`type`	Yes	Must be `LEAD_FORM`.
`id`	Yes	Id of the lead form to open when the component is tapped. Must be a valid lead form id (UUID).

Example Request POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards

{
  "name": "Fall launch card",
  "components": [
    {
      "type": "MEDIA",
      "media_key": "3_1743570804436678656"
    },
    {
      "type": "DETAILS",
      "title": "Sign up",
      "destination": {
        "type": "LEAD_FORM",
        "id": "3f2b8c1a-8f4e-4a0b-9df2-0123456789ab"
      }
    }
  ]
}

See the Cards API reference for the full card create contract, including card_uri and attaching the card to a Post.

Export leads

Leads collected by a form are exported through the ad-export job lifecycle: create an export job, poll its status, download the result, and optionally cancel it. A leads export is an export create with entity_type set to leads.

Leads exports are restricted to account administrators, since exported leads contain personal information.

The remaining routes are shared by all export types and work the same way for leads exports.

POST accounts/:account_id/ad-export/api/v1/exports

Create a leads export job. The form must exist, belong to the account, and not be archived; otherwise the request fails with a 404. Resource URL https://ads-api.x.com/12/accounts/:account_id/ad-export/api/v1/exports

string

required

string

required

Must be leads.

string

required

Id of the lead form whose leads to export. The form must exist, belong to the account, and not be archived.

int

required

Start of the export window as a Unix timestamp in seconds. Inclusive.

int

required

End of the export window as a Unix timestamp in seconds. Exclusive: the window is [start_epoch, end_epoch), so leads submitted exactly at end_epoch are not included.

enum

Format of the exported file.

Possible values: json, csv, xlsx

Example Request POST https://ads-api.x.com/12/accounts/18ce54d4x5t/ad-export/api/v1/exports

{
  "entity_type": "leads",
  "lead_form_id": "3f2b8c1a-8f4e-4a0b-9df2-0123456789ab",
  "start_epoch": 1751328000,
  "end_epoch": 1753920000,
  "response_format": "json"
}

The create response includes an export job id. Use that id to poll status, download the file, or cancel the job.

GET accounts/:account_id/ad-export/api/v1/exports/:export_id

Return the job status. Once the job completes, the response includes a download_url. Resource URL https://ads-api.x.com/12/accounts/:account_id/ad-export/api/v1/exports/:export_id

string

required

The identifier for the leveraged account.

string

required

The identifier of the export job returned when the job was created.

GET accounts/:account_id/ad-export/api/v1/exports/:export_id/download

Download the exported file. Resource URL https://ads-api.x.com/12/accounts/:account_id/ad-export/api/v1/exports/:export_id/download

string

required

The identifier for the leveraged account.

string

required

The identifier of a completed export job.

DELETE accounts/:account_id/ad-export/api/v1/exports/:export_id

Cancel the export job. Resource URL https://ads-api.x.com/12/accounts/:account_id/ad-export/api/v1/exports/:export_id

string

required

The identifier for the leveraged account.

string

required

The identifier of the export job to cancel.

Overview

Fundamentals

Resources

Measurement

Lead Generation API Reference

API Reference

Lead Forms

POST accounts/:account_id/lead_forms

Nested objects

introduction

final_page

fields entries

Field keys

privacy_policy

PUT accounts/:account_id/lead_forms/:lead_form_id

GET accounts/:account_id/lead_forms

GET accounts/:account_id/lead_forms/:lead_form_id

DELETE accounts/:account_id/lead_forms/:lead_form_id

Attach a lead form to a card

Export leads

POST accounts/:account_id/ad-export/api/v1/exports

GET accounts/:account_id/ad-export/api/v1/exports/:export_id

GET accounts/:account_id/ad-export/api/v1/exports/:export_id/download

DELETE accounts/:account_id/ad-export/api/v1/exports/:export_id