Operations (sample payloads)

Main operations
Copy

Create custom audience
Copy

Create a custom audience in your business account.

Sample Input

1{
2    "ad_account_id": "123456789",
3    "name": "New Custom Audience",
4    "customer_file_source": "USER_PROVIDED_ONLY",
5    "description": "A custom audience for our summer campaign",
6    "app_ids": [
7        "987654321",
8        "876543210"
9    ],
10    "audience_members": {
11        "audience_member_list": [
12            {
13                "email": "john.doe@example.com",
14                "first_name": "John",
15                "last_name": "Doe",
16                "country_code": "us",
17                "city": "New York",
18                "zip_code": "10001",
19                "phone": "+12125551234",
20                "gender": "m",
21                "birth_year": "1985",
22                "birth_month": "06",
23                "birth_day": "15"
24            },
25            {
26                "email": "jane.smith@example.com",
27                "first_name": "Jane",
28                "last_name": "Smith",
29                "country_code": "ca",
30                "city": "Toronto",
31                "phone": "+14165557890",
32                "gender": "f",
33                "birth_year": "1990",
34                "birth_month": "09",
35                "birth_day": "22"
36            }
37        ]
38    }
39}

Sample Output

1{
2    "id": "6789012345"
3}

Create post
Copy

Create a new post.

Sample Input

1{
2    "page_id": "123456789012345",
3    "message": "Check out our latest product launch! 🚀 Visit our website for more details.",
4    "publish": true,
5    "scheduled_publish_time": "2023-06-15T14:30:00Z"
6}

Sample Output

1{
2    "id": "987654321098765"
3}

Delete audience members
Copy

Remove members from a given audience.

Sample Input

1{
2    "custom_audience_id": "6789012345",
3    "audience_members": {
4        "audience_member_list": [
5            {
6                "email": "johndoe@example.com",
7                "phone": "+1234567890",
8                "first_name": "John",
9                "last_name": "Doe",
10                "country_code": "us",
11                "zip_code": "90210"
12            },
13            {
14                "email": "janedoe@example.com",
15                "phone": "+1987654321",
16                "first_name": "Jane",
17                "last_name": "Doe",
18                "country_code": "ca",
19                "city": "Toronto"
20            }
21        ]
22    }
23}

Sample Output

1{
2    "audience_id": "6789012345",
3    "session_id": "1234567890abcdef",
4    "num_received": 2,
5    "num_invalid_entries": 0,
6    "invalid_entry_samples": {}
7}

Delete custom audience
Copy

Delete a custom audience.

Sample Input

1{
2    "custom_audience_id": "23842001234567890"
3}

Sample Output

1{
2    "success": true
3}

Get ad
Copy

Retrieve an ad using its ID.

Sample Input

1{
2    "ad_id": "23843234567890123"
3}

Sample Output

1{
2    "id": "23843234567890123",
3    "account_id": "1234567890",
4    "adset": {
5        "id": "6789012345678901"
6    },
7    "adset_id": "6789012345678901",
8    "bid_type": "LOWEST_COST_WITH_BID_CAP",
9    "campaign": {
10        "id": "5678901234567890"
11    },
12    "campaign_id": "5678901234567890",
13    "configured_status": "ACTIVE",
14    "created_time": "2023-05-15T10:30:00+0000",
15    "creative": {
16        "id": "7890123456789012"
17    },
18    "effective_status": "ACTIVE",
19    "last_updated_by_app_id": "987654321098765",
20    "name": "Summer Sale Promotion",
21    "source_ad_id": "23843234567890123",
22    "status": "ACTIVE",
23    "updated_time": "2023-05-16T14:45:00+0000"
24}

Get ad account
Copy

Retrieve an ad account using its ID.

Sample Input

1{
2    "ad_account_id": "act_123456789"
3}

Sample Output

1{
2    "id": "act_123456789",
3    "account_id": "123456789",
4    "account_status": 1,
5    "age": 365,
6    "amount_spent": "10000.00",
7    "balance": "5000.00",
8    "can_create_brand_lift_study": true,
9    "capabilities": [
10        "ADVERTISING",
11        "AUDIENCE_MANAGEMENT",
12        "CUSTOM_AUDIENCE_CREATION"
13    ],
14    "created_time": "2022-01-01T00:00:00+0000",
15    "currency": "USD",
16    "disable_reason": 0,
17    "fb_entity": 2,
18    "funding_source": "CREDIT_CARD",
19    "funding_source_details": {},
20    "has_migrated_permissions": true,
21    "is_attribution_spec_system_default": true,
22    "is_direct_deals_enabled": false,
23    "is_in_3ds_authorization_enabled_market": true,
24    "is_in_middle_of_local_entity_migration": false,
25    "is_notifications_enabled": true,
26    "is_personal": 0,
27    "is_prepay_account": false,
28    "is_tax_id_required": false,
29    "min_campaign_group_spend_cap": "100.00",
30    "min_daily_budget": 1,
31    "name": "My Ad Account",
32    "offsite_pixels_tos_accepted": true,
33    "owner": "12345678901234567",
34    "spend_cap": "50000.00",
35    "tax_id_status": 0,
36    "tax_id_type": "NONE",
37    "timezone_id": 1,
38    "timezone_name": "America/Los_Angeles",
39    "timezone_offset_hours_utc": -7,
40    "tos_accepted": {},
41    "user_tos_accepted": {
42        "custom_audience_tos": 1
43    }
44}

Get ad account insights
Copy

Retrieve insights from a specific ad account.

Sample Input

1{
2    "ad_account_id": "act_123456789",
3    "date_preset": "last_30d",
4    "level": "account",
5    "breakdowns": [
6        "age",
7        "gender"
8    ],
9    "action_breakdowns": [
10        "action_type"
11    ],
12    "time_increment": 1,
13    "limit": 10
14}

Sample Output

