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 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
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
{
"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 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:
- At least one of the four parameters above must be provided (cannot all be null or empty)
- Maximum 50 monitor objects can be added per request
- 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)
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
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
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
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
{
"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 |