clawdbot-workspace/FB_ADS_FIELD_REFERENCE.md

# Facebook Ads CSV Bulk Upload - Complete Field Reference

## 📚 Table of Contents
- [Campaign Level Fields](#campaign-level-fields)
- [Ad Set Level Fields](#ad-set-level-fields)
- [Ad Level Fields](#ad-level-fields)
- [Advanced Features](#advanced-features)
- [Validation Rules](#validation-rules)
- [Common Use Cases](#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