1{
2    "data": [
3        {
4            "account_currency": "USD",
5            "account_id": "act_123456789",
6            "account_name": "My Ad Account",
7            "actions": [
8                {
9                    "action_type": "link_click",
10                    "value": "150"
11                },
12                {
13                    "action_type": "page_engagement",
14                    "value": "300"
15                }
16            ],
17            "clicks": "200",
18            "cost_per_action_type": [
19                {
20                    "action_type": "link_click",
21                    "value": "0.5"
22                },
23                {
24                    "action_type": "page_engagement",
25                    "value": "0.25"
26                }
27            ],
28            "cost_per_inline_link_click": "0.45",
29            "cost_per_inline_post_engagement": "0.22",
30            "cpc": "0.5",
31            "cpm": "10.00",
32            "cpp": "5.00",
33            "ctr": "2.5",
34            "date_start": "2023-05-01",
35            "date_stop": "2023-05-31",
36            "frequency": "2.5",
37            "impressions": "10000",
38            "inline_link_click_ctr": "2.0",
39            "inline_link_clicks": "180",
40            "inline_post_engagement": "350",
41            "objective": "LINK_CLICKS",
42            "reach": "4000",
43            "social_spend": "25.00",
44            "spend": "100.00",
45            "unique_clicks": "180",
46            "unique_ctr": "2.2",
47            "age": "25-34",
48            "gender": "female"
49        }
50    ],
51    "paging": {
52        "cursors": {
53            "before": "MAZDZD",
54            "after": "MjQZD"
55        }
56    }
57}

Get ad insights
Copy

Retrieve insights for a specific ad.

Sample Input

1{
2    "ad_id": "6273849201234567",
3    "action_attribution_windows": [
4        "1d_view",
5        "28d_click"
6    ],
7    "action_breakdowns": [
8        "action_type",
9        "action_device"
10    ],
11    "breakdowns": [
12        "age",
13        "gender"
14    ],
15    "date_preset": "last_30d",
16    "level": "ad",
17    "limit": 10
18}

Sample Output

1{
2    "data": [
3        {
4            "account_currency": "USD",
5            "account_id": "1234567890",
6            "account_name": "My Ad Account",
7            "actions": [
8                {
9                    "action_type": "link_click",
10                    "value": "150"
11                },
12                {
13                    "action_type": "page_engagement",
14                    "value": "300"
15                }
16            ],
17            "ad_id": "6273849201234567",
18            "ad_name": "Summer Sale Ad",
19            "adset_id": "6273849201234568",
20            "adset_name": "Summer Sale Adset",
21            "buying_type": "AUCTION",
22            "campaign_id": "6273849201234569",
23            "campaign_name": "Summer Sale Campaign",
24            "clicks": "200",
25            "cost_per_action_type": [
26                {
27                    "action_type": "link_click",
28                    "value": "0.5"
29                },
30                {
31                    "action_type": "page_engagement",
32                    "value": "0.25"
33                }
34            ],
35            "cost_per_inline_link_click": "0.45",
36            "cpc": "0.5",
37            "cpm": "10.00",
38            "ctr": "2.5",
39            "date_start": "2023-05-01",
40            "date_stop": "2023-05-30",
41            "frequency": "3.2",
42            "impressions": "8000",
43            "reach": "2500",
44            "spend": "100.00",
45            "unique_clicks": "180",
46            "unique_ctr": "2.25"
47        }
48    ],
49    "paging": {
50        "cursors": {
51            "before": "MAZDZD",
52            "after": "MjQZD"
53        }
54    }
55}

Get adset
Copy

Retrieve an adset using its ID.

Sample Input

1{
2    "adset_id": "23843234567890123"
3}

Sample Output

1{
2    "id": "23843234567890123",
3    "account_id": "1234567890",
4    "attribution_spec": [
5        {
6            "event_type": "CLICK",
7            "window_days": 7
8        },
9        {
10            "event_type": "VIEW",
11            "window_days": 1
12        }
13    ],
14    "bid_strategy": "LOWEST_COST_WITHOUT_CAP",
15    "billing_event": "IMPRESSIONS",
16    "budget_remaining": "5000",
17    "campaign": {
18        "id": "6789012345678901"
19    },
20    "campaign_id": "6789012345678901",
21    "configured_status": "ACTIVE",
22    "created_time": "2023-05-01T10:30:00+0000",
23    "daily_budget": "1000",
24    "destination_type": "WEBSITE",
25    "effective_status": "ACTIVE",
26    "is_dynamic_creative": false,
27    "lifetime_budget": "50000",
28    "lifetime_imps": 1000000,
29    "name": "Summer Sale Adset",
30    "optimization_goal": "LINK_CLICKS",
31    "pacing_type": [
32        "standard"
33    ],
34    "promoted_object": {
35        "pixel_id": "987654321098765",
36        "custom_event_type": "PURCHASE",
37        "pixel_rule": "page_view"
38    },
39    "recurring_budget_semantics": false,
40    "source_adset": {
41        "id": "12345678901234567"
42    },
43    "source_adset_id": "12345678901234567",
44    "start_time": "2023-05-15T00:00:00+0000",
45    "status": "ACTIVE",
46    "targeting": {
47        "age_max": 65,
48        "age_min": 18,
49        "excluded_custom_audiences": [
50            {
51                "id": "6543210987654321",
52                "name": "Existing Customers"
53            }
54        ],
55        "custom_audiences": [
56            {
57                "id": "7654321098765432",
58                "name": "Website Visitors"
59            }
60        ],
61        "geo_locations": {
62            "countries": [
63                "US",
64                "CA"
65            ],
66            "location_types": [
67                "home",
68                "recent"
69            ]
70        },
71        "targeting_optimization": "expansion_all",
72        "publisher_platforms": [
73            "facebook",
74            "instagram"
75        ],
76        "facebook_positions": [
77            "feed",
78            "right_hand_column"
79        ],
80        "instagram_positions": [
81            "stream"
82        ],
83        "device_platforms": [
84            "mobile",
85            "desktop"
86        ],
87        "messenger_positions": [
88            "messenger_home"
89        ]
90    },
91    "updated_time": "2023-05-10T15:45:00+0000",
92    "use_new_app_click": true
93}

Get adset insights
Copy

Retrieve insights for a specific adset.

Sample Input

