> ## Documentation Index
> Fetch the complete documentation index at: https://docs.steerai.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# Social Media Campaigns API

> Automate marketing campaigns across Facebook, Instagram, and TikTok

## Overview

The Social Media Campaigns API enables automated marketing campaigns for your vehicle listings across major social platforms. Launch multi-platform campaigns, track performance metrics, and manage ad spend directly from the Steer AI platform.

## Supported Platforms

<CardGroup cols={3}>
  <Card title="Facebook" icon="facebook">
    Facebook Marketplace and News Feed ads
  </Card>

  <Card title="Instagram" icon="instagram">
    Instagram Feed and Stories ads
  </Card>

  <Card title="TikTok" icon="tiktok">
    TikTok For You page ads (Coming soon)
  </Card>
</CardGroup>

## Prerequisites

Before using the Campaigns API, you must:

1. Connect your social media accounts via the upload-post service
2. Have an active Facebook Business Manager account
3. Set up payment methods for ad accounts

## Endpoints

### Get Facebook Pages

<ParamField path="GET" type="endpoint">
  /ads/facebook/pages
</ParamField>

Retrieve Facebook pages available for advertising that are linked to your account.

**Response:**

```json theme={null}
{
  "success": true,
  "pages": [
    {
      "id": "123456789",
      "name": "Prime Auto Dealership",
      "picture": "https://...",
      "account_id": "act_9876543210"
    }
  ]
}
```

**Response Fields:**

<ResponseField name="id" type="string">
  Facebook Page ID
</ResponseField>

<ResponseField name="name" type="string">
  Page display name
</ResponseField>

<ResponseField name="picture" type="string">
  Page profile picture URL
</ResponseField>

<ResponseField name="account_id" type="string">
  Associated Facebook Ad Account ID
</ResponseField>

<Info>
  This endpoint is cached for 5 minutes to improve performance.
</Info>

***

### Activate Campaign

<ParamField path="POST" type="endpoint">
  /ads/campaigns/activate
</ParamField>

Launch a marketing campaign on one or more social media platforms.

**Request Body:**

```json theme={null}
{
  "campaignId": "campaign_uuid",
  "platforms": ["facebook", "instagram"]
}
```

<ParamField body="campaignId" type="string" required>
  Campaign UUID from your marketing campaign system
</ParamField>

<ParamField body="platforms" type="array" required>
  Array of platform names: `facebook`, `instagram`, `tiktok`. Must have at least one platform.
</ParamField>

**Response:**

```json theme={null}
{
  "results": [
    {
      "success": true,
      "campaign_id": "fb_campaign_123",
      "ad_set_id": "fb_adset_456",
      "ad_id": "fb_ad_789",
      "platform": "facebook",
      "message": "Campaign activated successfully"
    },
    {
      "success": true,
      "campaign_id": "ig_campaign_123",
      "ad_set_id": "ig_adset_456",
      "ad_id": "ig_ad_789",
      "platform": "instagram",
      "message": "Campaign activated successfully"
    }
  ],
  "summary": {
    "total": 2,
    "successes": 2,
    "errors": 0,
    "successful_platforms": ["facebook", "instagram"],
    "error_messages": []
  }
}
```

**Response Fields:**

<ResponseField name="results" type="array">
  Array of platform-specific results
</ResponseField>

<ResponseField name="success" type="boolean">
  Whether the campaign launched successfully on this platform
</ResponseField>

<ResponseField name="campaign_id" type="string">
  Platform-specific campaign ID
</ResponseField>

<ResponseField name="ad_set_id" type="string">
  Platform-specific ad set ID
</ResponseField>

<ResponseField name="ad_id" type="string">
  Platform-specific ad ID
</ResponseField>

<ResponseField name="platform" type="string">
  Platform name (facebook, instagram, tiktok)
</ResponseField>

<ResponseField name="error" type="string">
  Error message if campaign failed
</ResponseField>

***

### Get Campaign Metrics

<ParamField path="GET" type="endpoint">
  /ads/campaigns/{campaignId}/metrics
</ParamField>

Retrieve performance metrics for an active campaign.

**Path Parameters:**

<ParamField path="campaignId" type="string" required>
  Campaign UUID
</ParamField>

**Query Parameters:**

