# Agent Marketing Tools API Documentation

This document provides API documentation for the Marketing Tools features of the Agent Module.

## Base URL

All endpoints are relative to the base URL of your application.

## Authentication

All endpoints require authentication. Include the authentication token in the request header:

```
Authorization: Bearer {token}
```

## Endpoints

### Marketing Materials

#### List Marketing Materials

Retrieves a list of available marketing materials.

**URL**: `/api/agent/marketing/materials`

**Method**: `GET`

**Query Parameters**:

| Parameter | Type   | Required | Description                                      |
|-----------|--------|----------|--------------------------------------------------|
| page      | int    | No       | Page number for pagination (default: 1)          |
| per_page  | int    | No       | Number of items per page (default: 10)           |
| type      | string | No       | Filter by type (social, email, print, video)     |
| search    | string | No       | Search term to filter materials by title         |

**Response**:

```json
{
  "data": [
    {
      "id": 1,
      "title": "Social Media Post Template",
      "description": "A template for social media posts about referrals",
      "type": "social",
      "thumbnail_url": "https://example.com/thumbnails/social-post.jpg",
      "has_file": false,
      "has_template": true,
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    {
      "id": 2,
      "title": "Email Newsletter Template",
      "description": "A template for email newsletters",
      "type": "email",
      "thumbnail_url": "https://example.com/thumbnails/email-newsletter.jpg",
      "has_file": false,
      "has_template": true,
      "created_at": "2023-01-02T00:00:00Z",
      "updated_at": "2023-01-02T00:00:00Z"
    },
    {
      "id": 3,
      "title": "Printable Brochure",
      "description": "A printable brochure for in-person marketing",
      "type": "print",
      "thumbnail_url": "https://example.com/thumbnails/brochure.jpg",
      "has_file": true,
      "has_template": false,
      "created_at": "2023-01-03T00:00:00Z",
      "updated_at": "2023-01-03T00:00:00Z"
    },
    // More marketing materials...
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "path": "/api/agent/marketing/materials",
    "per_page": 10,
    "to": 10,
    "total": 50
  }
}
```

#### Get Marketing Material

Retrieves a specific marketing material.

**URL**: `/api/agent/marketing/materials/{id}`

**Method**: `GET`

**URL Parameters**:

| Parameter | Type | Required | Description               |
|-----------|------|----------|---------------------------|
| id        | int  | Yes      | ID of the marketing material |

**Response**:

```json
{
  "data": {
    "id": 1,
    "title": "Social Media Post Template",
    "description": "A template for social media posts about referrals",
    "type": "social",
    "thumbnail_url": "https://example.com/thumbnails/social-post.jpg",
    "file_url": null,
    "template_content": "Check out this amazing opportunity to earn extra income through referrals with [COMPANY_NAME]! Use my referral code [REFERRAL_CODE] to sign up today. #referrals #[COMPANY_NAME] #extraincome",
    "personalized_content": "Check out this amazing opportunity to earn extra income through referrals with Go MD USA! Use my referral code AGENT123XYZ to sign up today. #referrals #GoMDUSA #extraincome",
    "usage_count": 15,
    "last_used_at": "2023-01-15T10:30:00Z",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
}
```

#### Download Marketing Material

Downloads a marketing material file.

**URL**: `/api/agent/marketing/materials/{id}/download`

**Method**: `GET`

**URL Parameters**:

| Parameter | Type | Required | Description               |
|-----------|------|----------|---------------------------|
| id        | int  | Yes      | ID of the marketing material |

**Response**:

The file will be downloaded directly.

#### Share Marketing Material

Records a share of a marketing material.

**URL**: `/api/agent/marketing/materials/{id}/share`

**Method**: `POST`

**URL Parameters**:

| Parameter | Type | Required | Description               |
|-----------|------|----------|---------------------------|
| id        | int  | Yes      | ID of the marketing material |

**Request Body**:

```json
{
  "platform": "facebook" // Options: facebook, twitter, linkedin, email, other
}
```

**Response**:

```json
{
  "message": "Marketing material shared successfully",
  "data": {
    "id": 1,
    "marketing_material_id": 1,
    "usage_type": "share_facebook",
    "created_at": "2023-01-15T10:30:00Z"
  }
}
```

### Landing Pages

#### List Landing Pages

Retrieves a list of the agent's landing pages.

**URL**: `/api/agent/marketing/landing-pages`