1{
2    "adset_id": "23843234567890123",
3    "limit": 1,
4    "date_preset": "last_7d",
5    "action_breakdowns": [
6        "action_type"
7    ],
8    "breakdowns": [
9        "age",
10        "gender"
11    ],
12    "fields": [
13        "impressions",
14        "clicks",
15        "spend",
16        "ctr",
17        "actions"
18    ]
19}

Sample Output

1{
2    "data": [
3        {
4            "account_currency": "USD",
5            "account_id": "1234567890",
6            "account_name": "My Ad Account",
7            "actions": [
8                {
9                    "action_type": "link_click",
10                    "value": "42"
11                },
12                {
13                    "action_type": "page_engagement",
14                    "value": "78"
15                }
16            ],
17            "adset_id": "23843234567890123",
18            "adset_name": "Summer Sale Promotion",
19            "age": "25-34",
20            "gender": "female",
21            "clicks": "65",
22            "ctr": "2.5",
23            "date_start": "2023-05-01",
24            "date_stop": "2023-05-07",
25            "impressions": "2600",
26            "spend": "150.25"
27        }
28    ],
29    "paging": {
30        "cursors": {
31            "before": "MAZDZD",
32            "after": "MjQZD"
33        }
34    }
35}

Get audience
Copy

Retrieve a custom audience.

Sample Input

1{
2    "audience_id": "6789012345",
3    "audience_type": "custom"
4}

Sample Output

1{
2    "id": "6789012345",
3    "name": "High-Value Customers",
4    "approximate_count": 50000,
5    "customer_file_source": "USER_PROVIDED_ONLY",
6    "data_source": {
7        "type": "FILE_IMPORTED",
8        "sub_type": "CUSTOM_AUDIENCE",
9        "creation_params": "{\"origin\":\"ui\"}"
10    },
11    "delivery_status": {
12        "code": 200,
13        "description": "Audience is ready and can be used for delivery"
14    },
15    "description": "Customers who have made purchases over $1000 in the last 6 months",
16    "is_value_based": false,
17    "operation_status": {
18        "code": 200,
19        "description": "Audience data is processed and ready"
20    },
21    "permission_for_actions": {
22        "can_edit": true,
23        "can_see_insight": true,
24        "can_share": false,
25        "subtype_supports_lookalike": true,
26        "supports_recipient_lookalike": true
27    },
28    "retention_days": 180,
29    "subtype": "CUSTOM",
30    "time_content_updated": 1623456789,
31    "time_created": 1620123456,
32    "time_updated": 1623456789
33}

Get business user
Copy

Retrieve a business user detail using ID.

Sample Input

1{
2    "business_user_id": "1234567890"
3}

Sample Output

1{
2    "id": "1234567890",
3    "business": {
4        "id": "9876543210",
5        "name": "Acme Corporation"
6    },
7    "email": "john.doe@acmecorp.com",
8    "finance_permission": "EDITOR",
9    "first_name": "John",
10    "ip_permission": "NONE",
11    "last_name": "Doe",
12    "name": "John Doe",
13    "pending_email": null,
14    "role": "ADMIN",
15    "title": "Marketing Manager",
16    "two_fac_status": "ENABLED"
17}

Get campaign
Copy

Retrieve a campaign using its ID.

Sample Input

1{
2    "campaign_id": "6273849201"
3}

Sample Output

1{
2    "id": "6273849201",
3    "account_id": "1234567890",
4    "bid_strategy": "LOWEST_COST_WITHOUT_CAP",
5    "budget_rebalance_flag": true,
6    "budget_remaining": "5000.00",
7    "buying_type": "AUCTION",
8    "can_create_brand_lift_study": false,
9    "can_use_spend_cap": true,
10    "configured_status": "ACTIVE",
11    "created_time": "2023-05-01T10:30:00+0000",
12    "daily_budget": "1000.00",
13    "effective_status": "ACTIVE",
14    "name": "Summer Sale Campaign",
15    "objective": "CONVERSIONS",
16    "source_campaign_id": "6273849200",
17    "start_time": "2023-05-15T00:00:00+0000",
18    "status": "ACTIVE",
19    "updated_time": "2023-05-10T14:45:00+0000"
20}

Get campaign insights
Copy

Retrieve insights for a specific campaign.

Sample Input

1{
2    "campaign_id": "6273849506172",
3    "action_attribution_windows": [
4        "1d_view",
5        "28d_click"
6    ],
7    "action_breakdowns": [
8        "action_type",
9        "action_device"
10    ],
11    "breakdowns": [
12        "age",
13        "gender"
14    ],
15    "date_preset": "last_30d",
16    "level": "campaign",
17    "time_increment": 7,
18    "limit": 10
19}

Sample Output

1{
2    "data": [
3        {
4            "account_currency": "USD",
5            "account_id": "1234567890",
6            "account_name": "My Ad Account",
7            "actions": [
8                {
9                    "action_type": "link_click",
10                    "value": "1250"
11                },
12                {
13                    "action_type": "page_engagement",
14                    "value": "3500"
15                }
16            ],
17            "buying_type": "AUCTION",
18            "campaign_id": "6273849506172",
19            "campaign_name": "Summer Sale Campaign",
20            "clicks": "2800",
21            "cost_per_action_type": [
22                {
23                    "action_type": "link_click",
24                    "value": "0.52"
25                },
26                {
27                    "action_type": "page_engagement",
28                    "value": "0.18"
29                }
30            ],
31            "cost_per_inline_link_click": "0.48",
32            "cost_per_inline_post_engagement": "0.15",
33            "cost_per_unique_click": "0.75",
34            "cpc": "0.45",
35            "cpm": "5.20",
36            "cpp": "3.80",
37            "ctr": "2.5",
38            "date_start": "2023-05-01",
39            "date_stop": "2023-05-07",
40            "frequency": "2.8",
41            "impressions": "112000",
42            "inline_link_click_ctr": "2.2",
43            "inline_link_clicks": "2450",
44            "inline_post_engagement": "4200",
45            "objective": "LINK_CLICKS",
46            "reach": "40000",
47            "social_spend": "250.00",
48            "spend": "1260.00",
49            "unique_clicks": "1680",
50            "unique_ctr": "1.5",
51            "unique_inline_link_click_ctr": "1.8",
52            "unique_inline_link_clicks": "2000",
53            "unique_link_clicks_ctr": "1.9",
54            "website_ctr": [
55                {
56                    "action_type": "link_click",
57                    "value": "2.2"
58                }
59            ]
60        }
61    ],
62    "paging": {
63        "cursors": {
64            "before": "MAZDZD",
65            "after": "MjQZD"
66        }
67    }
68}

