Creative Creation API Endpoint

Overview

The Creative Creation API endpoint allows developers to create new creatives with automatic campaign and ad set management.
This endpoint intelligently handles existing resources and creates new ones as needed.

Endpoint Details

• URL: POST /v1/creatives
• Authentication: Required (Audiencelab-Token header)
• Content-Type: application/json

Authentication

Include your team access token in the request header:

Audiencelab-Token: your_team_access_token_here

Request Body

Required Fields

• creative (string) – The name for your creative
• app_api_key (string) – Your application’s API key to identify which app the creative belongs to

Optional Fields

• campaign (string) – Campaign name (if not provided, will create week-based campaign)
• adset (string) – Ad set name (if not provided, will create day-based ad set)

Example Request Body

{
  "creative": "Summer Sale Banner",
  "app_api_key": "your_app_api_key_here",
  "campaign": "Q4 Campaign",
  "adset": "Facebook Ads"
}

Behavior

When Campaign and Adset Names Are Provided

1. Existing Campaign + Existing Adset → Reuses both existing resources
2. Existing Campaign + New Adset → Reuses campaign, creates new adset
3. New Campaign + New Adset → Creates both new resources

When Campaign and Adset Names Are NOT Provided

• Campaign: Automatically creates "Week X" (e.g., "Week 45")
• Adset: Automatically creates day name (e.g., "Monday", "Tuesday")

Response Format

Success Response (201 Created)

{
  "message": "Creative created successfully",
  "creative": {
    "name": "Summer Sale Banner",
    "tracking_link": "https://appstore-download.com/creative_token"
  },
  "campaign": {
    "name": "Q4 Campaign",
    "is_new": false
  },
  "adset": {
    "name": "Facebook Ads",
    "is_new": true
  },
  "application": {
    "name": "Your App Name"
  }
}

Response Fields Explained

• creative.name → The name you provided for the creative
• creative.tracking_link → Generated tracking URL for the creative
• campaign.name → Campaign name (provided or auto-generated)
• campaign.is_new → Boolean indicating if a new campaign was created
• adset.name → Ad set name (provided or auto-generated)
• adset.is_new → Boolean indicating if a new ad set was created
• application.name → Your application’s name

Error Responses

400 Bad Request

{ "message": "Creative name is required" }

{ "message": "API key is required" }

{ "message": "Invalid API key or application not found" }

401 Unauthorized

{ "message": "Incorrect authentication token" }

Usage Examples

Example 1: Create Creative with Specific Campaign and Adset

curl -X POST https://app.audiencelab.ai/api/v1/creatives \
  -H "Content-Type: application/json" \
  -H "Audiencelab-Token: your_team_token" \
  -d '{
    "creative": "Holiday Promotion",
    "app_api_key": "your_app_key",
    "campaign": "Holiday 2024",
    "adset": "Instagram Stories"
  }'

Example 2: Create Creative with Auto-generated Campaign and Adset

curl -X POST https://app.audiencelab.ai/api/v1/creatives \
  -H "Content-Type: application/json" \
  -H "Audiencelab-Token: your_team_token" \
  -d '{
    "creative": "Product Launch Video",
    "app_api_key": "your_app_key"
  }'

Example 3: JavaScript/Fetch

const response = await fetch("/v1/creatives", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Audiencelab-Token": "your_team_token",
  },
  body: JSON.stringify({
    creative: "Brand Awareness Ad",
    app_api_key: "your_app_key",
    campaign: "Brand Campaign",
    adset: "Facebook Feed",
  }),
});

const result = await response.json();
console.log("Creative created:", result);

Best Practices

1. Naming Conventions
   • Use descriptive, meaningful names for creatives
   • Campaign names should represent marketing initiatives or time periods
   • Ad set names should indicate targeting or placement strategy
2. Resource Management
   • Check is_new flags to understand what resources were created
   • Reuse existing campaigns and ad sets when possible to maintain organization
   • Use consistent naming patterns for better resource management
3. Error Handling
   • Always check for error responses
   • Validate required fields before sending requests
   • Handle authentication errors gracefully
4. Rate Limiting
   • Implement appropriate delays between requests
   • Monitor API usage to avoid hitting rate limits

Integration Notes

Tracking Links

• Each creative gets a unique tracking link
• Use the tracking_link for an ad’s final destination URL
• Link format: https://appstore-download.com/{creative_token}

Resource IDs

• Campaign and ad set names serve as identifiers
• For creatives, these don’t have to be unique
• For campaigns and adsets, an existing item will be reused

Application Isolation

• Application API keys are validated against your team’s applications

Troubleshooting

Common Issues

1. Authentication Failed
   • Verify your Audiencelab-Token is correct
   • Ensure the token hasn’t expired or been revoked
2. Invalid API Key
   • Verify that an Application has been created in the Audiencelab dashboard
   • Ensure the app_api_key was copied correctly and hasn’t been revoked
3. Missing Required Fields
   • Ensure creative field is provided
   • Ensure app_api_key field is provided
   • Check JSON syntax and Content-Type header

Support

For additional support or questions about this API endpoint, please contact the development team or refer to the internal API documentation.