# Create Monitor Task

This document explains how to create monitor tasks using advertiser accounts. There are four ways to create monitor tasks:

| Method | Parameter | Description | Example |
| ------ | --------- | ----------- | ------- |
| 1. Advertiser ID | facebook_page_id_list | Obtained via Advertiser Search API | `["614178972053891"]` |
| 2. Advertiser URL | facebook_page_url_list | Enter Facebook advertiser page URL directly | `["https://www.facebook.com/example"]` |
| 3. Public Page Number | facebook_public_page_number_list | Enter Facebook public page number | `["123456789"]` |
| 4. Store/Website URL | facebook_shop_url_list | Enter store, website, or landing page URL | `["https://example.com"]` |

> **Priority Note**: If multiple parameters are submitted simultaneously, the system uses them in the following priority: facebook_page_id_list > facebook_page_url_list > facebook_public_page_number_list > facebook_shop_url_list

---

## API 1: Advertiser Search

### API Information

- **API Name**: Advertiser Search
- **Request Method**: POST
- **API URL**: `open-api/v1/monitor/data`
- **Endpoint Path**: `/v3/api/ad-monitor-task/search-fb-ads-advertiser`
- **Description**: Search advertiser information by keyword and return a list of matching advertisers. Users can create monitor tasks using the returned `facebook_page_id`.
- **Usage Note**: Free

**Request Headers:**

- Content-Type: application/json
- Accept: application/json

### Request Parameters

#### Request Structure

| Parameter | Type   | Description                       | Example                                            | Required | Default |
| --------- | ------ | --------------------------------- | -------------------------------------------------- | -------- | ------- |
| key       | string | User's external API request key   | "your_api_key_here"                                | Yes      |         |
| uri       | string | Endpoint path                     | "/v3/api/ad-monitor-task/search-fb-ads-advertiser" | Yes      |         |
| params    | object | Request parameters object         | See parameter list                                 | Yes      |         |

#### Request Body Parameters (params object)

| Parameter | Type   | Required | Description              |
| --------- | ------ | -------- | ------------------------ |
| name      | String | Yes      | Advertiser name keyword  |

#### Request Example

```bash
curl -X POST "https://www.pipispy.com/open-api/v1/monitor/data" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "key": "your_api_key_here",
    "uri": "/v3/api/ad-monitor-task/search-fb-ads-advertiser",
    "params": {
      "name": "example"
    }
  }'
```

### Response Parameters