<ParamField query="platformType" type="enum" required>
  Platform to get metrics from: `facebook`, `instagram`, `tiktok`
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "impressions": 125430,
    "clicks": 3421,
    "conversions": 87,
    "spent": 1250.50,
    "ctr": 2.73,
    "cpc": 0.37,
    "cpm": 9.97,
    "reach": 98234,
    "frequency": 1.28,
    "conversion_rate": 2.54
  }
}
```

**Metrics Explained:**

<ResponseField name="impressions" type="number">
  Number of times ad was displayed
</ResponseField>

<ResponseField name="clicks" type="number">
  Number of ad clicks
</ResponseField>

<ResponseField name="conversions" type="number">
  Number of successful conversions (leads, inquiries, etc.)
</ResponseField>

<ResponseField name="spent" type="number">
  Total amount spent (in account currency)
</ResponseField>

<ResponseField name="ctr" type="number">
  Click-through rate percentage
</ResponseField>

<ResponseField name="cpc" type="number">
  Cost per click
</ResponseField>

<ResponseField name="cpm" type="number">
  Cost per thousand impressions (mille)
</ResponseField>

<ResponseField name="reach" type="number">
  Unique users who saw the ad
</ResponseField>

<ResponseField name="frequency" type="number">
  Average times each user saw the ad
</ResponseField>

<ResponseField name="conversion_rate" type="number">
  Percentage of clicks that converted
</ResponseField>

<Info>
  Metrics are cached for 1 minute. Data may take 24-48 hours to fully stabilize on the platform side.
</Info>

***

### Pause Campaign

<ParamField path="POST" type="endpoint">
  /ads/campaigns/{campaignId}/pause
</ParamField>

Pause an active campaign on a specific platform.

**Path Parameters:**

<ParamField path="campaignId" type="string" required>
  Campaign UUID
</ParamField>

**Request Body:**

```json theme={null}
{
  "platformType": "facebook"
}
```

<ParamField body="platformType" type="enum" required>
  Platform to pause: `facebook`, `instagram`, `tiktok`
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "campaign_id": "fb_campaign_123",
  "platform": "facebook",
  "message": "Campaign paused successfully"
}
```

<Warning>
  Pausing a campaign stops ad delivery immediately but does not delete the campaign. You can reactivate it later.
</Warning>

***

## Campaign Workflow

```mermaid theme={null}
graph TD
    A[Create Campaign] --> B{Connect Accounts?}
    B -->|No| C[Connect Facebook/Instagram]
    B -->|Yes| D[Get Facebook Pages]
    C --> D
    D --> E[Select Target Pages]
    E --> F[Configure Campaign]
    F --> G[Activate Campaign]
    G --> H{Launch Success?}
    H -->|Yes| I[Monitor Metrics]
    H -->|No| J[Review Errors]
    I --> K{Performance OK?}
    K -->|Yes| L[Continue]
    K -->|No| M[Optimize Campaign]
    M --> I
    L --> N{Campaign Complete?}
    N -->|No| I
    N -->|Yes| O[Pause/Archive]
    J --> F

    style G fill:#282F75
    style I fill:#4360B1
    style O fill:#28a745
```

## Campaign Best Practices

### Audience Targeting

Configure your campaigns for optimal reach:

* **Location:** Target specific cities or regions where you operate
* **Age Range:** Typically 25-54 for auto purchases
* **Interests:** Car enthusiasts, new car shoppers, luxury vehicles
* **Behaviors:** In-market for vehicles, recently moved, new job

### Budget Recommendations

| Campaign Type          | Daily Budget | Duration   | Expected Results   |
| ---------------------- | ------------ | ---------- | ------------------ |
| **Local Awareness**    | \$20-50      | 7-14 days  | 5,000-15,000 reach |
| **Lead Generation**    | \$50-100     | 14-30 days | 50-150 leads       |
| **Inventory Showcase** | \$100-200    | 30-60 days | 100-300 inquiries  |
| **Special Promotion**  | \$200-500    | 7-14 days  | 200-500 leads      |

### Creative Guidelines

**Images:**

* High-quality vehicle photos (1080x1080 recommended)
* Multiple angles showing exterior and interior
* Professional lighting and clean backgrounds
* Include price or special offer overlays

**Copy:**

* Clear, concise messaging (125 characters or less)
* Include make, model, year
* Highlight key features or benefits
* Strong call-to-action ("Schedule Test Drive", "View Details")

