clawdbot-workspace/FB_ADS_FIELD_REFERENCE.md

Facebook Ads CSV Bulk Upload - Complete Field Reference

📚 Table of Contents

• Campaign Level Fields
• Ad Set Level Fields
• Ad Level Fields
• Advanced Features
• Validation Rules
• Common Use Cases

---

Campaign Level Fields

Required Fields

Field	Description	Valid Values	Example
Campaign Name	Name of your campaign	Any string (max 250 chars)	"Q1 2026 Product Launch"
Campaign Objective	Campaign goal	OUTCOME_TRAFFIC, OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_ENGAGEMENT, OUTCOME_APP_PROMOTION, OUTCOME_AWARENESS	OUTCOME_TRAFFIC
Buying Type	Auction type	AUCTION, RESERVATION	AUCTION
Campaign Status	Initial campaign state	ACTIVE, PAUSED	ACTIVE

Optional Fields

Field	Description	Valid Values	Example
Campaign Budget Optimization	Enable CBO	TRUE, FALSE	FALSE
Campaign Budget	Total campaign budget (only if CBO=TRUE)	Positive number	1000
Campaign Bid Strategy	How to bid	LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP, TARGET_COST	LOWEST_COST_WITHOUT_CAP
Campaign Spend Limit	Max spend across campaign	Positive number	5000

---

Ad Set Level Fields

Required Fields

Field	Description	Valid Values	Example
Ad Set Name	Name of ad set	Any string	"Cold Traffic - Tech Enthusiasts 18-35"
Optimization Goal	What to optimize for	LINK_CLICKS, LANDING_PAGE_VIEWS, IMPRESSIONS, REACH, OFFSITE_CONVERSIONS, THRUPLAY, POST_ENGAGEMENT	LINK_CLICKS
Billing Event	What you pay for	IMPRESSIONS, LINK_CLICKS, THRUPLAY	LINK_CLICKS
Daily Budget OR Lifetime Budget	Budget amount	Positive number (min $1/day)	50.0
Ad Set Status	Initial ad set state	ACTIVE, PAUSED	ACTIVE

Targeting Fields

Field	Description	Valid Values	Example
Targeting Age Min	Minimum age	13-65	18
Targeting Age Max	Maximum age	13-65+	65+
Targeting Gender	Gender targeting	All, Male, Female	All
Targeting Locations	Geographic targeting	Country names, states, cities (comma-separated)	"United States,Canada"
Targeting Custom Audiences	Custom audience IDs	Comma-separated IDs	"123456789,987654321"
Targeting Excluded Custom Audiences	Audiences to exclude	Comma-separated IDs	"111222333"
Targeting Interests	Interest targeting	Interest names (comma-separated)	"Technology,AI,Software"
Targeting Behaviors	Behavior targeting	Behavior names	"Tech Early Adopters"
Targeting Languages	Language codes	ISO language codes	"en,es,fr"

Placement Fields

Field	Description	Valid Values	Example
Placements	Placement selection	Automatic, Manual	Automatic
Platform Positions	Specific platforms (if Manual)	Facebook, Instagram, Messenger, Audience Network	"Facebook,Instagram"

Scheduling Fields

Field	Description	Valid Values	Example
Start Date	When to start	YYYY-MM-DD	2026-02-15
End Date	When to end (optional)	YYYY-MM-DD or blank	2026-03-15

Conversion Tracking (For Sales/Leads objectives)

Field	Description	Valid Values	Example
Promoted Object Pixel ID	Meta Pixel ID	Numeric ID	123456789012345
Promoted Object Custom Event Type	Event to track	Purchase, Lead, CompleteRegistration, AddToCart, etc.	Purchase
Optimization Window	Conversion window	1_DAY, 7_DAYS	7_DAYS
Attribution Setting	Attribution window	7_DAY_CLICK_1_DAY_VIEW, 1_DAY_CLICK, etc.	7_DAY_CLICK_1_DAY_VIEW

---

Ad Level Fields

Required Fields

Field	Description	Valid Values	Example
Ad Name	Name of the ad	Any string	"Hero Ad - Tech Audience v1"
Ad Status	Initial ad state	ACTIVE, PAUSED	ACTIVE
Body	Primary text	Any string (125 chars recommended)	"Transform your workflow with AI"
Title	Headline	Any string (40 chars max)	"Try OpenClaw Free Today"
Link	Destination URL	Valid URL	https://example.com

Creative Fields

For Images:

Field	Description	Valid Values	Example
Image Hash	Use existing library image	Hash from library	abc123def456
Image File	Upload new image	Filename to upload	hero_image_1080x1080.jpg

For Videos:

Field	Description	Valid Values	Example
Video ID	Use existing library video	ID from library	123456789
Video File	Upload new video	Filename to upload	product_demo.mp4

Note: Use either Hash/ID for existing assets OR File for new uploads. Don't fill both.

Optional Fields

Field	Description	Valid Values	Example
Caption	Link description	Any string	"Limited Time Offer"
Call To Action	CTA button	LEARN_MORE, SHOP_NOW, SIGN_UP, DOWNLOAD, GET_QUOTE, CONTACT_US, BOOK_NOW, APPLY_NOW, NO_BUTTON	LEARN_MORE
Website URL	Can differ from Link	Valid URL	https://example.com/promo
Display Link	Vanity URL shown	String	example.com/special

UTM Tracking

Field	Description	Example
UTM Source	Traffic source	facebook
UTM Medium	Marketing medium	paid_social
UTM Campaign	Campaign identifier	q1_launch
UTM Term	Paid keywords (optional)	tech_audience
UTM Content	Ad variation identifier	hero_v1

