Enhanced Campaign Creation API Documentation

# Enhanced Campaign Creation API Documentation

## Overview
The Enhanced Campaign Creation API provides a comprehensive endpoint for creating marketing campaigns with advanced features including location targeting, creator requirements, milestone-based rewards, video specifications, and timeline management.

**Base URL:** `https://adx-web-backend.up.railway.app`

**API Version:** v2

---

## Endpoints

### 1. POST /api/v2/campaigns

Create a new enhanced campaign with comprehensive features and advanced targeting options.

#### Request

**Method:** `POST`

**URL:** `/api/v2/campaigns`

**Headers:**
```
Content-Type: application/json
```

**Authentication:** Not required - This is a public endpoint. No authentication token is needed.

#### Request Body

The request body must be a JSON object with the following structure:

##### Required Fields

| Field | Type | Required | Validation | Description |
|-------|------|----------|------------|-------------|
| `title` | string | ✅ | 5-100 chars, no `<>{}[]` | Campaign title |
| `description` | string | ✅ | 10-500 chars, no `<>{}[]` | Campaign description |
| `budget` | number | ✅ | 100-10,000,000 | Total campaign budget |
| `currency` | string | ✅ | `₹`, `$`, `€`, `£` | Currency symbol |
| `type` | string | ✅ | `fashion`, `tech`, `travel`, `food`, `lifestyle`, `beauty` | Campaign category |
| `platforms` | array | ✅ | 1-8 items, valid platform names | Target social media platforms |
| `created_at` | string | ✅ | ISO 8601 datetime | Campaign creation timestamp |
| `location_targeting` | object | ✅ | See LocationTargeting | Location targeting settings |
| `timeline` | object | ✅ | See Timeline | Campaign timeline |

##### Location Targeting (Required)

```json
{
  "type": "Global" | "Country" | "City" | "Radius",
  "country": "string (required if type is Country or City)",
  "city": "string (required if type is City)",
  "radius_km": "number (required if type is Radius, 1-1000)",
  "target_language": "string (optional)",
  "latitude": "number (optional)",
  "longitude": "number (optional)",
  "address": "string (optional)",
  "regions": ["string"] (optional, array of region names)
}
```

##### Timeline (Required)

```json
{
  "start_date": "ISO 8601 datetime (required, must be future date)",
  "end_date": "ISO 8601 datetime (required, must be after start_date)",
  "duration_days": "integer (required, >= 1, must match date difference)",
  "posting_schedule": "string (optional, e.g., 'Flexible', 'Daily', 'Weekly')"
}
```

##### Optional Fields

| Field | Type | Description |
|-------|------|-------------|
| `summary` | string | Campaign summary |
| `full_description` | string | Full campaign description |
| `content_type` | string | `Video`, `Image`, `Story`, `Reel`, `Post` |
| `number_of_posts` | integer | Number of posts required (>= 1) |
| `posting_schedule` | string | Posting schedule description |
| `creative_instructions` | string | Creative brief and instructions |
| `key_messages` | array | List of key messages to convey |
| `requirements` | array | List of campaign requirements |
| `video_specifications` | object | Video content specifications |
| `creator_requirements` | object | Creator requirements and demographics |
| `max_applicants` | integer | Maximum number of applicants (>= 1) |
| `application_deadline` | string | ISO 8601 datetime (must be before timeline.start_date) |
| `auto_close_when_full` | boolean | Auto close when max applicants reached (default: false) |
| `application_instructions` | string | Instructions for applicants |
| `milestones` | array | Campaign milestones (must have valid UUID IDs) |
| `brand_name` | string | Brand name |
| `contact_person` | string | Contact person name |
| `deliverables` | array | List of deliverables |
| `tags` | array | Campaign tags |
| `poster_url` | string | URL to campaign poster image |
| `verification_required` | boolean | Enable verification system (default: true) |
| `analytics_integration` | boolean | Enable analytics tracking (default: true) |
| `target_audience` | string | Target audience summary text |
| `end_date` | string | ISO 8601 datetime (alternative to timeline.end_date) |

##### Video Specifications (Optional)

```json
{
  "min_length": "integer (>= 1, seconds)",
  "max_length": "integer (>= 1, > min_length, seconds)",
  "quality": "HD720" | "HD1080" | "UHD4K",
  "platforms": ["string"] (array of platform names)
}
```

##### Creator Requirements (Optional)