**Video (if applicable):**

* 15-30 seconds optimal length
* Show vehicle in motion and details
* Add captions (80% watch without sound)
* Include branding at start and end

## Use Cases

### Example 1: Launch Multi-Platform Campaign

```bash theme={null}
# Activate campaign on Facebook and Instagram
curl -X POST "https://api.steerai.autos/v1/ads/campaigns/activate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "campaign_uuid",
    "platforms": ["facebook", "instagram"]
  }'
```

### Example 2: Monitor Campaign Performance

```bash theme={null}
# Get Facebook campaign metrics
curl -X GET "https://api.steerai.autos/v1/ads/campaigns/{campaignId}/metrics?platformType=facebook" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example 3: Pause Underperforming Campaign

```bash theme={null}
# Pause campaign if metrics don't meet targets
curl -X POST "https://api.steerai.autos/v1/ads/campaigns/{campaignId}/pause" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platformType": "facebook"
  }'
```

## Error Codes

| Code                      | Status | Description                                  |
| ------------------------- | ------ | -------------------------------------------- |
| `USER_NOT_REGISTERED`     | 400    | User not registered with upload-post service |
| `ACCOUNT_NOT_CONNECTED`   | 400    | Social media account not connected           |
| `CAMPAIGN_NOT_FOUND`      | 404    | Campaign ID does not exist                   |
| `INVALID_PLATFORM`        | 400    | Unsupported platform specified               |
| `INSUFFICIENT_AD_CREDIT`  | 402    | Not enough credit in ad account              |
| `PAGE_NOT_FOUND`          | 404    | Facebook page not found or not accessible    |
| `PERMISSION_DENIED`       | 403    | Missing required permissions for platform    |
| `CAMPAIGN_ALREADY_ACTIVE` | 400    | Campaign is already running                  |

## Platform-Specific Notes

### Facebook/Instagram

* Requires Facebook Business Manager account
* Ad account must have payment method configured
* Page must have at least 30 followers for boosted posts
* Review times: 24 hours typical, up to 48 hours for complex ads
* Minimum daily budget: \$5 USD equivalent

### TikTok

* Currently in development
* Will require TikTok Business account
* Minimum daily budget: \$20 USD equivalent
* Review times: Up to 24 hours

## Integration Example

```javascript theme={null}
class CampaignManager {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseURL = 'https://api.steerai.autos/v1';
  }

  async activateCampaign(campaignId, platforms) {
    const response = await fetch(`${this.baseURL}/ads/campaigns/activate`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ campaignId, platforms })
    });
    return response.json();
  }

  async getMetrics(campaignId, platform) {
    const response = await fetch(
      `${this.baseURL}/ads/campaigns/${campaignId}/metrics?platformType=${platform}`,
      {
        headers: { 'Authorization': `Bearer ${this.apiKey}` }
      }
    );
    return response.json();
  }

  async pauseCampaign(campaignId, platform) {
    const response = await fetch(
      `${this.baseURL}/ads/campaigns/${campaignId}/pause`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.apiKey}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ platformType: platform })
      }
    );
    return response.json();
  }

  // Monitor campaign and auto-pause if CPC exceeds threshold
  async monitorCampaign(campaignId, platform, maxCPC) {
    const metrics = await this.getMetrics(campaignId, platform);

    if (metrics.data.cpc > maxCPC) {
      console.log(`CPC ${metrics.data.cpc} exceeds threshold ${maxCPC}. Pausing campaign.`);
      await this.pauseCampaign(campaignId, platform);
      return { action: 'paused', reason: 'CPC_THRESHOLD_EXCEEDED' };
    }

    return { action: 'continue', metrics: metrics.data };
  }
}
```

## Related Resources

<CardGroup cols={2}>
  <Card title="Marketing Strategy Guide" icon="bullhorn" href="/guides/marketing-strategy">
    Learn effective automotive marketing strategies
  </Card>

  <Card title="Vehicles API" icon="car" href="/api-reference/vehicles/overview">
    Manage inventory for marketing campaigns
  </Card>

  <Card title="Analytics Dashboard" icon="chart-line" href="/api-reference/analytics/dashboard-statistics">
    Track campaign ROI and performance
  </Card>

  <Card title="Best Practices" icon="star" href="/guides/best-practices">
    Marketing and API best practices
  </Card>
</CardGroup>