---
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
      - `isOptimizedForQuality` boolean — Set true for a higher-intent form (adds a review step before submit).
      - `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 with error code 3. The Facebook Page normally needs a Page admin to accept the Lead Ads Terms of Service.

---

[API](https://skmtc.net/zernio/apis/zernio-api.md) · [All operations](https://skmtc.net/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zernio/zernio-api/versions/f81ca70ea6b9/schema)