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

# Create a lead form

`POST /v1/messaging/ads/lead-forms`

## Request

- Base URL: `https://apihub.co.il`
- URL: `https://apihub.co.il/v1/messaging/ads/lead-forms`
- Auth: HTTP bearer

Creates a lead form on a Facebook Page or LinkedIn Company Page to collect contact details from ads.

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), where `accountId` may be the `metaads` ads connection (its Page comes from the Facebook account linked to the same profile), an Instagram account (the Page its ads run under: its own linked Page, else the Facebook or business-login Meta ads account on the same profile) or the Facebook account itself; 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.


**Billing:** Request; paid actions are priced in credits (see GET /v1/messaging/prices) · **Rate limit:** 60/min

## Headers

- `Idempotency-Key` string
- `X-Tag` string

## Request body

- object
  - `name` string, required
  - `locale` string: Deprecated: use platformSpecificData.locale.
  - `accountId` string, required
  - `questions` object[]: Deprecated (Meta legacy shape): use platformSpecificData.questions.
    - `key` string: CUSTOM questions only.
    - `type` string, required: EMAIL, PHONE, FULL_NAME, FIRST_NAME, LAST_NAME, CUSTOM, …
    - `label` string: CUSTOM questions only.
    - `options` object[]
      - `key` string
      - `value` string
    - `inline_context` string
  - `thankYouBody` string: Deprecated: use platformSpecificData.thankYouBody.
  - `thankYouTitle` string: Deprecated: use platformSpecificData.thankYouTitle.
  - `privacyPolicyUrl` string, uri, required
  - `followUpActionUrl` string, uri: Deprecated: use platformSpecificData.followUpActionUrl.
  - `thankYouButtonText` string: Deprecated: use platformSpecificData.thankYouButtonText.
  - `thankYouButtonType` string: Deprecated: use platformSpecificData.thankYouButtonType.
  - `thankYouWebsiteUrl` string, uri: Deprecated: use platformSpecificData.thankYouWebsiteUrl.
  - `platformSpecificData` union: Form content; the shape is selected by the accountId's platform. Unknown fields are a 400 (strict-parsed).
    - object
      - `locale` string
      - `questions` object[], required
        - `key` string: CUSTOM questions only.
        - `type` string, required: EMAIL, PHONE, FULL_NAME, FIRST_NAME, LAST_NAME, CUSTOM, …
        - `label` string: CUSTOM questions only.
        - `options` object[]
          - `key` string
          - `value` string
        - `inline_context` string
      - `contextCard` object
        - `style` 'LIST_STYLE' | 'PARAGRAPH_STYLE'
        - `title` string
        - `content` string[]
        - `buttonText` string
        - `coverPhoto` string, uri: Direct public JPEG or PNG image URL, up to 5 MB. Uploaded as an unpublished Page photo and attached to the form. Redirects, Ad Image hashes and IDs are not supported.
      - `thankYouBody` string
      - `thankYouTitle` string
      - `followUpActionUrl` string, uri
      - `thankYouButtonText` string
      - `thankYouButtonType` string
      - `thankYouWebsiteUrl` string, uri
      - `isOptimizedForQuality` boolean: Set true for a higher-intent form (adds a review step before submit).
      - `privacyPolicyLinkText` string
      - `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.
      - `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.
      - `questionPageCustomHeadline` string
      - `blockDisplayForNonTargetedViewer` boolean
    - object
      - `state` 'DRAFT' | 'PUBLISHED': Defaults to DRAFT.
      - `locale` object
        - `country` string
        - `language` string
      - `consents` object[]
        - `required` boolean: Whether the viewer must tick this consent to submit. Defaults to false.
        - `description` string, required
      - `headline` string, required
      - `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
            - `choices` object[], required
              - …
            - `question` string, required
            - `required` boolean
            - `responseEditable` boolean
      - `adAccountId` string, required: LinkedIn ad account id (resolves the owning organization).
      - `description` string, required
  - `isOptimizedForQuality` boolean: Deprecated: use platformSpecificData.isOptimizedForQuality.
  - `privacyPolicyLinkText` string: Deprecated: use platformSpecificData.privacyPolicyLinkText.

## Response `200`

Completed

- object
  - `id` string: Execution id — stable across internal retries; use it with GET /v1/executions/{id}
  - `status` 'pending' | 'processing' | 'completed' | 'partial' | 'failed' | 'cancelled' | 'timeout'
  - `operation` string
  - `tag` string, nullable: Your X-Tag, if sent
  - `created_at` string, date-time
  - `completed_at` string, date-time, nullable
  - `output` object: Operation result (see each operation). While a Studio render is processing: `stage` (queued · transcribing · downloading · preparing · cleaning_voice · mixing_audio · rendering · finishing), `phase` (the engine's: download · prepare · voice · audio · encode · qa · upload, or null), `progress` (a percent, 0–100) and `progress_fraction` (0–1), `eta_seconds` (seconds left, never below 0) and `estimate_seconds`
    - `form` object
      - `id` string
      - `name` string
    - `status` string
  - `error` string, nullable
  - `usage` object
    - `credits_charged` number, nullable
    - `credits_reserved` number
    - `estimated_credits` number
    - `cost_source` 'provider_reported' | 'calculated' | 'estimated' | 'null', nullable
    - `provider_usage` object, nullable: Normalised consumption, e.g. { VIDEO_SECOND: 22.4 }
  - `balance` object
    - `available` number
    - `reserved` number

## Other responses

- `400`: Invalid input
- `402`: Insufficient credits / project budget
- `404`: Resource not found (or not yours)
- `429`: Rate limited
- `503`: Service temporarily paused

---

[API](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai.md) · [All operations](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/llms.txt) · [OpenAPI document](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/revisions/a8caa42835ce?raw)