Skip to content

Field Schema

Complete reference for all fields used in Pablo ad creation across Notion and API integrations.

Notion vs API field names. A few fields have shorter names on the Notion side than in the API. In Notion use ad_link, ad_asset, ad_asset_mid, ad_asset_vertical; in the API use ad_link_url, ad_asset_url, ad_asset_mid_url, ad_asset_vertical_url. This reference uses the API names; the Field Mapping guide lists the Notion-side names in full.

Fields

Field Name Required Description
ad_id - Meta ad ID (when supplied, overwrites existing ad)
ad_name ✓ Internal identifier for tracking
ad_headline ✓ Headline text — a string or an array of options
ad_body ✓ Primary text/body copy — a string or an array of options
ad_description - Additional description text — a string or an array of options
ad_headline_2 … _5 - Additional headline options (Notion-friendly alternative to arrays)
ad_body_2 … _5 - Additional body options
ad_description_2 … _5 - Additional description options
ad_link_url ✓ Destination URL when ad is clicked (Notion: ad_link)
ad_cta_label ✓ Button label
ad_media_type ✓ Type of creative
ad_asset_url * Main (square) image/video file(s) (Notion: ad_asset)
ad_asset_mid_url * Mid format (4:5 ratio) (Notion: ad_asset_mid)
ad_asset_vertical_url * Vertical format (9:16 ratio) (Notion: ad_asset_vertical)
ad_asset_urls, ad_asset_mid_urls, ad_asset_vertical_urls * Plural array forms (API, mainly for carousels)
ad_asset_filename (+ _mid_, _vertical_, and plural forms) - Filenames shown in Ads Manager (API only)
destination_ad_account_id ✓ Meta ad account ID
destination_adset_id * Target ad set ID (required unless using destination_adset_name)
destination_adset_name - Name for adset to find or create (use with destination_template_adset_id)
destination_template_adset_id - Template adset ID to clone when creating a new adset (alias: template_adset_id)
destination_template_ad_id ✓ Template ad for settings
ad_initial_status - Initial ad status (ACTIVE or PAUSED, default: PAUSED)
lead_form_id - Meta lead form ID (if using lead ads)
partner_instagram_username - Partner/creator Instagram username for branded content
partner_facebook_page_id - (Advanced, API only) Partner's Facebook Page ID for branded content

* Asset rule: no single asset field is required on its own — at least one asset must be present in any slot (main, mid, or vertical; singular or plural). A vertical-only ad is valid.

System Fields

Pablo automatically populates these fields after ad creation (read-only):

Field Name Description
build_id Unique build identifier
ad_import_status Current build state: building, qa, or error (successful builds land in qa)
error_message Error details if build fails
ad_post_id Facebook post ID for the ad
ad_preview_link Preview link to view the created ad
partner_instagram_id Resolved Instagram user ID (when partner_instagram_username is provided)
partner_instagram_metadata Cached partner info: {id, username, name, profile_picture_url}

Field Details

ad_id

Type: String (Numeric) Required: No

Description: Meta ad ID for updating an existing ad. When supplied, Pablo will overwrite the specified ad instead of creating a new one.

Format: Numeric string (e.g., "120234452710130091")

Usage:

  • Leave empty to create a new ad
  • Provide ad ID to update/overwrite an existing ad

Notes:

  • When updating an ad, all creative content will be replaced with new values
  • Useful for refreshing ad creative without creating duplicate ads
  • Pablo populates this field automatically after creating a new ad

ad_name

Type: Text Required: Yes

Description: The name of the ad in Facebook ads manager.

Validation:

  • Must not be empty

ad_headline, ad_body, ad_description — and multiple text options

Type: Text, or an array of texts Required: headline and body yes (at least one option each); description optional

Description: The ad's text. Each of the three accepts either a single string or an array of options. When more than one option is supplied for any of them, Pablo builds the ad as a standard ad with Meta's multiple text options (optimization_type: DEGREES_OF_FREEDOM) — Meta then picks the best-performing combination per impression. This is not Dynamic Creative; the ad coexists with normal ads in a normal adset.