---

Advanced Features

Dynamic Creative

Enable testing multiple variations of creative elements:

Field	Purpose
Dynamic Creative	Set to TRUE to enable
Additional Body 1-3	Up to 3 extra primary text variations
Additional Title 1-3	Up to 3 extra headline variations
Additional Image 1-2	Up to 2 extra image variations

Meta will automatically test combinations and optimize for best performers.

Carousel Ads

Create multi-card carousel ads:

Field Pattern	Example
Carousel Card [1-10] Title	"Feature 1: Speed"
Carousel Card [1-10] Body	"10x faster than competitors"
Carousel Card [1-10] Link	https://example.com/feature1
Carousel Card [1-10] Image	feature1.jpg

Supports up to 10 cards per ad.

Multi-Language (DLO)

Serve different languages automatically:

Field Pattern	Example
Language [1-5] Code	en, es, fr, de, etc.
Language [1-5] Body	Translated primary text
Language [1-5] Title	Translated headline
Language [1-5] Link	Language-specific landing page

Meta serves the right language based on user's Facebook language setting.

Partnership/Creator Ads

Use influencer content:

Field	Description	Example
Partnership Ad Code	Code from creator	ABC123XYZ789
Creator Account ID	Creator's Facebook/Instagram ID	1234567890

Existing Post IDs

Reuse posts to maintain social proof:

Field	Description	Example
Use Page Post	Set to TRUE	TRUE
Page Post ID	ID of existing post	123456789012345_67890

---

Validation Rules

Critical Constraints

1. Budget Minimums

   • Daily Budget: Minimum $1.00
   • Lifetime Budget: Minimum $1.00

2. Date Format

   • Must be: YYYY-MM-DD
   • Start Date cannot be in the past
   • End Date must be after Start Date

3. Age Targeting

   • Min Age: 13-65
   • Max Age: 13-65 or "65+"
   • Max must be >= Min

4. Status Values

   • Only: ACTIVE or PAUSED
   • Case-sensitive

5. Objective-Specific Requirements

   • OUTCOME_SALES / OUTCOME_LEADS: Must include Pixel ID and Custom Event Type
   • OUTCOME_TRAFFIC: Requires valid destination URL

6. File Uploads

   • Images: JPG, PNG (max 30MB, 1080x1080px recommended)
   • Videos: MP4, MOV (max 4GB, under 240 min)
   • File names cannot contain spaces or special characters (use underscores)

7. Creative Requirements

   • Must provide EITHER Image Hash/Video ID OR Image File/Video File
   • Cannot leave creative fields entirely blank
   • Primary text: 125 characters recommended (max 500)
   • Headline: 40 characters max
   • Link description: 30 characters max

---

Common Use Cases

1. Simple Link Click Campaign

Objective: Drive traffic to website
Required Fields: Campaign Name, Objective (TRAFFIC), Ad Set Name, Daily Budget, Ad Name, Body, Title, Link, Image File
Budget: $50/day minimum recommended

2. Conversion Campaign

Objective: Track purchases/leads
Additional Required: Pixel ID, Custom Event Type, Optimization Goal (OFFSITE_CONVERSIONS)
Budget: $100/day minimum recommended

3. Creative Testing (Dynamic Creative)

Setup: Set Dynamic Creative = TRUE
Fill: Main creative + Additional Body 1-3, Additional Title 1-3, Additional Image 1-2
Result: Meta tests all combinations automatically

4. Multi-Audience Testing

Setup: Duplicate row for each audience
Change: Ad Set Name, Targeting fields (Age, Interests, Locations)
Keep Same: Campaign Name, Ad creative

5. Carousel Product Showcase

Setup: Fill Carousel Card 1-10 fields
Each Card: Unique product image, title, description, link
Best For: E-commerce, feature comparisons

6. International Campaign (Multi-Language)

Setup: Fill Language 1-5 fields
Each Language: Translated copy + localized landing page
Target: Multiple countries in ad set targeting

---

Pro Tips

1. Naming Conventions

   • Use consistent naming: [Objective]_[Audience]_[Creative]_v[#]
   • Example: Traffic_TechEnthusiasts_HeroVideo_v1

2. UTM Tracking

   • Always fill UTM fields for proper attribution
   • Use UTM Content to identify ad variations

3. Bulk Variations

   • Duplicate rows to test multiple:
     • Audiences (change targeting)
     • Creatives (change image/copy)
     • Bids (change bid amount)
     • Budgets (change daily budget)

4. File Management

   • Name files systematically: ProductName_Placement_Version.jpg
   • Example: OpenClaw_Feed_v1.jpg, OpenClaw_Story_v1.jpg

5. Testing Strategy

   • Start with 3-5 ad variations per ad set
   • Test one variable at a time (audience OR creative, not both)
   • Give each ad set 3-5 days before evaluating

6. Common Mistakes to Avoid

   • Don't use $ symbols in budget fields
   • Don't include spaces in file names
   • Don't leave required fields blank
   • Don't mix Image Hash and Image File (use one or the other)
   • Don't forget UTM tracking

---

Field Count Summary

• Campaign Fields: 8
• Ad Set Fields: 27
• Ad Fields: 30
• Carousel Fields: 40 (10 cards × 4 fields)
• Multi-Language Fields: 20 (5 languages × 4 fields)
• Partnership Fields: 2

Total Available Fields: 127+

Typical Row Uses: 40-60 fields for standard campaigns

---

Generated by: Buba
Date: 2026-02-11
For: Advertising Report Card