Skip to content

Field Schema

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

Fields

Field Name Required Description
ad_id - Meta ad ID (when supplied, overwrites existing ad)
ad_name ✓ Internal identifier for tracking
ad_headline ✓ Main headline text displayed in ad
ad_description - Additional description text
ad_body ✓ Primary text/body copy
ad_link_url ✓ Destination URL when ad is clicked
ad_cta_label ✓ Button label
ad_media_type ✓ Type of creative
ad_asset_url ✓ Main image/video file(s)
ad_asset_mid_url - Square/portrait format (4:5 ratio)
ad_asset_vertical_url - Vertical format (9:16 ratio)
ad_asset_filename - Filename for main asset (API only)
ad_asset_mid_filename - Filename for mid asset (API only)
ad_asset_vertical_filename - Filename for vertical asset (API only)
destination_ad_account_id ✓ Meta ad account ID
destination_adset_id ✓ Target ad set 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) Partner's Facebook Page ID for branded content

System Fields

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

Field Name Description
build_id Unique build identifier
build_status Current build state: building, qa, published, error
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

Validation:

  • Must be numeric
  • Must be a valid ad ID in the specified ad account
  • The ad must exist and be accessible to the authenticated user

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
  • Max 255 characters
  • Any text characters allowed

ad_headline

Type: Text
Required: Yes

Description: Main headline text displayed prominently in the ad.

Validation:

  • Must not be empty
  • Max 255 characters
  • Plain text only
  • May be truncated on some placements if too long

ad_description

Type: Text
Required: No

Description: Additional description text for the ad. This field provides extra context or details beyond the main body text.

Validation:

  • Plain text only
  • No character limit
  • Optional field - can be left empty

Notes:

  • Not all Meta ad placements display the description field
  • Most commonly shown in link preview formats
  • Consider this supplementary to your main ad_body text

ad_body

Type: Text
Required: Yes

Description: Primary text/body copy for the ad.

Validation:

  • Must not be empty
  • Plain text only
  • Unlimited length
  • Longer text may be truncated with "... See more" on some placements

Type: URL
Required: Yes

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

Validation:

  • Must start with http:// or https://
  • Must be publicly accessible (no localhost or private IPs)
  • Must return 200 status code
  • Must meet Meta's advertising policies

ad_cta_label

Type: Enum (Select)
Required: Yes

Description: Call-to-action button text displayed on the ad.

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

Notes:

ad_media_type

Type: Enum (Select)
Required: Yes

Description: Type of ad creative.

Allowed Values:

Value Description Asset Requirements
static Single image ad 1 image file
carousel Multi-image swipeable ad 2-10 image files
video Video ad 1 video file + optional thumbnail

When ad_media_type is carousel, the assets in ad_asset_url will be used to create the carousel, and their type will be automatically determined.

ad_asset_url

Type: File URL or Array of URLs
Required: Yes

Description: Primary creative file(s). Single file for static/video ads, multiple files for carousel ads. Refer to Meta's specifications for Image Ads and Video Ads.

ad_asset_mid_url

Type: File URL or Array of URLs
Required: No

Description: Portrait/mid format asset(s) optimized for Feed placements. Refer to Meta's specifications for Image Ads and Video Ads.

ad_asset_vertical_url

Type: File URL or Array of URLs
Required: No

Description: Vertical format asset(s) optimized for Stories and Reels placements. Refer to Meta's specifications for Image Ads and Video Ads.

ad_asset_filename

Type: Text
Required: No

Description: Optional filename for the main asset, which will determine how it appears in Ads Manager.

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

ad_asset_mid_filename

Type: Text
Required: No

Description: Filename for the mid (4:5) asset, which will determine how it appears in Ads Manager.

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

ad_asset_vertical_filename

Type: Text
Required: No

Description: Filename for the vertical (9:16) asset, which will determine how it appears in Ads Manager.

Notes: Not used in Notion/Airtable (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 numeric
  • 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: Yes

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

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

Validation:

  • Must be numeric
  • Must exist in the specified ad account
  • Must be active (not deleted or archived)
  • Cannot use ad sets with "Dynamic Creative" enabled

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

partner_facebook_page_id

Type: String (Numeric)
Required: No

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

Validation:

  • Must be numeric
  • Optional - Pablo automatically resolves this from the partner's Instagram account

Notes:

  • Advanced Use Only: You typically do NOT need to provide this field.
  • Pablo uses the Meta API to look up the partner's Page ID based on the provided partner_instagram_username.
  • Only use this if the automatic resolution fails or you need to force a specific Page ID.
  • 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