**Method**: `GET`

**Query Parameters**:

| Parameter | Type   | Required | Description                                      |
|-----------|--------|----------|--------------------------------------------------|
| page      | int    | No       | Page number for pagination (default: 1)          |
| per_page  | int    | No       | Number of items per page (default: 10)           |
| status    | string | No       | Filter by status (active, inactive)              |

**Response**:

```json
{
  "data": [
    {
      "id": 1,
      "title": "Referral Program Landing Page",
      "slug": "referral-program",
      "template": "basic",
      "is_active": true,
      "visit_count": 150,
      "conversion_count": 12,
      "conversion_rate": 8.0,
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    {
      "id": 2,
      "title": "Special Offer Landing Page",
      "slug": "special-offer",
      "template": "professional",
      "is_active": true,
      "visit_count": 200,
      "conversion_count": 25,
      "conversion_rate": 12.5,
      "created_at": "2023-01-15T00:00:00Z",
      "updated_at": "2023-01-15T00:00:00Z"
    },
    // More landing pages...
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "/api/agent/marketing/landing-pages",
    "per_page": 10,
    "to": 2,
    "total": 2
  }
}
```

#### Get Landing Page

Retrieves a specific landing page.

**URL**: `/api/agent/marketing/landing-pages/{id}`

**Method**: `GET`

**URL Parameters**:

| Parameter | Type | Required | Description               |
|-----------|------|----------|---------------------------|
| id        | int  | Yes      | ID of the landing page    |

**Response**:

```json
{
  "data": {
    "id": 1,
    "title": "Referral Program Landing Page",
    "slug": "referral-program",
    "template": "basic",
    "content": "<h1>Join Our Referral Program</h1><p>Earn rewards by referring friends and family!</p>",
    "settings": {
      "header_color": "#2b7ab8",
      "button_color": "#da395d",
      "show_logo": true,
      "show_contact_form": true
    },
    "is_active": true,
    "full_url": "https://example.com/agent/referral-program",
    "visit_count": 150,
    "conversion_count": 12,
    "conversion_rate": 8.0,
    "recent_visits": [
      {
        "id": 1,
        "ip_address": "192.168.1.1",
        "referrer": "google.com",
        "created_at": "2023-01-20T10:30:00Z"
      },
      {
        "id": 2,
        "ip_address": "192.168.1.2",
        "referrer": "facebook.com",
        "created_at": "2023-01-20T11:15:00Z"
      },
      // More visits...
    ],
    "recent_conversions": [
      {
        "id": 1,
        "name": "John Doe",
        "email": "john@example.com",
        "created_at": "2023-01-20T10:45:00Z"
      },
      {
        "id": 2,
        "name": "Jane Smith",
        "email": "jane@example.com",
        "created_at": "2023-01-20T12:30:00Z"
      },
      // More conversions...
    ],
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
}
```

#### Create Landing Page

Creates a new landing page.

**URL**: `/api/agent/marketing/landing-pages`

**Method**: `POST`

**Request Body**:

```json
{
  "title": "New Landing Page",
  "template": "basic",
  "content": "<h1>Welcome to my landing page</h1><p>This is a custom landing page for my referrals.</p>",
  "settings": {
    "header_color": "#2b7ab8",
    "button_color": "#da395d",
    "show_logo": true,
    "show_contact_form": true
  },
  "is_active": true
}
```

**Response**:

```json
{
  "message": "Landing page created successfully",
  "data": {
    "id": 3,
    "title": "New Landing Page",
    "slug": "new-landing-page",
    "template": "basic",
    "content": "<h1>Welcome to my landing page</h1><p>This is a custom landing page for my referrals.</p>",
    "settings": {
      "header_color": "#2b7ab8",
      "button_color": "#da395d",
      "show_logo": true,
      "show_contact_form": true
    },
    "is_active": true,
    "full_url": "https://example.com/agent/new-landing-page",
    "created_at": "2023-01-21T09:00:00Z",
    "updated_at": "2023-01-21T09:00:00Z"
  }
}
```

#### Update Landing Page

Updates an existing landing page.

**URL**: `/api/agent/marketing/landing-pages/{id}`

**Method**: `PUT`

**URL Parameters**:

| Parameter | Type | Required | Description               |
|-----------|------|----------|---------------------------|
| id        | int  | Yes      | ID of the landing page    |