```json
{
  "min_followers": "integer (>= 0, optional)",
  "max_followers": "integer (>= 0, > min_followers, optional)",
  "interests": ["string"] (array of interest names),
  "talent_types": ["string"] (array of talent type names),
  "demographics": {
    "age_range": {
      "min": "integer (13-100)",
      "max": "integer (13-100, > min)"
    },
    "gender": "string (optional)",
    "location": "string (optional)"
  },
  "age_range": {
    "min": "integer (13-100)",
    "max": "integer (13-100, > min)"
  },
  "location": "string (optional)"
}
```

##### Milestones (Optional)

```json
[
  {
    "id": "UUID string (required, valid UUID format)",
    "title": "string (1-100 chars, required)",
    "description": "string (1-500 chars, required)",
    "due_date": "ISO 8601 datetime (required, must be within campaign timeline)",
    "reward_amount": "number (> 0, required)",
    "deliverables": ["string"] (array, at least 1 item required)
  }
]
```

**Valid Platform Values:**
- `Instagram`
- `YouTube`
- `Facebook`
- `Twitter`
- `TikTok`
- `LinkedIn`
- `Snapchat`
- `Pinterest`

**Valid Campaign Types:**
- `fashion`
- `tech`
- `travel`
- `food`
- `lifestyle`
- `beauty`

**Valid Content Types:**
- `Video`
- `Image`
- `Story`
- `Reel`
- `Post`

#### Complete Request Example

```json
{
  "title": "Summer Fashion Campaign 2024",
  "description": "Looking for creative influencers to showcase our latest summer collection",
  "budget": 50000.0,
  "currency": "₹",
  "type": "fashion",
  "platforms": ["Instagram", "YouTube"],
  "created_at": "2024-01-15T10:30:00Z",
  "location_targeting": {
    "type": "Country",
    "country": "India",
    "city": "",
    "radius_km": null,
    "target_language": "English",
    "latitude": null,
    "longitude": null,
    "address": "",
    "regions": []
  },
  "timeline": {
    "start_date": "2024-06-01T00:00:00Z",
    "end_date": "2024-07-01T00:00:00Z",
    "duration_days": 30,
    "posting_schedule": "Flexible"
  },
  "summary": "Fashion campaign for summer collection with Instagram and YouTube promotion",
  "full_description": "Complete campaign description with all details...",
  "content_type": "Video",
  "number_of_posts": 3,
  "posting_schedule": "Flexible",
  "creative_instructions": "Create engaging video content showcasing summer outfits with natural lighting and outdoor settings",
  "key_messages": [
    "Summer vibes",
    "Trendy fashion",
    "Comfortable and stylish"
  ],
  "requirements": [
    "Must show product clearly",
    "Include brand hashtags",
    "Tag @brandname"
  ],
  "video_specifications": {
    "min_length": 30,
    "max_length": 180,
    "quality": "HD1080",
    "platforms": ["Instagram", "YouTube"]
  },
  "creator_requirements": {
    "min_followers": 10000,
    "max_followers": null,
    "interests": ["Fashion", "Lifestyle"],
    "talent_types": ["Fashion Influencer", "Lifestyle Blogger"],
    "demographics": {
      "age_range": {
        "min": 18,
        "max": 35
      },
      "gender": "All",
      "location": "India"
    },
    "age_range": {
      "min": 18,
      "max": 35
    },
    "location": "India"
  },
  "max_applicants": 50,
  "application_deadline": "2024-05-25T23:59:59Z",
  "auto_close_when_full": true,
  "application_instructions": "Please submit your portfolio and previous work samples. Include links to your social media profiles.",
  "milestones": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "title": "Content Submission",
      "description": "Submit initial content drafts",
      "due_date": "2024-06-15T23:59:59Z",
      "reward_amount": 10000.0,
      "deliverables": ["Video draft", "Image selection"]
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "title": "Final Content",
      "description": "Submit final approved content",
      "due_date": "2024-06-25T23:59:59Z",
      "reward_amount": 25000.0,
      "deliverables": ["Final video", "Social media posts"]
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "title": "Campaign Completion",
      "description": "Campaign goes live and metrics tracked",
      "due_date": "2024-07-01T23:59:59Z",
      "reward_amount": 15000.0,
      "deliverables": ["Analytics report", "Engagement metrics"]
    }
  ],
  "brand_name": "Fashion Co",
  "contact_person": "John Doe",
  "deliverables": [
    "3 Instagram posts",
    "2 YouTube videos",
    "1 Instagram Story series"
  ],
  "tags": ["summer", "fashion", "influencer", "lifestyle"],
  "poster_url": "https://cdn.yourapp.com/campaigns/poster-abc123.jpg",
  "verification_required": true,
  "analytics_integration": true,
  "target_audience": "Location: Country - India\nLanguage: English\nAge Range: 18-35\nGender: All\nInterests: Fashion, Lifestyle",
  "end_date": "2024-07-01T00:00:00Z"
}
```

