Social Media Campaigns API - Steer Autos Documentation

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

Facebook

Facebook Marketplace and News Feed ads

Instagram

Instagram Feed and Stories ads

TikTok

TikTok For You page ads (Coming soon)

Prerequisites

Before using the Campaigns API, you must:

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

Endpoints

Get Facebook Pages

GET

endpoint

/ads/facebook/pages

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

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

Response Fields:

string

Facebook Page ID

name

string

Page display name

picture

string

Page profile picture URL

account_id

string

Associated Facebook Ad Account ID

This endpoint is cached for 5 minutes to improve performance.

Activate Campaign

POST

endpoint

/ads/campaigns/activate

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

{
  "campaignId": "campaign_uuid",
  "platforms": ["facebook", "instagram"]
}

campaignId

string

required

Campaign UUID from your marketing campaign system

platforms

array

required

Array of platform names: facebook, instagram, tiktok. Must have at least one platform.

Response:

{
  "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:

results

array

Array of platform-specific results

success

boolean

Whether the campaign launched successfully on this platform

campaign_id

string

Platform-specific campaign ID

ad_set_id

string

Platform-specific ad set ID

ad_id

string

Platform-specific ad ID

platform

string

Platform name (facebook, instagram, tiktok)

error

string

Error message if campaign failed

Get Campaign Metrics

GET

endpoint

/ads/campaigns//metrics

Retrieve performance metrics for an active campaign. Path Parameters:

campaignId

string

required

Campaign UUID

Query Parameters:

platformType

enum

required

Platform to get metrics from: facebook, instagram, tiktok

Response:

{
  "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:

impressions

number

Number of times ad was displayed

clicks

number

Number of ad clicks

conversions

number

Number of successful conversions (leads, inquiries, etc.)

spent

number

Total amount spent (in account currency)

ctr

number

Click-through rate percentage

cpc

number

Cost per click

cpm

number

Cost per thousand impressions (mille)

reach

number

Unique users who saw the ad

frequency

number

Average times each user saw the ad

conversion_rate

number

Percentage of clicks that converted

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

Pause Campaign

POST

endpoint

/ads/campaigns//pause

Pause an active campaign on a specific platform. Path Parameters:

campaignId

string

required

Campaign UUID

Request Body:

{
  "platformType": "facebook"
}

platformType

enum

required

Platform to pause: facebook, instagram, tiktok

Response:

{
  "success": true,
  "campaign_id": "fb_campaign_123",
  "platform": "facebook",
  "message": "Campaign paused successfully"
}

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

Campaign Workflow

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

# 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

# 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

# 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

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 };
  }
}

Marketing Strategy Guide

Learn effective automotive marketing strategies

Vehicles API

Manage inventory for marketing campaigns

Analytics Dashboard

Track campaign ROI and performance

Best Practices

Marketing and API best practices

API Documentation

​Overview

​Supported Platforms

Facebook

Instagram

TikTok

​Prerequisites

​Endpoints

​Get Facebook Pages

​Activate Campaign

​Get Campaign Metrics

​Pause Campaign

​Campaign Workflow

​Campaign Best Practices

​Audience Targeting

​Budget Recommendations

​Creative Guidelines

​Use Cases

​Example 1: Launch Multi-Platform Campaign

​Example 2: Monitor Campaign Performance

​Example 3: Pause Underperforming Campaign

​Error Codes

​Platform-Specific Notes

​Facebook/Instagram

​TikTok

​Integration Example

​Related Resources

Marketing Strategy Guide

Vehicles API

Analytics Dashboard

Best Practices

Overview

Supported Platforms

Prerequisites

Endpoints

Get Facebook Pages

Activate Campaign

Get Campaign Metrics

Pause Campaign

Campaign Workflow

Campaign Best Practices

Audience Targeting

Budget Recommendations

Creative Guidelines

Use Cases

Example 1: Launch Multi-Platform Campaign

Example 2: Monitor Campaign Performance

Example 3: Pause Underperforming Campaign

Error Codes

Platform-Specific Notes

Facebook/Instagram

TikTok

Integration Example

Related Resources