Two ways to supply options:

  1. Array form (API): "ad_headline": ["50% Off", "Limited Time", "Don't Miss Out"]
  2. Numbered fields (Notion/Airtable-friendly): ad_headline_2 … ad_headline_5, ad_body_2 … ad_body_5, ad_description_2 … ad_description_5

Meta supports up to 5 options per text slot — stay within that.

Important trade-off: for image and video ads, supplying more than one text option disables placement-specific asset customization — one asset is chosen (main → mid → vertical fallback) and used everywhere. Use multiple text options or S/M/V placement assets, not both. See Placement Assets.

Notes:

  • Longer body text may be truncated with "... See more" on some placements
  • Not all placements display the description field — it's supplementary to ad_body

Type: URL Required: Yes Notion name: ad_link

Description: Destination URL where users are directed when they click the ad.

Validation:

  • Must be a valid http:// or https:// URL
  • Must meet Meta's advertising policies (checked by Meta, not by Pablo)

ad_cta_label

Type: Text (Meta CTA value) Required: Yes

Description: Call-to-action button text displayed on the ad. Pablo passes the value straight through to Meta — it is not validated up front, so a typo will surface as a Meta error during the build rather than an immediate validation error. Use one of Meta's CTA values:

Common Values:

Value Display Text
SHOP_NOW Shop Now
LEARN_MORE Learn More
SIGN_UP Sign Up
DOWNLOAD Download
GET_QUOTE Get Quote
CONTACT_US Contact Us
APPLY_NOW Apply Now
BOOK_TRAVEL Book Travel
WATCH_VIDEO Watch Video

Notes:

ad_media_type

Type: Enum (Select) Required: Yes

Description: Type of ad creative.

Allowed Values:

Value Description Asset Requirements
static Single image ad (image accepted as a synonym) 1+ image file
video Video ad 1 video file (thumbnail is generated automatically from the video)
carousel Multi-card swipeable ad — cards can be images, videos, or a mix 2+ files

When ad_media_type is carousel, each card's type (image vs video) is detected automatically from the files supplied.

Assets: ad_asset_url, ad_asset_mid_url, ad_asset_vertical_url (+ plural forms)

Type: File URL, or array of URLs (plural fields) Required: At least one asset in any slot Notion names: ad_asset, ad_asset_mid, ad_asset_vertical (files properties)

Description:

  • Main (ad_asset_url): square (1:1) asset — the default for most placements
  • Mid (ad_asset_mid_url): 4:5 asset — preferred in Feed placements when present
  • Vertical (ad_asset_vertical_url): 9:16 asset — Stories, Reels

Refer to Meta's specifications for Image Ads and Video Ads. For which asset serves which placement, see Placement Assets.

Carousel rules (validated):

  • At least 2 main cards (ad_asset_urls or repeated files in ad_asset)
  • Mid (4:5) assets are not supported alongside main assets on carousels — supplying both is a validation error. (A mid-only carousel is accepted: the mid assets are treated as the main cards.)
  • If vertical cards are supplied, there must be at least 2, and the vertical count must equal the main count
  • Filename arrays, when supplied, must match their URL arrays in length
  • More than 10 cards: Meta's cap is 10 — extra cards are dropped with a warning rather than rejected

API plural forms: ad_asset_urls, ad_asset_mid_urls, ad_asset_vertical_urls (and matching *_filenames) take arrays explicitly. The singular fields also accept arrays for carousels — both spellings work.

ad_asset_filename (+ _mid_, _vertical_, plural forms)

Type: Text or array of texts Required: No

Description: Optional filename(s) for assets, which determine how they appear in Ads Manager.

Notes: Not used in Notion (filenames auto-detected from attachments)

destination_ad_account_id

Type: String (Numeric) Required: Yes

Description: Meta ad account ID where the ad will be created.

Format: Numeric string (e.g., "123456789")