#### Response Structure

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "facebook_page_id": "714739975064116",
        "name": "Example Advertiser",
        "avatar_url": "https://example.com/avatar.jpg",
        "category": "Digital creator",
        "country": null
      }
    ]
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}
```

#### Response Field Description

| Field Name | Type    | Description                            |
| ---------- | ------- | -------------------------------------- |
| code       | Integer | Response status code, 200 means success |
| message    | String  | Response message                       |
| data       | Object  | Response data                          |
| version    | String  | API version                            |
| timestamp  | String  | Response timestamp                     |
| sign       | String  | Response signature                     |
| remaining_credits | Long    | Current remaining available credits after this request |
| consumed_credits  | Long    | Credits consumed by this request                       |
| success    | Boolean | Request success status                 |
| fail       | Boolean | Request failure status                 |

#### Response Data Fields

| Field Name              | Type   | Description                              |
| ----------------------- | ------ | ---------------------------------------- |
| data[].facebook_page_id | string | Advertiser ID, used to create monitor tasks |
| data[].name             | string | Advertiser name                          |
| data[].avatar_url       | string | Advertiser avatar                        |
| data[].category         | string | Category                                 |
| data[].country          | string | Country                                  |

---

## API 2: Create Monitor Task

### API Information

- **API Name**: Create Monitor Task
- **Request Method**: POST
- **API URL**: `open-api/v1/monitor/data`
- **Endpoint Path**: `/v3/api/ad-monitor-task/create-monitor-task`
- **Description**: Batch create monitor tasks for advertisers or stores/websites, supports four input methods, and returns the creation result for each task.
- **Usage Note**: 1 credit will be deducted for each successfully created monitor task

**Request Headers:**

- Content-Type: application/json
- Accept: application/json

### Request Parameters

#### Request Structure

| Parameter | Type   | Description                       | Example                                       | Required | Default |
| --------- | ------ | --------------------------------- | --------------------------------------------- | -------- | ------- |
| key       | string | User's external API request key   | "your_api_key_here"                           | Yes      |         |
| uri       | string | Endpoint path                     | "/v3/api/ad-monitor-task/create-monitor-task" | Yes      |         |
| params    | object | Request parameters object         | See parameter list                            | Yes      |         |

#### Request Body Parameters (params object)

| Parameter                        | Type          | Required | Description                                              |
| -------------------------------- | ------------- | -------- | -------------------------------------------------------- |
| facebook_page_id_list            | array[string] | No       | Advertiser ID list (can be obtained via Advertiser Search API) |
| facebook_page_url_list           | array[string] | No       | Advertiser page URL list                                 |
| facebook_public_page_number_list | array[string] | No       | Public page number list                                  |
| facebook_shop_url_list           | array[string] | No       | Store/website/landing page URL list                      |

> **Important Notes**:
> 1. At least one of the four parameters above must be provided (cannot all be null or empty)
> 2. Maximum 50 monitor objects can be added per request
> 3. **If multiple parameters are submitted simultaneously, the system uses them in priority order: facebook_page_id_list > facebook_page_url_list > facebook_public_page_number_list > facebook_shop_url_list**

#### Request Examples

**Method 1: Create via Advertiser ID (Recommended)**

```bash
curl -X POST "https://www.pipispy.com/open-api/v1/monitor/data" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "key": "your_api_key_here",
    "uri": "/v3/api/ad-monitor-task/create-monitor-task",
    "params": {
      "facebook_page_id_list": ["614178972053891", "714739975064116"]
    }
  }'
```

**Method 2: Create via Advertiser URL**

```bash
curl -X POST "https://www.pipispy.com/open-api/v1/monitor/data" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "key": "your_api_key_here",
    "uri": "/v3/api/ad-monitor-task/create-monitor-task",
    "params": {
      "facebook_page_url_list": ["https://www.facebook.com/example"]
    }
  }'
```

**Method 3: Create via Public Page Number**

```bash
curl -X POST "https://www.pipispy.com/open-api/v1/monitor/data" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "key": "your_api_key_here",
    "uri": "/v3/api/ad-monitor-task/create-monitor-task",
    "params": {
      "facebook_public_page_number_list": ["123456789"]
    }
  }'
```

**Method 4: Create via Store/Website URL**

```bash
curl -X POST "https://www.pipispy.com/open-api/v1/monitor/data" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "key": "your_api_key_here",
    "uri": "/v3/api/ad-monitor-task/create-monitor-task",
    "params": {
      "facebook_shop_url_list": ["https://example.com"]
    }
  }'
```

### Response Parameters

#### Response Structure

```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "task_id": "1005",
      "facebook_page_id": "614178972053891",
      "facebook_page_url": null,
      "facebook_public_page_number": null,
      "facebook_shop_url": null,
      "error_message": null
    }
  ],
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 1,
  "fail": false,
  "success": true
}
```

#### Response Field Description

| Field Name | Type    | Description                            |
| ---------- | ------- | -------------------------------------- |
| code       | Integer | Response status code, 200 means success |
| message    | String  | Response message                       |
| data       | Array   | Response data (task creation result list) |
| version    | String  | API version                            |
| timestamp  | String  | Response timestamp                     |
| sign       | String  | Response signature                     |
| success    | Boolean | Request success status                 |
| fail       | Boolean | Request failure status                 |

#### Response Data Fields

| Field Name                  | Type   | Description              |
| --------------------------- | ------ | ------------------------ |
| task_id                     | string | Monitor task ID          |
| facebook_page_id            | string | Advertiser ID            |
| facebook_page_url           | string | Advertiser URL           |
| facebook_public_page_number | string | Public page number       |
| facebook_shop_url           | string | Store/website URL        |
| error_message               | string | Error message (if any)   |

---

## Error Codes

| Error Code | Description              |
| ---------- | ------------------------ |
| 200        | Success                  |
| 400        | Invalid request parameters |
| 500        | Internal server error    |