---
title: "Create a lead form"
method: POST
path: "/v1/ads/lead-forms"
tags: ["Lead Gen"]
---

# Create a lead form

`POST /v1/ads/lead-forms`

Creates a Lead Gen form. The form content goes inside `platformSpecificData` for both platforms (the shape is selected by the accountId's platform). Meta: created on the connected Facebook Page (POST /{page-id}/leadgen_forms); the old top-level Meta fields (questions, thankYou*, contextCard, …) are DEPRECATED but still accepted while platformSpecificData is absent — mixing both shapes is a 400. LinkedIn: created on the ad account's Company Page. NOT idempotent — a retry creates a second form. Meta prefilled question types (EMAIL, PHONE, FULL_NAME, …) must omit label/key; CUSTOM questions require both. LinkedIn exposes only free-text and multiple-choice questions via API (prefilled-from-profile fields are Campaign Manager UI-only). Requires the Ads add-on.

## Request body

- object
  - `accountId` string, required
  - `name` string, required
  - `questions` object[] — Deprecated (Meta legacy shape): use platformSpecificData.questions.
    - `type` string, required — EMAIL, PHONE, FULL_NAME, FIRST_NAME, LAST_NAME, CUSTOM, …
    - `key` string — CUSTOM questions only.
    - `label` string — CUSTOM questions only.
    - `options` object[]
      - `key` string
      - `value` string
    - `inline_context` string
  - `privacyPolicyUrl` string, uri, required
  - `privacyPolicyLinkText` string — Deprecated: use platformSpecificData.privacyPolicyLinkText.
  - `followUpActionUrl` string, uri — Deprecated: use platformSpecificData.followUpActionUrl.
  - `locale` string — Deprecated: use platformSpecificData.locale.
  - `thankYouTitle` string — Deprecated: use platformSpecificData.thankYouTitle.
  - `thankYouBody` string — Deprecated: use platformSpecificData.thankYouBody.
  - `thankYouButtonText` string — Deprecated: use platformSpecificData.thankYouButtonText.
  - `thankYouButtonType` string — Deprecated: use platformSpecificData.thankYouButtonType.
  - `thankYouWebsiteUrl` string, uri — Deprecated: use platformSpecificData.thankYouWebsiteUrl.
  - `isOptimizedForQuality` boolean — Deprecated: use platformSpecificData.isOptimizedForQuality.
  - `platformSpecificData` union — Form content; the shape is selected by the accountId's platform. Unknown fields are a 400 (strict-parsed).
    - object
      - `questions` object[], required
        - `type` string, required — EMAIL, PHONE, FULL_NAME, FIRST_NAME, LAST_NAME, CUSTOM, …
        - `key` string — CUSTOM questions only.
        - `label` string — CUSTOM questions only.
        - `options` object[]
          - `key` string
          - `value` string
        - `inline_context` string
      - `privacyPolicyLinkText` string
      - `followUpActionUrl` string, uri
      - `locale` string
      - `thankYouTitle` string
      - `thankYouBody` string
      - `thankYouButtonText` string
      - `thankYouButtonType` string
      - `thankYouWebsiteUrl` string, uri
      - `thankYouEnableMessenger` boolean — Adds a 'Continue in Messenger' option to the thank-you page (Meta thank_you_page.enable_messenger), so the lead can carry on chatting with the Page. Set thankYouButtonType to MESSAGE_BUSINESS or P2B_MESSENGER to make the chat the primary button.
      - `isOptimizedForQuality` boolean — Set true for a higher-intent form (adds a review step before submit).
      - `isPhoneSmsVerifyEnabled` boolean — Requires the lead to verify their phone number over SMS before the form submits (Meta is_phone_sms_verify_enabled). Only meaningful on a form with a PHONE question. Meta can restrict this parameter to apps holding a capability: when it does, the create fails with a 422 naming platformSpecificData.isPhoneSmsVerifyEnabled, and the toggle then has to be set in Meta's form builder.
      - `blockDisplayForNonTargetedViewer` boolean
      - `questionPageCustomHeadline` string
      - `contextCard` object
        - `title` string
        - `content` string[]
        - `style` 'LIST_STYLE' | 'PARAGRAPH_STYLE'
        - `buttonText` string
        - `coverPhoto` string
    - object
      - `adAccountId` string, required — LinkedIn ad account id (resolves the owning organization).
      - `headline` string, required
      - `description` string, required
      - `state` 'DRAFT' | 'PUBLISHED' — Defaults to DRAFT.
      - `locale` object
        - `country` string
        - `language` string
      - `consents` object[]
        - `description` string, required
        - `required` boolean — Whether the viewer must tick this consent to submit. Defaults to false.
      - `questions` union[], required
        - union
          - object
            - `kind` 'text', required
            - `name` string, required
            - `question` string, required
            - `required` boolean
            - `responseEditable` boolean
            - `maxResponseLength` integer — Defaults to 300 on LinkedIn's side.
          - object
            - `kind` 'multipleChoice', required
            - `name` string, required
            - `question` string, required
            - `required` boolean
            - `responseEditable` boolean
            - `choices` object[], required
              - …

## Response `200`

Created form.

- object
  - `status` string
  - `form` object
    - `id` string
    - `name` string

## Other responses

- `400` — Invalid request
- `401` — Unauthorized
- `403` — Ads add-on required.
- `422` — Meta rejected the lead form. Code 3 is Meta's generic app-capability error and does not name a field; when the request set isPhoneSmsVerifyEnabled, the response names that field as the one to drop first.

## Changes

- **2026-08-26** `b5344d376e5e` — 2 info
  - added the new optional request property `platformSpecificData/oneOf[subschema #1: MetaLeadFormPlatformData]/isPhoneSmsVerifyEnabled`
  - added the new optional request property `platformSpecificData/oneOf[subschema #1: MetaLeadFormPlatformData]/thankYouEnableMessenger`
- **2026-08-07** `51932b099b2f` — 2 warning
  - removed the request property `platformSpecificData/oneOf[subschema #1: MetaLeadFormPlatformData]/allowOrganicLeadGen`
  - removed the request property `platformSpecificData/oneOf[subschema #1: MetaLeadFormPlatformData]/formType`

[Change history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/ads/lead-forms/post.md)

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) · [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/zernio/zernio-api/revisions/dd66917efd2e/schema)