#### Minimal Request Example

```json
{
  "title": "Simple Campaign",
  "description": "This is a simple campaign description with minimum required fields",
  "budget": 5000.0,
  "currency": "₹",
  "type": "lifestyle",
  "platforms": ["Instagram"],
  "created_at": "2024-01-15T10:30:00Z",
  "location_targeting": {
    "type": "Global",
    "country": null,
    "city": null,
    "radius_km": null,
    "target_language": null,
    "latitude": null,
    "longitude": null,
    "address": null,
    "regions": []
  },
  "timeline": {
    "start_date": "2024-06-01T00:00:00Z",
    "end_date": "2024-06-15T00:00:00Z",
    "duration_days": 14,
    "posting_schedule": null
  }
}
```

#### Response

**Status Code:** `201 Created`

**Response Structure:**
```json
{
  "success": true,
  "data": {
    "campaign_id": "string",
    "status": "draft",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "message": "Campaign created successfully"
  }
}
```

**Response Fields:**

| Field | Type | Description |
|-------|------|-------------|
| `success` | boolean | Whether the request was successful (always `true` for 201) |
| `data.campaign_id` | string | Unique campaign identifier (database ID as string) |
| `data.status` | string | Campaign status (`draft` for new campaigns) |
| `data.created_at` | datetime | ISO 8601 timestamp of campaign creation |
| `data.updated_at` | datetime | ISO 8601 timestamp of last update (initially same as created_at) |
| `data.message` | string | Success message |

**Example Response:**
```json
{
  "success": true,
  "data": {
    "campaign_id": "123456789",
    "status": "draft",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "message": "Campaign created successfully"
  }
}
```

#### Validation Rules

##### Field-Level Validation

| Field | Validation Rule | Error Message |
|-------|----------------|---------------|
| `title` | 5-100 characters, no `<>{}[]` | "Title cannot contain <, >, {, }, [, ]" |
| `description` | 10-500 characters, no `<>{}[]` | "Description cannot contain <, >, {, }, [, ]" |
| `budget` | 100-10,000,000 | "budget must be between 100 and 10000000" |
| `currency` | Must be one of: `₹`, `$`, `€`, `£` | "Input should be '₹', '$', '€' or '£'" |
| `type` | Must be valid campaign type | "Input should be 'fashion', 'tech', 'travel', 'food', 'lifestyle' or 'beauty'" |
| `platforms` | 1-8 items, valid platform names | "Invalid platform: {platform}" |
| `location_targeting.type` | Must be `Global`, `Country`, `City`, or `Radius` | "Input should be 'Global', 'Country', 'City' or 'Radius'" |
| `location_targeting.country` | Required if type is `Country` or `City` | "country is required when type is Country or City" |
| `location_targeting.city` | Required if type is `City` | "city is required when type is City" |
| `location_targeting.radius_km` | Required if type is `Radius`, 1-1000 | "radius_km is required when type is Radius" |
| `timeline.start_date` | Must be future date | "timeline start_date must be in the future" |
| `timeline.end_date` | Must be after start_date | "end_date must be after start_date" |
| `timeline.duration_days` | Must match date difference | "duration_days must match the difference between start_date and end_date" |
| `creator_requirements.age_range.min` | 13-100 | "creator_requirements.age_range.min must be between 13 and 100" |
| `creator_requirements.age_range.max` | 13-100, > min | "creator_requirements.age_range.max must be greater than min" |
| `milestones[].id` | Valid UUID format | "milestone id must be a valid UUID format" |
| `milestones[].due_date` | Must be within campaign timeline | "Milestone {id} due_date must be within campaign timeline" |

##### Business Logic Validation

| Rule | Error Message |
|------|---------------|
| Total milestone rewards exceed budget | "Total milestone rewards cannot exceed campaign budget" |
| Application deadline not before timeline start | "application_deadline must be before timeline.start_date" |
| Duplicate milestone IDs | "Milestone IDs must be unique" |
| Maximum 8 platforms | "Maximum 8 platforms allowed" |

#### Error Responses

##### 400 Bad Request - Business Logic Validation

```json
{
  "detail": {
    "error": "Validation failed",
    "details": [
      {
        "field": "budget",
        "message": "Insufficient wallet balance. Required: 50000, Available: 30000"
      }
    ]
  }
}
```

##### 422 Unprocessable Entity - Input Validation

