Manage instant form (create / duplicate / archive) (`adsap_manage_instant_form`)

Platform: Meta · Read or write: Write · Plan: All plans · Consumes a task: Yes · Preview supported: Yes

What it does

Creates, duplicates, archives or reactivates a Meta Instant Form, the lead form people fill in without leaving Facebook or Instagram. Meta never lets a form be edited or deleted once it exists, so the first call is always a preview that creates nothing. A form belongs to one Facebook Page and only works in ads that run for that Page.

When to use it

Use it when you want a lead ad and the Page has no suitable form yet.
dry_run defaults to true, so the first call is a preview. The assistant sets dry_run to false once you confirm.
To change a form, use action duplicate with a new form.name and only the sections to replace, then archive the old one. Meta has no edit.
Have your privacy policy link ready. Meta refuses a form without one, and the assistant should never invent it.
To see a Page’s forms first, use adsap_list_meta_assets with asset_type instant_forms. To read one form in full, use adsap_get_instant_form.
The new form_id goes into creative_spec.leadgen_form_id of adsap_create_ad, on an ad set whose conversion location is Instant Forms or Website and Instant Forms.

Worked example

You ask

“Create a lead form called Newsletter signup on my brand Page. Ask for full name and email, and which product they are interested in: Signs or Lamps. Privacy policy is https://example.com/privacy . Preview it first.”

The assistant calls `adsap_manage_instant_form`


{
  "action": "create",
  "ad_account_id": "act_1234567890",
  "page_id": "100000000000001",
  "form": {
    "name": "Newsletter signup",
    "questions": [
      { "type": "FULL_NAME" },
      { "type": "EMAIL" },
      {
        "type": "CUSTOM",
        "label": "Which product are you interested in?",
        "options": ["Signs", "Lamps"]
      }
    ],
    "privacy_policy": { "url": "https://example.com/privacy" },
    "thank_you": { "title": "Thanks, you are on the list.", "button_type": "NONE" }
  },
  "dry_run": true
}

Adsap returns

The field names are the ones Adsap returns. The values are examples.


{
  "ok": true,
  "dry_run": true,
  "operation": "create",
  "page": {
    "id": "100000000000001",
    "name": "Your Brand",
    "lead_terms_accepted": true
  },
  "would": {
    "method": "POST",
    "endpoint": "/100000000000001/leadgen_forms",
    "params": {
      "name": "Newsletter signup",
      "is_optimized_for_quality": false,
      "block_display_for_non_targeted_viewer": false,
      "questions": [
        { "type": "FULL_NAME", "key": "full_name" },
        { "type": "EMAIL", "key": "email" },
        {
          "type": "CUSTOM",
          "label": "Which product are you interested in?",
          "options": [
            { "value": "Signs", "key": "o1" },
            { "value": "Lamps", "key": "o2" }
          ],
          "key": "which_product_are_you_interested_in"
        }
      ],
      "privacy_policy": { "url": "https://example.com/privacy" },
      "thank_you_page": { "title": "Thanks, you are on the list.", "button_type": "NONE" }
    }
  },
  "warnings": []
}

How to read it

would is the exact request Adsap will send to Meta, and nothing exists yet. lead_terms_accepted confirms the Page has accepted Meta’s Lead Ads Terms; when it has not, the call stops with LEAD_TERMS_NOT_ACCEPTED and a link for a Page admin. Each question gets a key, the field name your leads arrive under.

The full response also has a human_readable_summary sentence, left out here. If the plan looks right, the assistant repeats the call with dry_run set to false. That response returns form.form_id.

Parameters

Descriptions are shortened from the tool schema. Your assistant sees the full text.

Name	Type	Required	Description
`action`	one of `create`, `duplicate`, `archive`, `reactivate`	Yes	create a new form; duplicate an existing one with changes (the only way to ‘edit’, since Meta never lets a form be modified)…
`ad_account_id`	string	Yes	Meta ad account (act_…) the Page is connected to. Used for access checks.
`page_id`	string	No	Numeric id of the Facebook Page that owns the form. A form belongs to ONE Page and only works in ads that run for that Page.
`form_id`	string	No	Required for duplicate, archive and reactivate.
`form`	object	No	create: the whole form (name, questions, privacy_policy and thank_you are required). duplicate: a NEW name plus only the sections to replace; a section you send replaces the whole section, everything else is copied as is.
`form.name`	string	No	Internal form name, never shown to people. Must be unique on the Page, archived forms included.
`form.locale`	string	No	Language of Meta’s own buttons and labels inside the form, e.g. EN_US, EN_GB, FR_FR, ES_ES, DE_DE, IT_IT, PT_BR. Omit for the Page default.
`form.form_type`	one of `more_volume`, `higher_intent`	No	more_volume (default) or higher_intent, which adds a review step where people confirm their answers before sending: fewer leads, usually better ones.
`form.block_organic`	boolean	No	true = only people targeted by the ad can send the form. Default false (a shared link to the ad also works).
`form.questions_headline`	string	No	Optional headline above the questions.
`form.intro`	object	No	Optional first screen that explains the offer before the questions.
`form.questions`	array of object	No	In the order people see them. At least one.
`form.privacy_policy`	object	No	REQUIRED by Meta on every form. Ask the user for the link; never invent one.
`form.custom_disclaimer`	object	No	Optional legal text with consent boxes, shown with the privacy policy.
`form.thank_you`	object	No	REQUIRED: the screen people see after sending the form.
`form.tracking_parameters`	object	No	Hidden name/value pairs sent with every lead (e.g. source=meta_leads). A name may not equal a question’s field key (email, full_name, or the slug of a custom question).
`dry_run`	boolean	No	Preview only: the request is validated and the resolved payload returned, nothing is created or changed.

Example prompts

“Create an Instant Form on my Page asking for name, email and phone, and preview it first.”
“Duplicate my Newsletter signup form as Newsletter signup v2, with a higher intent review step.”
“Archive the old Summer contest form.”

Notes

A problem with the form comes back as INVALID_INPUT with every issue listed at once. Meta allows at most 3 short answer questions per form; multiple choice questions are not capped. A tracking parameter cannot share its name with a question key. A real create, duplicate, archive or reactivate uses one task; previews use none.

Not available: conditional logic (answers that branch), appointment scheduling, store locator, national ID questions and gated file downloads.

adsap_get_instant_form: Read ONE Meta Instant Form in full: questions, intro, privacy policy and custom disclaimer, thank-you screen, tracking parameters, status…

Guide

Read AI Copilot usage for the workflow around this tool, and the Tool reference for every tool.

Manage instant form (create / duplicate / archive) (adsap_manage_instant_form)