Facebook IntegrationVersion: v3

Create page lead form

POST/ad-publishing/facebook/page/{pageId}/forms

Create a lead gen form. With isDraft: true the form is stored locally and returned as a draft; without it the form is published to Facebook and the Meta record is returned. The two responses share almost no fields. Publishing enforces at least one question and a complete thankYouPage (title, body, buttonText) where a draft save enforces neither. Pass draftFormId when publishing an existing draft to have it deleted afterwards — either the bare id or the draft_-prefixed form is accepted, and cleanup failures are logged rather than surfaced.

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your access token.

Scope:adPublishing.write

Auth methods:OAuthPrivate Integration

Token type:Sub-Account Token

Request

Headers

Versionstringrequired

API Version

Available optionsv3

Example:v3

Path Parameters

pageIdstringrequired

Facebook page identifier

Example:103456789012345

Body

application/json

typestringrequired

Lead form type

Available optionsMORE_VOLUMEHIGHER_INTENT

Example:MORE_VOLUME

namestringrequired

Lead form name

Example:Contact Form

locationIdstringrequired

Location identifier

Example:loc_abc123

greetingCardobject

Greeting card config

questionsobject[]required

List of questions displayed on the lead form. Required (non-empty) when isDraft is false or omitted; optional for drafts.

questionPageHeadlinestring

Question page headline

Example:Tell us about yourself

privacyPolicyLinkstringrequired

Example:https://example.com/privacy

privacyPolicyTextstring

Example:We respect your privacy

customDisclaimerobject

Custom disclaimer config

thankYouPageobjectrequired

Thank you page config. Required when isDraft is false or omitted; optional for drafts.

isDraftboolean

If the form is a draft, set to true

Example:true

draftFormIdstring

Draft form ID

Example:1234567890

localestring

Locale

Example:EN_US

Response

application/json

The stored draft when isDraft is set, otherwise the form as published to Facebook

oneOf

FacebookCreatedDraftLeadFormDTO
FacebookCreatedLeadFormDTO

idstringrequired

Draft id, unprefixed. The listing endpoint reports this same draft as draft_<id>.

Example:6a866661867e604d24f5a21c

isDraftbooleanrequired

Always true on this branch

Example:true

namestringrequired

Form name

Example:Untitled form 20 Aug 26, 07:57 AM

locationIdstringrequired

Owning location

Example:fRMewNQIxSyZ5R4nQyit

pageIdstringrequired

Page the draft will publish to

Example:196684453527082

typestring

Lead form objective

Available optionsMORE_VOLUMEHIGHER_INTENT

Example:MORE_VOLUME

localestringrequired

Form locale, upper-cased as stored

Example:EN_US

createdAtstringrequired

Creation time, ISO-8601

Example:2026-08-20T02:28:49.477Z

updatedAtstringrequired

Last modification time, ISO-8601. Equal to createdAt on a fresh draft.

Example:2026-08-20T02:28:49.477Z

greetingCardobject

Intro card

questionsobject[]

Questions as stored. Each carries a Mongo _id, and so does every entry in its options.

questionPageHeadlinestring

Headline above the questions

Example:We'll use your information to send you our weekly newsletters.

privacyPolicyLinkstring

Example:https://www.privacypolicy.com

privacyPolicyTextstring

Example:Link text

customDisclaimerobject

Custom disclaimer block

thankYouPageobject

Confirmation screen