**Request Body**:

```json
{
  "title": "Updated Landing Page",
  "content": "<h1>Welcome to my updated landing page</h1><p>This is an updated landing page for my referrals.</p>",
  "settings": {
    "header_color": "#3366cc",
    "button_color": "#ff6600",
    "show_logo": true,
    "show_contact_form": true
  },
  "is_active": true
}
```

**Response**:

```json
{
  "message": "Landing page updated successfully",
  "data": {
    "id": 1,
    "title": "Updated Landing Page",
    "slug": "referral-program",
    "template": "basic",
    "content": "<h1>Welcome to my updated landing page</h1><p>This is an updated landing page for my referrals.</p>",
    "settings": {
      "header_color": "#3366cc",
      "button_color": "#ff6600",
      "show_logo": true,
      "show_contact_form": true
    },
    "is_active": true,
    "full_url": "https://example.com/agent/referral-program",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-21T10:00:00Z"
  }
}
```

#### Delete Landing Page

Deletes a landing page.

**URL**: `/api/agent/marketing/landing-pages/{id}`

**Method**: `DELETE`

**URL Parameters**:

| Parameter | Type | Required | Description               |
|-----------|------|----------|---------------------------|
| id        | int  | Yes      | ID of the landing page    |

**Response**:

```json
{
  "message": "Landing page deleted successfully"
}
```

### Marketing Analytics

#### Get Marketing Performance

Retrieves marketing performance metrics.

**URL**: `/api/agent/marketing/performance`

**Method**: `GET`

**Query Parameters**:

| Parameter | Type   | Required | Description                                      |
|-----------|--------|----------|--------------------------------------------------|
| period    | string | No       | Time period (week, month, quarter, year, all)    |
| start_date| string | No       | Start date for custom period (YYYY-MM-DD)        |
| end_date  | string | No       | End date for custom period (YYYY-MM-DD)          |

**Response**:

```json
{
  "data": {
    "material_usage": {
      "total_views": 250,
      "total_downloads": 75,
      "total_shares": 120,
      "by_type": {
        "social": {
          "views": 100,
          "downloads": 0,
          "shares": 80
        },
        "email": {
          "views": 80,
          "downloads": 15,
          "shares": 30
        },
        "print": {
          "views": 50,
          "downloads": 50,
          "shares": 10
        },
        "video": {
          "views": 20,
          "downloads": 10,
          "shares": 0
        }
      },
      "by_platform": {
        "facebook": 50,
        "twitter": 30,
        "linkedin": 25,
        "email": 15
      }
    },
    "landing_pages": {
      "total_visits": 500,
      "total_conversions": 45,
      "overall_conversion_rate": 9.0,
      "by_page": [
        {
          "id": 1,
          "title": "Referral Program Landing Page",
          "visits": 150,
          "conversions": 12,
          "conversion_rate": 8.0
        },
        {
          "id": 2,
          "title": "Special Offer Landing Page",
          "visits": 200,
          "conversions": 25,
          "conversion_rate": 12.5
        },
        // More pages...
      ]
    },
    "referrals": {
      "total_referrals": 35,
      "conversion_to_referral_rate": 77.8,
      "by_source": {
        "landing_page": 20,
        "social": 10,
        "email": 5
      }
    },
    "time_series": {
      "labels": ["Jan 1", "Jan 2", "Jan 3", "Jan 4", "Jan 5", "Jan 6", "Jan 7"],
      "visits": [20, 25, 30, 35, 40, 45, 50],
      "conversions": [2, 3, 3, 4, 5, 5, 6],
      "referrals": [1, 2, 2, 3, 3, 4, 5]
    }
  }
}
```

## Error Responses

### 401 Unauthorized

```json
{
  "error": "Unauthorized",
  "message": "Authentication token is invalid or expired"
}
```

### 403 Forbidden

```json
{
  "error": "Forbidden",
  "message": "You do not have permission to access this resource"
}
```

### 404 Not Found

```json
{
  "error": "Not Found",
  "message": "The requested resource was not found"
}
```

### 422 Validation Error

```json
{
  "error": "Validation Error",
  "message": "The given data was invalid",
  "errors": {
    "title": [
      "The title field is required"
    ],
    "content": [
      "The content field is required"
    ]
  }
}
```

### 500 Server Error

```json
{
  "error": "Server Error",
  "message": "An unexpected error occurred"
}
```