Get lead
Copy

Get data about a specific lead using their ID.

Sample Input

1{
2    "lead_id": "6789012345678901"
3}

Sample Output

1{
2    "created_time": "2023-05-15T10:30:45+0000",
3    "id": "6789012345678901",
4    "field_data": [
5        {
6            "name": "full_name",
7            "values": [
8                "John Doe"
9            ]
10        },
11        {
12            "name": "email",
13            "values": [
14                "johndoe@example.com"
15            ]
16        },
17        {
18            "name": "phone_number",
19            "values": [
20                "+1234567890"
21            ]
22        }
23    ],
24    "ad_id": "1234567890123456",
25    "ad_name": "Summer Sale Promotion",
26    "adset_id": "2345678901234567",
27    "adset_name": "Interest-based Audience",
28    "campaign_id": "3456789012345678",
29    "campaign_name": "Q2 Sales Campaign",
30    "form_id": "4567890123456789",
31    "is_organic": false,
32    "platform": "facebook"
33}

Get page insights
Copy

Get insights for a specific page.

Sample Input

1{
2    "page_id": "123456789012345",
3    "metric": [
4        "page_impressions",
5        "page_engaged_users",
6        "page_fans"
7    ],
8    "date_preset": "last_30d",
9    "period": "day",
10    "show_description_from_api_doc": true,
11    "since": "2023-05-01T00:00:00Z",
12    "until": "2023-05-30T23:59:59Z"
13}

Sample Output

1{
2    "data": [
3        {
4            "name": "page_impressions",
5            "period": "day",
6            "values": [
7                {
8                    "value": 1234,
9                    "end_time": "2023-05-01T07:00:00+0000"
10                },
11                {
12                    "value": 1567,
13                    "end_time": "2023-05-02T07:00:00+0000"
14                }
15            ],
16            "title": "Page Impressions",
17            "description": "The number of times any content from your Page or about your Page entered a person's screen.",
18            "id": "123456789012345/insights/page_impressions/day"
19        },
20        {
21            "name": "page_engaged_users",
22            "period": "day",
23            "values": [
24                {
25                    "value": 456,
26                    "end_time": "2023-05-01T07:00:00+0000"
27                },
28                {
29                    "value": 789,
30                    "end_time": "2023-05-02T07:00:00+0000"
31                }
32            ],
33            "title": "Page Engaged Users",
34            "description": "The number of people who engaged with your Page. Engagement includes any click or story created.",
35            "id": "123456789012345/insights/page_engaged_users/day"
36        },
37        {
38            "name": "page_fans",
39            "period": "day",
40            "values": [
41                {
42                    "value": 10000,
43                    "end_time": "2023-05-01T07:00:00+0000"
44                },
45                {
46                    "value": 10050,
47                    "end_time": "2023-05-02T07:00:00+0000"
48                }
49            ],
50            "title": "Page Fans",
51            "description": "The total number of people who have liked your Page.",
52            "id": "123456789012345/insights/page_fans/day"
53        }
54    ],
55    "paging": {}
56}

Get post insights
Copy

Get insights for a specifc post.

Sample Input

1{
2    "post_id": "123456789012345",
3    "metric": [
4        "post_impressions",
5        "post_engagements",
6        "post_reactions_by_type_total"
7    ],
8    "date_preset": "last_30d",
9    "period": "day",
10    "show_description_from_api_doc": true,
11    "page_id": "987654321098765"
12}

Sample Output

1{
2    "data": [
3        {
4            "name": "post_impressions",
5            "period": "day",
6            "values": [
7                {
8                    "value": 1250
9                },
10                {
11                    "value": 1500
12                },
13                {
14                    "value": 1800
15                }
16            ],
17            "title": "Post Impressions",
18            "description": "The number of times your post was displayed on screen.",
19            "id": "123456789012345/insights/post_impressions/day"
20        },
21        {
22            "name": "post_engagements",
23            "period": "day",
24            "values": [
25                {
26                    "value": 75
27                },
28                {
29                    "value": 90
30                },
31                {
32                    "value": 120
33                }
34            ],
35            "title": "Post Engagements",
36            "description": "The number of times people engaged with your post through reactions, comments, shares, or clicks.",
37            "id": "123456789012345/insights/post_engagements/day"
38        },
39        {
40            "name": "post_reactions_by_type_total",
41            "period": "day",
42            "values": [
43                {
44                    "value": {
45                        "like": 45,
46                        "love": 15,
47                        "wow": 5,
48                        "haha": 8,
49                        "sorry": 2,
50                        "anger": 0
51                    }
52                },
53                {
54                    "value": {
55                        "like": 55,
56                        "love": 20,
57                        "wow": 7,
58                        "haha": 10,
59                        "sorry": 1,
60                        "anger": 1
61                    }
62                },
63                {
64                    "value": {
65                        "like": 70,
66                        "love": 25,
67                        "wow": 10,
68                        "haha": 12,
69                        "sorry": 3,
70                        "anger": 0
71                    }
72                }
73            ],
74            "title": "Post Reactions by Type",
75            "description": "The number of reactions on your post by type.",
76            "id": "123456789012345/insights/post_reactions_by_type_total/day"
77        }
78    ],
79    "paging": {
80        "previous": "https://graph.facebook.com/v12.0/123456789012345/insights?access_token=...",
81        "next": "https://graph.facebook.com/v12.0/123456789012345/insights?access_token=..."
82    }
83}

Get user
Copy

Get data about the user signed in.

Sample Input

1{}

Sample Output

1{
2    "id": "12345678901234567",
3    "name": "John Doe"
4}

List ad accounts
Copy

List ad accounts associated with current user.

Sample Input

1{
2    "fields": [
3        "account_id",
4        "name",
5        "currency",
6        "balance",
7        "amount_spent"
8    ],
9    "limit": 2
10}