Validation:

  • Must be an ad account accessible to the authenticated user
  • Account must be active (not deleted or disabled)

destination_adset_id

Type: String (Numeric) Required: Required unless using destination_adset_name + destination_template_adset_id

Description: Target ad set ID within the ad account where the ad will be placed.

Format: Numeric string (e.g., "987654321")

Validation:

  • Must exist in the specified ad account and be active (not deleted or archived)
  • If provided alongside destination_adset_name, the ID takes precedence — but note that whenever destination_adset_name is set, destination_template_adset_id must be set too, even if the ID wins

destination_adset_name

Type: String Required: No (but requires destination_template_adset_id when used)

Description: Instead of providing an adset ID directly, provide a name and the system will find an existing adset with that name or create a new one. Useful for batch workflows where multiple ads should go into the same adset.

How it works:

  1. Searches for an existing adset with this exact name in the ad account (case- and whitespace-sensitive)
  2. If found, the ad is built into the existing adset
  3. If not found, a new adset is created by cloning properties from the template adset (targeting, budget, optimization goal, etc.)

Example: "Testing Batch 2026-W08"

See the full guide: for examples, use cases, and best practices, see the Dynamic Adset Creation guide.

destination_template_adset_id

Type: String (Numeric) Required: Required when destination_adset_name is provided Alias: template_adset_id is accepted as a backward-compatible spelling

Description: The adset to use as a template when creating a new adset. Properties like campaign, targeting, budget, optimization goal, and billing event are copied from this adset.

Format: Numeric string (e.g., "120233775366710091")

See the Dynamic Adset Creation guide for details on which properties are copied.

destination_template_ad_id

Type: String (Numeric) Required: Yes

Description: Existing ad ID to copy settings from (page connections, tracking parameters, creative enhancements).

Format: Numeric string (e.g., "555666777")

Inherited Settings:

  • Connected Facebook Page
  • Connected Instagram account
  • Connected Threads profile
  • Tracking parameters (UTM tags, pixels)
  • Creative enhancement settings (degrees_of_freedom_spec)

partner_instagram_username

Type: Text Required: No

Description: Instagram username of a partner/creator for branded content ads. Pablo will automatically look up their Instagram Business Account ID and configure the ad as a branded content partnership.

Format: Username with or without @ (e.g., "@creator" or "creator")

Notes:

  • Used for influencer/creator partnership ads
  • The partner must have an Instagram Business or Creator account
  • The ad will display "Paid partnership" disclosure
  • Pablo auto-populates partner_instagram_id and partner_instagram_metadata
  • See the Partnership Ads guide for the full flow and requirements

partner_facebook_page_id

Type: String (Numeric) Required: No Availability: API only — the Notion integration does not read this field

Description: The Facebook Page ID of the partner/creator for branded content ads.

Notes:

  • Advanced use only: you typically do NOT need to provide this field.
  • Pablo attempts to resolve the partner's Page ID automatically from the sponsor's approved-partners list. If that resolution fails, the ad still builds using the advertiser's own page identity — supplying this field explicitly is the way to force the partner's page.
  • The partner must have an Instagram Business/Creator account linked to this Page.

ad_initial_status

Type: Enum (Select) Required: No Default: PAUSED

Description: The initial status of the ad when it's created in Meta Ads Manager.

Allowed Values:

Value Description
ACTIVE Ad goes live immediately after creation
PAUSED Ad is created but remains paused (default)

Notes:

  • If not specified, ads default to PAUSED status
  • You can change the status later in Meta Ads Manager
  • Setting to ACTIVE requires the ad set and campaign to also be active
  • Useful for testing ads before making them live

lead_form_id

Type: Text Required: No

Description: Meta lead form ID for lead generation ads.

Format: Numeric string (e.g., "123456789012345")

Validation:

  • Must be a valid lead form ID in your Meta account
  • Lead form must be active and approved
  • Only applicable when creating lead ads

Notes:

  • Used for lead generation campaigns
  • Leave empty for standard link ads
  • Lead form must be created in Meta Ads Manager first