```json
{
  "detail": [
    {
      "type": "string_too_short",
      "loc": ["body", "title"],
      "msg": "String should have at least 5 characters",
      "input": "Hi"
    },
    {
      "type": "value_error",
      "loc": ["body", "title"],
      "msg": "Title cannot contain <, >, {, }, [, ]",
      "input": "Campaign <Test>"
    }
  ]
}
```

##### 500 Internal Server Error

```json
{
  "detail": "Internal server error occurred while creating campaign"
}
```

---

### 2. GET /api/v2/campaigns/health

Health check endpoint for the Campaign APIs v2 service.

#### Request

**Method:** `GET`

**URL:** `/api/v2/campaigns/health`

**Headers:**
```
(No headers required)
```

#### Response

**Status Code:** `200 OK`

**Response Structure:**
```json
{
  "status": "healthy",
  "service": "campaign_apis_v2",
  "timestamp": "2024-01-15T10:30:00.123456"
}
```

---

## Usage Examples

### cURL Examples

#### Create Campaign (Minimal)

```bash
curl -X POST 'https://adx-web-backend.up.railway.app/api/v2/campaigns' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Summer Fashion Campaign",
    "description": "Looking for creative influencers to showcase our latest summer collection",
    "budget": 50000.0,
    "currency": "₹",
    "type": "fashion",
    "platforms": ["Instagram", "YouTube"],
    "created_at": "2024-01-15T10:30:00Z",
    "location_targeting": {
      "type": "Country",
      "country": "India",
      "city": null,
      "radius_km": null,
      "target_language": "English",
      "latitude": null,
      "longitude": null,
      "address": null,
      "regions": []
    },
    "timeline": {
      "start_date": "2024-06-01T00:00:00Z",
      "end_date": "2024-07-01T00:00:00Z",
      "duration_days": 30,
      "posting_schedule": "Flexible"
    }
  }'
```

#### Create Campaign (Full Example)

```bash
curl -X POST 'https://adx-web-backend.up.railway.app/api/v2/campaigns' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Tech Review Campaign",
    "description": "Comprehensive tech review campaign for new smartphone",
    "budget": 75000.0,
    "currency": "₹",
    "type": "tech",
    "platforms": ["YouTube", "Instagram"],
    "created_at": "2024-01-15T10:30:00Z",
    "location_targeting": {
      "type": "Global",
      "country": null,
      "city": null,
      "radius_km": null,
      "target_language": "English",
      "latitude": null,
      "longitude": null,
      "address": null,
      "regions": []
    },
    "timeline": {
      "start_date": "2024-06-01T00:00:00Z",
      "end_date": "2024-07-01T00:00:00Z",
      "duration_days": 30,
      "posting_schedule": "Flexible"
    },
    "video_specifications": {
      "min_length": 120,
      "max_length": 600,
      "quality": "HD1080",
      "platforms": ["YouTube"]
    },
    "creator_requirements": {
      "min_followers": 50000,
      "interests": ["Technology", "Gadgets"],
      "age_range": {
        "min": 18,
        "max": 45
      }
    },
    "milestones": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "title": "Unboxing Video",
        "description": "Submit unboxing and first impressions video",
        "due_date": "2024-06-15T23:59:59Z",
        "reward_amount": 25000.0,
        "deliverables": ["Unboxing video", "First impressions"]
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440002",
        "title": "Full Review",
        "description": "Submit comprehensive review video",
        "due_date": "2024-06-30T23:59:59Z",
        "reward_amount": 50000.0,
        "deliverables": ["Full review video", "Performance benchmarks"]
      }
    ]
  }'
```

### JavaScript/TypeScript Examples

#### Using Fetch API