Sample Output

1{
2    "data": [
3        {
4            "id": "act_123456789",
5            "name": "My First Ad Account",
6            "account_id": "123456789",
7            "currency": "USD",
8            "balance": 1000.5,
9            "amount_spent": 5678.9
10        },
11        {
12            "id": "act_987654321",
13            "name": "My Second Ad Account",
14            "account_id": "987654321",
15            "currency": "EUR",
16            "balance": 2500.75,
17            "amount_spent": 1234.56
18        }
19    ],
20    "paging": {
21        "cursors": {
22            "before": "MQZDZD",
23            "after": "MjQZD"
24        }
25    }
26}

List ads in ad account
Copy

List ads in a given ad account.

Sample Input

1{
2    "ad_account_id": "act_123456789",
3    "limit": 10
4}

Sample Output

1{
2    "data": [
3        {
4            "id": "23842613456780123",
5            "name": "Summer Sale Campaign Ad 1"
6        },
7        {
8            "id": "23842613456780124",
9            "name": "New Product Launch Ad"
10        },
11        {
12            "id": "23842613456780125",
13            "name": "Brand Awareness Ad"
14        }
15    ],
16    "paging": {
17        "cursors": {
18            "before": "MAZDZD",
19            "after": "MTYXNJ"
20        }
21    }
22}

List business client ad accounts
Copy

List all client-owned ad accounts.

Sample Input

1{
2    "business_id": "123456789012345",
3    "limit": 10,
4    "after": "QVFIUjZAaWE5MzZAFZAkFYZD"
5}

Sample Output

1{
2    "data": [
3        {
4            "account_id": "987654321098765",
5            "id": "987654321098765"
6        },
7        {
8            "account_id": "876543210987654",
9            "id": "876543210987654"
10        },
11        {
12            "account_id": "765432109876543",
13            "id": "765432109876543"
14        }
15    ],
16    "paging": {
17        "cursors": {
18            "before": "QVFIUmZA1ZAkFYZD",
19            "after": "QVFIUjZAaWE5MzZAFZAkFYZD"
20        }
21    }
22}

List business users
Copy

List all business users associated with this business.

Sample Input

1{
2    "business_id": "123456789",
3    "limit": 3,
4    "after": "QVFIUjZAhbXVfZAm9yZA3NhbWpleGFtcGxlY3Vyc29y"
5}

Sample Output

1{
2    "data": [
3        {
4            "id": "987654321",
5            "name": "John Doe",
6            "business": {
7                "id": "123456789",
8                "name": "Acme Corporation"
9            },
10            "role": "ADMIN"
11        },
12        {
13            "id": "876543210",
14            "name": "Jane Smith",
15            "business": {
16                "id": "123456789",
17                "name": "Acme Corporation"
18            },
19            "role": "EMPLOYEE"
20        },
21        {
22            "id": "765432109",
23            "name": "Bob Johnson",
24            "business": {
25                "id": "123456789",
26                "name": "Acme Corporation"
27            },
28            "role": "EMPLOYEE"
29        }
30    ],
31    "paging": {
32        "cursors": {
33            "before": "QVFIUmV4YW1wbGViZWZvcmVjdXJzb3I=",
34            "after": "QVFIUmV4YW1wbGVhZnRlcmN1cnNvcg=="
35        }
36    }
37}

List campaigns in ad account
Copy

List ad campaigns found in an ad account.

Sample Input

1{
2    "ad_account_id": "act_123456789",
3    "limit": 10,
4    "after": "QVFIUjZAaZAm5nZAXByZAlZAyOUxr"
5}

Sample Output

1{
2    "data": [
3        {
4            "id": "6273849201",
5            "name": "Summer Sale Campaign"
6        },
7        {
8            "id": "6273849202",
9            "name": "New Product Launch"
10        },
11        {
12            "id": "6273849203",
13            "name": "Brand Awareness"
14        }
15    ],
16    "paging": {
17        "cursors": {
18            "before": "QVFIUmZA3ZAnNkZD",
19            "after": "QVFIUjZAaZAm5nZAXByZAlZAyOUxr"
20        }
21    }
22}

List custom audiences
Copy

List custom audience found in an ad account.

Sample Input

1{
2    "ad_account_id": "act_123456789",
3    "limit": 2,
4    "filtering": [
5        {
6            "field": "name",
7            "operator": "CONTAIN",
8            "value": "Loyal Customers"
9        }
10    ],
11    "after": "QVFIUjZAaZAm5BZAXlIOWRyZA2Vr"
12}

Sample Output

1{
2    "data": [
3        {
4            "id": "6789012345",
5            "name": "Loyal Customers 2023",
6            "approximate_count": 50000,
7            "customer_file_source": "USER_PROVIDED_ONLY",
8            "data_source": {
9                "type": "FILE_IMPORTED",
10                "sub_type": "CUSTOM_AUDIENCE",
11                "creation_params": "{\"origin\":\"ui\"}"
12            },
13            "delivery_status": {
14                "code": 200,
15                "description": "Active"
16            },
17            "description": "Customers who have made more than 5 purchases in the last year",
18            "is_value_based": false,
19            "operation_status": {
20                "code": 200,
21                "description": "Normal"
22            },
23            "permission_for_actions": {
24                "can_edit": true,
25                "can_see_insight": true,
26                "can_share": true,
27                "subtype_supports_lookalike": true,
28                "supports_recipient_lookalike": true
29            },
30            "retention_days": 180,
31            "subtype": "CUSTOM",
32            "time_content_updated": 1623456789,
33            "time_created": 1623400000,
34            "time_updated": 1623456789
35        },
36        {
37            "id": "7890123456",
38            "name": "High-Value Loyal Customers",
39            "approximate_count": 10000,
40            "customer_file_source": "USER_PROVIDED_ONLY",
41            "data_source": {
42                "type": "FILE_IMPORTED",
43                "sub_type": "CUSTOM_AUDIENCE",
44                "creation_params": "{\"origin\":\"ui\"}"
45            },
46            "delivery_status": {
47                "code": 200,
48                "description": "Active"
49            },
50            "description": "Loyal customers with average order value > $500",
51            "is_value_based": true,
52            "operation_status": {
53                "code": 200,
54                "description": "Normal"
55            },
56            "permission_for_actions": {
57                "can_edit": true,
58                "can_see_insight": true,
59                "can_share": true,
60                "subtype_supports_lookalike": true,
61                "supports_recipient_lookalike": true
62            },
63            "retention_days": 365,
64            "subtype": "CUSTOM",
65            "time_content_updated": 1623567890,
66            "time_created": 1623500000,
67            "time_updated": 1623567890
68        }
69    ],
70    "paging": {
71        "cursors": {
72            "before": "QVFIUmZA3ZAnNyZA2VyOWRyZA2Vr",
73            "after": "QVFIUjZAaZAm5BZAXlIOWRyZA2Vr"
74        }
75    }
76}

List forms in page
Copy

List leadgen forms owned by a page.

Sample Input

1{
2    "page_id": "123456789012345",
3    "limit": 10,
4    "after": "QVFIUjNfZAm9vZA3NhZAGV2UzZA2ZAkFBZAk1EX01SLXRyZAzZAtOWlpNWVItMzZApZAjRmZAWF5ZAkFBZAk1EX01SLXRyZAzZAtOWlpNWVItMzZApZAjRm"
5}

Sample Output

1{
2    "data": [
3        {
4            "id": "987654321098765",
5            "leadgen_export_csv_url": "https://www.facebook.com/ads/lead_gen/export_csv/?id=987654321098765",
6            "locale": "en_US",
7            "name": "Newsletter Signup",
8            "status": "ACTIVE"
9        },
10        {
11            "id": "876543210987654",
12            "leadgen_export_csv_url": "https://www.facebook.com/ads/lead_gen/export_csv/?id=876543210987654",
13            "locale": "es_ES",
14            "name": "Product Inquiry",
15            "status": "ACTIVE"
16        }
17    ],
18    "paging": {
19        "cursors": {
20            "before": "QVFIUjNfZAm9vZA3NhZAGV2UzZA2ZAkFBZAk1EX01SLXRyZAzZAtOWlpNWVItMzZApZAjRmZAWF5ZAkFBZAk1EX01SLXRyZAzZAtOWlpNWVItMzZApZAjRm",
21            "after": "QVFIUmZAkNDZD1ZD2VyX01SLXRyZAzZAtOWlpNWVItMzZApZAjRmZAWF5ZAkFBZAk1EX01SLXRyZAzZAtOWlpNWVItMzZApZAjRm"
22        }
23    }
24}

List leads from ad
Copy

List leads from a given ad.

Sample Input

1{
2    "ad_id": "23843017891650364",
3    "filtering": [
4        {
5            "operator": "GREATER_THAN",
6            "value": "2023-05-01T00:00:00Z"
7        }
8    ]
9}

Sample Output

1{
2    "data": [
3        {
4            "created_time": "2023-05-02T14:30:45Z",
5            "id": "5678901234567890",
6            "field_data": [
7                {
8                    "name": "full_name",
9                    "values": [
10                        "John Doe"
11                    ]
12                },
13                {
14                    "name": "email",
15                    "values": [
16                        "johndoe@example.com"
17                    ]
18                },
19                {
20                    "name": "phone_number",
21                    "values": [
22                        "+1234567890"
23                    ]
24                }
25            ]
26        },
27        {
28            "created_time": "2023-05-03T09:15:22Z",
29            "id": "6789012345678901",
30            "field_data": [
31                {
32                    "name": "full_name",
33                    "values": [
34                        "Jane Smith"
35                    ]
36                },
37                {
38                    "name": "email",
39                    "values": [
40                        "janesmith@example.com"
41                    ]
42                },
43                {
44                    "name": "phone_number",
45                    "values": [
46                        "+1987654321"
47                    ]
48                }
49            ]
50        }
51    ],
52    "paging": {
53        "cursors": {
54            "before": "MQZDZD",
55            "after": "NXYZAB"
56        }
57    }
58}

List leads from form
Copy

List leads from a given form.

Sample Input

1{
2    "page_id": "123456789012345",
3    "form_id": "987654321098765",
4    "filtering": [
5        {
6            "operator": "GREATER_THAN",
7            "value": "2023-05-01T00:00:00Z"
8        }
9    ],
10    "limit": 10,
11    "after": "QVFIUjZAaZAm5vZAXNETzZA5UEpSMVBnZAzZArZAzZA5T1BZAZAZA"
12}

Sample Output

1{
2    "data": [
3        {
4            "created_time": "2023-05-15T14:30:22+0000",
5            "id": "5678901234567890",
6            "field_data": [
7                {
8                    "name": "full_name",
9                    "values": [
10                        "John Doe"
11                    ]
12                },
13                {
14                    "name": "email",
15                    "values": [
16                        "johndoe@example.com"
17                    ]
18                },
19                {
20                    "name": "phone_number",
21                    "values": [
22                        "+1234567890"
23                    ]
24                }
25            ]
26        },
27        {
28            "created_time": "2023-05-14T09:45:11+0000",
29            "id": "6789012345678901",
30            "field_data": [
31                {
32                    "name": "full_name",
33                    "values": [
34                        "Jane Smith"
35                    ]
36                },
37                {
38                    "name": "email",
39                    "values": [
40                        "janesmith@example.com"
41                    ]
42                },
43                {
44                    "name": "phone_number",
45                    "values": [
46                        "+9876543210"
47                    ]
48                }
49            ]
50        }
51    ],
52    "paging": {
53        "cursors": {
54            "before": "QVFIUmZA1ZAjRfZAk1CTmFB",
55            "after": "QVFIUjZAaZAm5vZAXNETzZA5UEpSMVBnZAzZArZAzZA5T1BZAZAZA"
56        }
57    }
58}

List pages managed
Copy

List the pages managed by the current user.

Sample Input

1{
2    "limit": 2,
3    "after": "QVFIUjZAaZAnZAyOVpnZAzZAxZAXNERUx1TjZA5UVRyMEpBRTlIOXZAGZAUlCNVRRZA2x2TjZAzOWVQZD"
4}

Sample Output