```typescript
interface CampaignRequest {
  title: string;
  description: string;
  budget: number;
  currency: "₹" | "$" | "€" | "£";
  type: "fashion" | "tech" | "travel" | "food" | "lifestyle" | "beauty";
  platforms: string[];
  created_at: string;
  location_targeting: {
    type: "Global" | "Country" | "City" | "Radius";
    country?: string | null;
    city?: string | null;
    radius_km?: number | null;
    target_language?: string | null;
    latitude?: number | null;
    longitude?: number | null;
    address?: string | null;
    regions?: string[];
  };
  timeline: {
    start_date: string;
    end_date: string;
    duration_days: number;
    posting_schedule?: string | null;
  };
  // ... optional fields
}

async function createCampaign(
  campaignData: CampaignRequest
): Promise<{ success: boolean; data: { campaign_id: string; status: string; created_at: string; updated_at: string; message: string } }> {
  const headers: HeadersInit = {
    'Content-Type': 'application/json',
  };

  const response = await fetch(
    'https://adx-web-backend.up.railway.app/api/v2/campaigns',
    {
      method: 'POST',
      headers,
      body: JSON.stringify(campaignData),
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.detail?.error || error.detail || 'Failed to create campaign');
  }

  return await response.json();
}

// Usage
const campaignData: CampaignRequest = {
  title: "Summer Fashion Campaign 2024",
  description: "Looking for creative influencers to showcase our latest summer collection",
  budget: 50000.0,
  currency: "₹",
  type: "fashion",
  platforms: ["Instagram", "YouTube"],
  created_at: new Date().toISOString(),
  location_targeting: {
    type: "Country",
    country: "India",
    city: null,
    radius_km: null,
    target_language: "English",
    latitude: null,
    longitude: null,
    address: null,
    regions: []
  },
  timeline: {
    start_date: "2024-06-01T00:00:00Z",
    end_date: "2024-07-01T00:00:00Z",
    duration_days: 30,
    posting_schedule: "Flexible"
  }
};

createCampaign(campaignData)
  .then(result => console.log('Campaign created:', result))
  .catch(error => console.error('Error:', error));
```

#### Using Axios

```typescript
import axios from 'axios';

const api = axios.create({
  baseURL: 'https://adx-web-backend.up.railway.app',
  headers: {
    'Content-Type': 'application/json',
  },
});

export const createCampaign = async (
  campaignData: CampaignRequest
) => {
  try {
    const response = await api.post('/api/v2/campaigns', campaignData);
    return response.data;
  } catch (error) {
    if (axios.isAxiosError(error)) {
      throw new Error(
        error.response?.data?.detail?.error ||
        error.response?.data?.detail ||
        'Failed to create campaign'
      );
    }
    throw error;
  }
};

export const checkHealth = async () => {
  try {
    const response = await api.get('/api/v2/campaigns/health');
    return response.data;
  } catch (error) {
    throw new Error('Health check failed');
  }
};
```

---

## Key Notes

1. **No Authentication Required**: This endpoint is public and does not require authentication. Campaigns are created without user validation.

2. **Milestone Rewards**: If milestones are included, the total of all milestone reward amounts must not exceed the campaign budget.

3. **Date Validation**: 
   - All milestone `due_date` values must be within the campaign timeline (between `timeline.start_date` and `timeline.end_date`)
   - `application_deadline` must be before `timeline.start_date`
   - `timeline.start_date` must be in the future

4. **Platform Values**: Valid platform strings are:
   - `Instagram`, `YouTube`, `Facebook`, `Twitter`, `TikTok`, `LinkedIn`, `Snapchat`, `Pinterest`

5. **Content Type Options**:
   - `Video`, `Image`, `Story`, `Reel`, `Post`

6. **Campaign Status Flow**:
   - New campaigns start as `draft`
   - Can transition to: `pending` → `active` → `completed` or `cancelled`

7. **All Data is Dynamic**: All campaign data is stored dynamically from the request payload. No static or hardcoded values are used.

8. **Location Targeting**: 
   - If `type` is `Country` or `City`, `country` is required
   - If `type` is `City`, `city` is required
   - If `type` is `Radius`, `radius_km` is required (1-1000)

9. **Milestone IDs**: Must be valid UUID format (e.g., `550e8400-e29b-41d4-a716-446655440001`)

10. **Age Range Validation**: 
    - Minimum age: 13
    - Maximum age: 100
    - Max must be greater than min

---

## Testing

You can test the API using:

- **cURL**: Use the examples provided above
- **Postman**: Import the request examples
- **JavaScript/TypeScript**: Use the provided code examples
- **Python**: Use the `requests` library with similar structure

### Testing Checklist

- [ ] Minimal required fields only
- [ ] Full payload with all optional fields
- [ ] Invalid field values (validation errors)
- [ ] Milestone rewards exceed budget
- [ ] Invalid dates (past dates, wrong order)
- [ ] Invalid milestone IDs (non-UUID format)
- [ ] Invalid platform names
- [ ] Health check endpoint

---

## Support

For issues or questions:
- Check the validation error messages for field-specific issues
- Ensure all required fields are provided
- Verify date formats are ISO 8601
- Confirm platform and type values are from the valid lists

---

## Changelog

### Version 2.0
- Enhanced request payload structure with comprehensive fields
- Location targeting with multiple types (Global, Country, City, Radius)
- Creator requirements with demographics
- Video specifications
- Milestone-based reward system
- Timeline management
- Dynamic data storage (no static values)
- Updated response format matching specification
- Public endpoint (no authentication required)