1{
2    "data": [
3        {
4            "id": "123456789012345",
5            "name": "My Business Page"
6        },
7        {
8            "id": "234567890123456",
9            "name": "My Personal Brand"
10        }
11    ],
12    "paging": {
13        "cursors": {
14            "before": "QVFIUmZA3ZA1ZAyOVpnZAzZAxZAXNERUx1TjZA5UVRyMEpBRTlIOXZAGZAUlCNVRRZA2x2TjZAzOWVQZD",
15            "after": "QVFIUjZAaZAnZAyOVpnZAzZAxZAXNERUx1TjZA5UVRyMEpBRTlIOXZAGZAUlCNVRRZA2x2TjZAzOWVRZD"
16        }
17    }
18}

List pending users
Copy

List all users invited to access this business, who have not yet accepted their invitation.

Sample Input

1{
2    "business_id": "123456789",
3    "limit": 10,
4    "email_address": "john.doe@example.com",
5    "after": "QVFIUjNfZAm5vZA3ZAZD"
6}

Sample Output

1{
2    "data": [
3        {
4            "id": "987654321",
5            "role": "ADMIN",
6            "email": "john.doe@example.com",
7            "invite_link": "https://www.facebook.com/business_locations/?business_id=123456789&invite_id=987654321",
8            "status": "PENDING"
9        },
10        {
11            "id": "876543210",
12            "role": "EMPLOYEE",
13            "email": "jane.smith@example.com",
14            "invite_link": "https://www.facebook.com/business_locations/?business_id=123456789&invite_id=876543210",
15            "status": "PENDING"
16        }
17    ],
18    "paging": {
19        "cursors": {
20            "before": "QVFIUjNfZAm5vZA3ZAZD",
21            "after": "QVFIUmZA1X0NUZD"
22        }
23    }
24}

List posts on page
Copy

Retrieve a list of posts associated with a specific page.

Sample Input

1{
2    "page_id": "123456789012345",
3    "limit": 2,
4    "after": "QVFIUjNfZAm5nZAXVpZAGVyX2x0UzZA2ZAzZAxZAjZAyZAWRkZD"
5}

Sample Output

1{
2    "header": {},
3    "body": {
4        "data": [
5            {
6                "created_time": "2023-05-15T14:30:00+0000",
7                "from": {
8                    "name": "My Business Page",
9                    "id": "123456789012345"
10                },
11                "id": "123456789012345_987654321098765",
12                "message": "Check out our latest product launch!",
13                "is_published": true,
14                "is_hidden": false,
15                "status_type": "mobile_status_update",
16                "updated_time": "2023-05-15T14:30:00+0000"
17            },
18            {
19                "created_time": "2023-05-14T10:15:00+0000",
20                "from": {
21                    "name": "My Business Page",
22                    "id": "123456789012345"
23                },
24                "id": "123456789012345_876543210987654",
25                "message": "Don't miss our upcoming sale this weekend!",
26                "is_published": true,
27                "is_hidden": false,
28                "status_type": "mobile_status_update",
29                "updated_time": "2023-05-14T10:15:00+0000"
30            }
31        ],
32        "paging": {
33            "cursors": {
34                "before": "QVFIUmZAZA3ZD1ZD1ZD1ZD1ZD1ZD1ZD1ZD1ZD1ZD1ZD1ZD1ZD",
35                "after": "QVFIUjNfZAm5nZAXVpZAGVyX2x0UzZA2ZAzZAxZAjZAyZAWRkZD"
36            },
37            "next": "https://graph.facebook.com/v12.0/123456789012345/posts?limit=2&after=QVFIUjNfZAm5nZAXVpZAGVyX2x0UzZA2ZAzZAxZAjZAyZAWRkZD"
38        }
39    }
40}

List saved audiences
Copy

List all saved audiences.

Sample Input

1{
2    "ad_account_id": "act_123456789",
3    "limit": 10,
4    "filtering": [
5        {
6            "field": "name",
7            "operator": "CONTAIN",
8            "value": "Summer"
9        }
10    ],
11    "after": "QVFIUjZAaWE5MzZAFZAkF6WkN0UzZA5R1JCN3RoZAk1SZA2x2TXByZAWRhOUlKZAVhCZAVhB"
12}

Sample Output

1{
2    "data": [
3        {
4            "id": "6123456789012",
5            "name": "Summer Sale Audience"
6        },
7        {
8            "id": "6234567890123",
9            "name": "Summer Fashion Enthusiasts"
10        },
11        {
12            "id": "6345678901234",
13            "name": "Summer Travel Planners"
14        }
15    ],
16    "paging": {
17        "cursors": {
18            "before": "QVFIUmZA3ZA3BhZAG5yZA2x2TXByZAWRhOUlKZAVhCZAVhB",
19            "after": "QVFIUjZAaWE5MzZAFZAkF6WkN0UzZA5R1JCN3RoZAk1SZA2x2TXByZAWRhOUlKZAVhCZAVhB"
20        }
21    }
22}

Targeting search
Copy

Retrieve target audiences for your ads that match your search query.

Sample Input

1{
2    "ad_account_id": "123456789",
3    "q": "sports fans",
4    "limit_type": "interests",
5    "locale": "en_US",
6    "limit": "5"
7}

Sample Output

1{
2    "data": [
3        {
4            "id": "6003107902433",
5            "name": "Sports",
6            "type": "interest",
7            "path": [
8                "Interests",
9                "Sports"
10            ],
11            "audience_size": 1500000000
12        },
13        {
14            "id": "6003139266461",
15            "name": "Football",
16            "type": "interest",
17            "path": [
18                "Interests",
19                "Sports",
20                "Football"
21            ],
22            "audience_size": 800000000
23        },
24        {
25            "id": "6003139281461",
26            "name": "Basketball",
27            "type": "interest",
28            "path": [
29                "Interests",
30                "Sports",
31                "Basketball"
32            ],
33            "audience_size": 600000000
34        },
35        {
36            "id": "6003139290861",
37            "name": "Soccer",
38            "type": "interest",
39            "path": [
40                "Interests",
41                "Sports",
42                "Soccer"
43            ],
44            "audience_size": 700000000
45        },
46        {
47            "id": "6003139302661",
48            "name": "Tennis",
49            "type": "interest",
50            "path": [
51                "Interests",
52                "Sports",
53                "Tennis"
54            ],
55            "audience_size": 300000000
56        }
57    ]
58}

Update custom audience
Copy

Update a custom audience with a new population.

Sample Input

1{
2    "custom_audience_id": "23842001234567",
3    "app_ids": [
4        "123456789",
5        "987654321"
6    ],
7    "audience_members": {
8        "audience_member_list": [
9            {
10                "email": "john.doe@example.com",
11                "first_name": "John",
12                "last_name": "Doe",
13                "country_code": "us",
14                "city": "New York",
15                "us_state": "ny",
16                "zip_code": "10001",
17                "birth_year": "1985",
18                "birth_month": "06",
19                "birth_day": "15",
20                "gender": "m",
21                "phone": "+12125551234"
22            },
23            {
24                "email": "jane.smith@example.com",
25                "first_name": "Jane",
26                "last_name": "Smith",
27                "country_code": "ca",
28                "city": "Toronto",
29                "birth_year": "1990",
30                "birth_month": "09",
31                "birth_day": "22",
32                "gender": "f",
33                "phone": "+14165557890"
34            }
35        ]
36    }
37}

Sample Output

1{
2    "id": "6070345123456",
3    "audience_id": "23842001234567",
4    "session_id": "1234567890abcdef",
5    "num_received": 2,
6    "num_invalid_entries": 0,
7    "invalid_entry_samples": {}
8}

Update post
Copy

Update a post.

Sample Input

1{
2    "post_id": "123456789012345",
3    "message": "Updated message: Check out our latest product launch!",
4    "publish": true,
5    "scheduled_publish_time": "2023-06-15T14:30:00Z"
6}

Sample Output

1{
2    "success": true
3}

DDL operations
Copy

List ad accounts (DDL)
Copy

Note that DDL operations can only be called directly by Connectors API, or when using CustomJS in the Embedded solution editor for e.g. DDL-dependent data mapping

Sample Input

1{}

Sample Output

1[
2    {
3        "id": "act_123456789",
4        "name": "My Ad Account",
5        "account_id": "123456789",
6        "account_status": 1,
7        "amount_spent": "1000.00",
8        "balance": "5000.00",
9        "currency": "USD",
10        "timezone_name": "America/Los_Angeles",
11        "timezone_offset_hours_utc": -7,
12        "business_name": "My Business",
13        "business_id": "987654321",
14        "created_time": "2023-01-15T10:30:00-0700",
15        "disable_reason": 0
16    },
17    {
18        "id": "act_987654321",
19        "name": "Secondary Ad Account",
20        "account_id": "987654321",
21        "account_status": 1,
22        "amount_spent": "500.00",
23        "balance": "2500.00",
24        "currency": "EUR",
25        "timezone_name": "Europe/London",
26        "timezone_offset_hours_utc": 1,
27        "business_name": "European Branch",
28        "business_id": "123123123",
29        "created_time": "2023-03-20T14:45:00+0100",
30        "disable_reason": 0
31    }
32]

List custom audience ad accounts (DDL)
Copy

Note that DDL operations can only be called directly by Connectors API, or when using CustomJS in the Embedded solution editor for e.g. DDL-dependent data mapping

Sample Input

1{}

Sample Output

1{
2    "data": [
3        {
4            "id": "123456789",
5            "name": "Main Ad Account",
6            "account_id": "987654321",
7            "account_status": "ACTIVE",
8            "currency": "USD",
9            "timezone_name": "America/Los_Angeles",
10            "business_name": "My Business",
11            "business_id": "1122334455"
12        },
13        {
14            "id": "234567890",
15            "name": "Secondary Ad Account",
16            "account_id": "876543210",
17            "account_status": "ACTIVE",
18            "currency": "EUR",
19            "timezone_name": "Europe/London",
20            "business_name": "My Other Business",
21            "business_id": "2233445566"
22        }
23    ],
24    "paging": {
25        "cursors": {
26            "before": "MAZDZD",
27            "after": "MjQZD"
28        }
29    }
30}

Operations (sample payloads)

Main operationsCopy

Create custom audienceCopy

Create postCopy

Delete audience membersCopy

Delete custom audienceCopy

Get adCopy

Get ad accountCopy

Get ad account insightsCopy

Get ad insightsCopy

Get adsetCopy

Get adset insightsCopy

Get audienceCopy

Get business userCopy

Get campaignCopy

Get campaign insightsCopy

Get leadCopy

Get page insightsCopy

Get post insightsCopy

Get userCopy

List ad accountsCopy

List ads in ad accountCopy

List business client ad accountsCopy

List business usersCopy

List campaigns in ad accountCopy

List custom audiencesCopy

List forms in pageCopy

List leads from adCopy

List leads from formCopy

List pages managedCopy

List pending usersCopy

List posts on pageCopy

List saved audiencesCopy

Targeting searchCopy

Update custom audienceCopy

Update postCopy

DDL operationsCopy

List ad accounts (DDL)Copy

List custom audience ad accounts (DDL)Copy

Overview

Operations

Main operations
Copy

Create custom audience
Copy

Create post
Copy

Delete audience members
Copy

Delete custom audience
Copy

Get ad
Copy

Get ad account
Copy

Get ad account insights
Copy

Get ad insights
Copy

Get adset
Copy

Get adset insights
Copy

Get audience
Copy

Get business user
Copy

Get campaign
Copy

Get campaign insights
Copy

Get lead
Copy

Get page insights
Copy

Get post insights
Copy

Get user
Copy

List ad accounts
Copy

List ads in ad account
Copy

List business client ad accounts
Copy

List business users
Copy

List campaigns in ad account
Copy

List custom audiences
Copy

List forms in page
Copy

List leads from ad
Copy

List leads from form
Copy

List pages managed
Copy

List pending users
Copy

List posts on page
Copy

List saved audiences
Copy

Targeting search
Copy

Update custom audience
Copy

Update post
Copy

DDL operations
Copy

List ad accounts (DDL)
Copy

List custom audience ad accounts (DDL)
Copy