Facebook Ads Connector ReferenceΒΆ The following operations allow you to work with the Facebook Ads API. Click an operation name to see parameter details and samples on how to use it. Initialize the connectorΒΆ To use the Facebook Ads connector, first create the connection with your configuration. When calling a Facebook Ads operation, ensure the connection is referenced using the configKey attribute. initThe init operation initializes the connection to Facebook Ads API. Parameter Name Description Required name Unique name to identify the connection by. Yes base The service root URL. The default value is https://graph.facebook.com/v20.0. Yes accessToken The access token to authenticate the request. Yes Sample configuration <facebookAds.init> <connectionType>facebookAds</connectionType> <name>FB_CONN_1</name> <base>https://graph.facebook.com/v20.0</base> <accessToken>REPLACE_WITH_ACCESS_TOKEN</accessToken> </facebookAds.init> OperationsΒΆ createCampaignThe createCampaign operation creates a campaign. Parameter Name Description Required adAccountId ID of the ad account. Yes properties A JSON object containing the campaign properties. See the Campaign parameters documentation for all the available properties. Yes responseVariable Variable name to store the response payload. Yes overwriteBody Replace the current message payload with the operation response. No (Default: false) Sample configuration <facebookAds.createCampaign configKey="FB_CONN_1"> <adAccountId>{json-eval($.account_id)}</adAccountId> <properties>{json-eval($.properties)}</properties> <responseVariable>campaignResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.createCampaign> Sample request { "account_id":"123123123", "properties": { "name": "New Furniture Campaign", "objective": "OUTCOME_TRAFFIC", "status": "PAUSED", "special_ad_categories": ["EMPLOYMENT"] } } getCampaignsThe getCampaigns operation returns campaigns under this ad account. Parameter Name Description Required adAccountId ID of the ad account. Yes datePreset Predefined date range used to aggregate insights metrics. No effectiveStatus Effective status for the campaigns. No isCompleted If true, we return completed campaigns. No timeRange Date range used to aggregate insights metrics. No fields Fields of the campaign that the response should contain. See the Fields documentation for a list of all available fields. No responseVariable Variable name to store the response payload. Yes overwriteBody Replace the current message payload with the operation response. No (Default: false) Sample configuration <facebookAds.getCampaigns configKey="FB_CONN_1"> <adAccountId>{json-eval($.account_id)}</adAccountId> <fields>{json-eval($.fields)}</fields> <effectiveStatus>{json-eval($.status)}</effectiveStatus> <isCompleted>{json-eval($.is_completed)}</isCompleted> <responseVariable>campaignsResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.getCampaigns> Sample request { "account_id": "123123123", "fields": "id,name", "is_completed": true, "status": [ "PAUSED" ] } updateCampaignThe updateCampaign operation updates a campaign. Parameter Name Description Required campaignId ID of the campaign. Yes properties A JSON object containing the campaign properties. See the Campaign parameters documentation for all the available properties. Yes responseVariable Variable name to store the response payload. Yes overwriteBody Replace the current message payload with the operation response. No (Default: false) Sample configuration <facebookAds.updateCampaign configKey="FB_CONN_1"> <campaignId>{json-eval($.campaign_id)}</campaignId> <properties>{json-eval($.properties)}</properties> <responseVariable>updateResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.updateCampaign> Sample request { "campaign_id": "123123123", "properties": { "name": "New Furniture Likes Campaign 2", "objective": "OUTCOME_ENGAGEMENT" } } dissociateCampaignThe dissociateCampaign operation dissociate a campaign from an ad account. Parameter Name Description Required adAccountId ID of the ad account. Yes deleteStrategy Delete strategy. Possible values DELETE_ANY, DELETE_OLDEST or DELETE_ARCHIVED_BEFORE. Yes beforeDate Set a before date to delete campaigns before this date. No objectCount Object count. No responseVariable Variable name to store the response payload. Yes overwriteBody Replace the current message payload with the operation response. No (Default: false) Sample configuration <facebookAds.dissociateCampaign configKey="FB_CONN_1"> <adAccountId>{json-eval($.account_id)}</adAccountId> <deleteStrategy>{json-eval($.strategy)}</deleteStrategy> <objectCount>{json-eval($.count)}</objectCount> <responseVariable>dissociateResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.dissociateCampaign> Sample request { "account_id": "123123123", "strategy": "DELETE_OLDEST", "count": 1 } deleteCampaignThe deleteCampaign operation deletes a campaign. Parameter Name Description Required campaignId ID of the campaign. Yes responseVariable Variable name to store the response payload. Yes overwriteBody Replace the current message payload with the operation response. No (Default: false) Sample configuration <facebookAds.deleteCampaign configKey="FB_CONN_1"> <campaignId>{json-eval($.campaign_id)}</campaignId> <responseVariable>deleteResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.deleteCampaign> Sample request { "campaign_id": "123123123" } createAdSetThe createAdSet operation creates an ad set. Parameter Name Description Required adAccountId ID of the ad account. Yes properties A JSON object containing the adset properties. See the Ad set parameters documentation for all the available properties. Yes responseVariable Variable name to store the response payload. Yes overwriteBody Replace the current message payload with the operation response. No (Default: false) Sample configuration <facebookAds.createAdSet configKey="FB_CONN_1"> <adAccountId>{json-eval($.account_id)}</adAccountId> <properties>{json-eval($.properties)}</properties> <responseVariable>adSetResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.createAdSet> Sample request { "account_id": "123123123", "properties": { "name": "New Furniture Ad set", "status": "PAUSED", "campaign_id": "123123123", "daily_budget": "10000", "bid_amount": "300", "billing_event": "IMPRESSIONS", "targeting": { "facebook_positions": [ "feed" ], "geo_locations": { "countries": [ "US" ] } } } } getAdSetsThe getAdSets operation returns all ad sets from one ad account. Parameter Name Description Required adAccountId ID of the ad account. Yes datePreset Predefined date range used to aggregate insights metrics. No timeRange Time Range. Note if the time range is invalid, it will be ignored. No fields Fields of the ad set that the response should contain. See the Fields documentation for a list of all available fields. No responseVariable Variable name to store the response payload. Yes overwriteBody Replace the current message payload with the operation response. No (Default: false) Sample configuration <facebookAds.getAdSets configKey="FB_CONN_1"> <adAccountId>{json-eval($.account_id)}</adAccountId> <fields>{json-eval($.fields)}</fields> <responseVariable>adSetsResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.getAdSets> Sample request { "account_id":"123123123", "fields":"id,name,status,campaign" } getAdSetThe getAdSet operation return data related to an ad set. Parameter Name Description Required adSetId ID of the ad set. Yes datePreset Predefined date range used to aggregate insights metrics. No timeRange Time Range. Note if time range is invalid, it will be ignored. No fields Fields of the ad set that the response should contain. See the Fields documentation for a list of all available fields. No responseVariable Variable name to store the response payload. Yes overwriteBody Replace the current message payload with the operation response. No (Default: false) Sample configuration <facebookAds.getAdSet configKey="FB_CONN_1"> <adSetId>{json-eval($.ad_set_id)}</adSetId> <fields>{json-eval($.fields)}</fields> <responseVariable>adSetResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.getAdSet> Sample request { "ad_set_id":"456456456", "fields":"name, targeting" } updateAdSetThe updateAdSet operation updates an ad set. Parameter Name Description Required adSetId ID of the ad set. Yes properties A JSON object containing the adset properties. See the Ad set parameters documentation for all the available properties. Yes responseVariable Variable name to store the response payload. Yes overwriteBody Replace the current message payload with the operation response. No (Default: false) Sample configuration <facebookAds.updateAdSet configKey="FB_CONN_1"> <adSetId>{json-eval($.ad_set_id)}</adSetId> <properties>{json-eval($.properties)}</properties> <responseVariable>updateResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.updateAdSet> Sample request { "ad_set_id": "123123123", "properties": { "name": "New Furniture Ad set Updated", "status": "PAUSED", "bid_amount": "500" } } deleteAdSetThe deleteAdSet operation deletes an ad set. Parameter Name Description Required adSetId ID of the ad set. Yes responseVariable Variable name to store the response payload. Yes overwriteBody Replace the current message payload with the operation response. No (Default: false) Sample configuration <facebookAds.deleteAdSet configKey="FB_CONN_1"> <adSetId>{json-eval($.ad_set_id)}</adSetId> <responseVariable>deleteResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.deleteAdSet> Sample request { "ad_set_id": "123123123" } createAdThe createAd operation creates an ad. Parameter Name Description Required adAccountId ID of the ad account. Yes properties A JSON object containing the ad properties. See the Ad parameters documentation for all the available properties. Yes responseVariable Variable name to store the response payload. Yes overwriteBody Replace the current message payload with the operation response. No (Default: false) Sample configuration <facebookAds.createAd configKey="FB_CONN_1"> <adAccountId>{json-eval($.account_id)}</adAccountId> <properties>{json-eval($.properties)}</properties> <responseVariable>adResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.createAd> Sample request { "account_id": "123123123", "properties": { "name": "New Furniture Ad", "status": "PAUSED", "adset_id": "456456456", "creative": { "creative_id": "789789789" } } } getAdsThe getAds operation returns ads under this ad account. Parameter Name Description Required adAccountId ID of the ad account. Yes datePreset Predefined date range used to aggregate insights metrics. No effectiveStatus Filter ads by effective status. No updatedSince Time since the ad has been updated. No timeRange Date range used to aggregate insights metrics. No fields Fields of the ad that the response should contain. See the Fields documentation for a list of all available fields. No responseVariable Variable name to store the response payload. Yes overwriteBody Replace the current message payload with the operation response. No (Default: false) Sample configuration <facebookAds.getAds configKey="FB_CONN_1"> <adAccountId>{json-eval($.account_id)}</adAccountId> <fields>{json-eval($.fields)}</fields> <effectiveStatus>{json-eval($.status)}</effectiveStatus> <updatedSince>{json-eval($.updated_since)}</updatedSince> <responseVariable>adsResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.getAds> Sample request { "account_id": "123123123", "fields": "id,name,status,ad_active_time", "status": [ "ACTIVE" ], "updated_since": 34564356 } getAdThe getAd operation returns data of an ad. Parameter Name Description Required adId ID of the ad. Yes datePreset Predefined date range used to aggregate insights metrics. No timeRange Date range used to aggregate insights metrics. No fields Fields of the ad that the response should contain. See the Fields documentation for a list of all available fields. No responseVariable Variable name to store the response payload. Yes overwriteBody Replace the current message payload with the operation response. No (Default: false) Sample configuration <facebookAds.getAd configKey="FB_CONN_1"> <adId>{json-eval($.ad_id)}</adId> <fields>{json-eval($.fields)}</fields> <responseVariable>adResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.getAd> Sample request { "ad_id":"789789789", "fields":"id,name,status,campaign,ad_active_time" } updateAdThe updateAd operation updates an ad. Parameter Name Description Required adId ID of the ad. Yes properties A JSON object containing the ad properties. See the Update Limitations documentation for all the available properties. Yes responseVariable Variable name to store the response payload. Yes overwriteBody Replace the current message payload with the operation response. No (Default: false) Sample configuration <facebookAds.updateAd configKey="FB_CONN_1"> <adId>{json-eval($.ad_id)}</adId> <properties>{json-eval($.properties)}</properties> <responseVariable>updateResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.updateAd> Sample request { "ad_id": "456456456", "properties": { "name": "New Furniture Ad 2", "status": "PAUSED" } } deleteAdThe deleteAd operation deletes an ad. Parameter Name Description Required adId ID of the ad. Yes responseVariable Variable name to store the response payload. Yes overwriteBody Replace the current message payload with the operation response. No (Default: false) Sample configuration <facebookAds.deleteAd configKey="FB_CONN_1"> <adId>{json-eval($.ad_id)}</adId> <responseVariable>deleteResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.deleteAd> Sample request { "ad_id": "456456456" } createCustomAudienceThe createCustomAudience operation creates a custom audience. Parameter Name Description Required adAccountId ID of the ad account. Yes properties Custom audience properties. Yes responseVariable Variable name to store the response payload. Yes overwriteBody Replace the current message payload with the operation response. No (Default: false) Sample configuration <facebookAds.createCustomAudience configKey="FB_CONN_1"> <adId>{json-eval($.ad_id)}</adId> <properties>{json-eval($.properties)}</properties> <responseVariable>audienceResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.createCustomAudience> Sample request { "ad_id": "456456456", "properties": { "name": "My Custom Audience", "subtype": "CUSTOM", "description": "Audience based on website traffic", "customer_file_source": "USER_PROVIDED_ONLY" } } createAdCreativeThe createAdCreative operation creates an ad creative. Parameter Name Description Required adAccountId ID of the ad account. Yes properties Ad creative properties. Yes responseVariable Variable name to store the response payload. Yes overwriteBody Replace the current message payload with the operation response. No (Default: false) Sample configuration <facebookAds.createAdCreative configKey="FB_CONN_1"> <adId>{json-eval($.ad_id)}</adId> <properties>{json-eval($.properties)}</properties> <responseVariable>creativeResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.createAdCreative> Sample request { "ad_id": "456456456", "properties": { "name": "My Ad Creative", "object_story_spec": { "page_id": "465229476789834", "link_data": { "description": "My ad creative", "image_hash": "f2cafafae01fc9201c8d2e70687dhk675Ddsac", "link": "https://sample.com/", "message": "Check out my website!", "name": "headline", "call_to_action": { "type": "LEARN_MORE", "value": { "link": "https://sample.com/", "link_caption": "" } } } }, "degrees_of_freedom_spec": { "creative_features_spec": { "standard_enhancements": { "enroll_status": "OPT_OUT" } } } } } updateCustomAudienceThe updateCustomAudience operation updates a custom audience. Parameter Name Description Required customAudienceId ID of the custom audience. Yes properties Custom audience update properties. Yes responseVariable Variable name to store the response payload. Yes overwriteBody Replace the current message payload with the operation response. No (Default: false) Sample configuration <facebookAds.updateCustomAudience configKey="FB_CONN_1"> <customAudienceId>{json-eval($.audience_id)}</customAudienceId> <properties>{json-eval($.properties)}</properties> <responseVariable>updateResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.updateCustomAudience> Sample request { "audience_id": "456456456", "properties": { "name": "My Custom Audience Update", "subtype": "CUSTOM", "description": "Audience based on website traffic", } } addUsersToAudienceThe addUsersToAudience operation adds users to a custom audience. Parameter Name Description Required customAudienceId ID of the custom audience. Yes properties Properties of the users to be added to the audience. Yes inputStructure Structure of the user data to be added. No responseVariable Variable name to store the response payload. Yes overwriteBody Replace the current message payload with the operation response. No (Default: false) Sample configurations for Facebook API compatible input <facebookAds.addUsersToAudience configKey="FB_CONN_1"> <customAudienceId>{json-eval($.audience_id)}</customAudienceId> <properties>{json-eval($.properties)}</properties> <responseVariable>audienceUpdateResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.addUsersToAudience> <facebookAds.addUsersToAudience configKey="FB_CONN_1"> <customAudienceId>{json-eval($.audience_id)}</customAudienceId> <properties>{json-eval($.properties)}</properties> <inputStructure>FACEBOOK_API_COMPATIBLE</inputStructure> <responseVariable>audienceUpdateResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.addUsersToAudience> Sample request for Facebook API compatible input { "audience_id": "456456456", "properties": { "payload": { "schema": [ "COUNTRY", "EMAIL", "FN", "GEN", "LN", "MADID", "PHONE" ], "data": [ [ "79adb2a2fce5c6ba215fe5f27f532d4e7edbac4b6a5e09e1ef3a08084a904621", "23b9cb38c8e9c75a466a349eec16aff2c3eabc707cf57432a872aab7e532d069", "b54f08623ae4039f55bcecba4961037fb4513d2ba9cb2b0667c5db970ac94911", "252f10c83610ebca1a059c0bae8255eba2f95be4d1d7bcfa89d7248a82d9f111", "d07227456ed0f3a3ca01456ee769b4662c1c679d754465b44c93b075fea751cd", "aece52e7-03ee-455a-b3c4-e57283966239", "c7e1a5948418c64b472abbe6a7b443ec83c4e31573874d600de828f89dd71339" ] ] } } } Sample configurations for JSON array input <facebookAds.addUsersToAudience configKey="FB_CONN_1"> <customAudienceId>{json-eval($.audience_id)}</customAudienceId> <properties>{json-eval($.properties)}</properties> <inputStructure>JSON_ARRAY</inputStructure> <responseVariable>audienceUpdateResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.addUsersToAudience> Sample request for JSON array input { "audience_id": "456456456", "properties": [ { "email": "[email protected]", "phone": "1-(650)-561-5622", "madid": "aece52e7-03ee-455a-b3c4-e57283966239", "fn": "Elizabeth", "ln": "Olsen", "zip": "94046", "ct": "Menlo Park", "st": "CA", "country": "US", "dob": "10\/21\/68", "doby": 1968, "gen": "F", "age": 48, "uid": 1234567890 }, { "email": "[email protected]", "phone": "1-(212) 736-3100", "madid": "BEBE52E7-03EE-455A-B3C4-E57283966239", "fn": "Andrew", "ln": "Jamison", "zip": "10118", "ct": "New York", "st": "NY", "country": "US", "dob": "10\/17\/78", "doby": 1978, "gen": "M", "age": 38, "uid": 1443637309 } ] } removeUsersFromAudienceThe removeUsersFromAudience operation removes users from a custom audience. Parameter Name Description Required customAudienceId ID of the custom audience. Yes properties Properties of the users to be removed from the audience. Yes inputStructure Structure of the user data to be removed. No responseVariable Variable name to store the response payload. Yes overwriteBody Replace the current message payload with the operation response. No (Default: false) Sample configurations for Facebook API compatible input <facebookAds.removeUsersFromAudience configKey="FB_CONN_1"> <customAudienceId>{json-eval($.audience_id)}</customAudienceId> <properties>{json-eval($.properties)}</properties> <responseVariable>audienceUpdateResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.removeUsersFromAudience> <facebookAds.removeUsersFromAudience configKey="FB_CONN_1"> <customAudienceId>{json-eval($.audience_id)}</customAudienceId> <properties>{json-eval($.properties)}</properties> <inputStructure>FACEBOOK_API_COMPATIBLE</inputStructure> <responseVariable>audienceUpdateResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.removeUsersFromAudience> Sample request for Facebook API compatible input { "audience_id": "456456456", "properties": { "payload": { "schema": [ "COUNTRY", "EMAIL", "FN", "GEN", "LN", "MADID", "PHONE" ], "data": [ [ "79adb2a2fce5c6ba215fe5f27f532d4e7edbac4b6a5e09e1ef3a08084a904621", "23b9cb38c8e9c75a466a349eec16aff2c3eabc707cf57432a872aab7e532d069", "b54f08623ae4039f55bcecba4961037fb4513d2ba9cb2b0667c5db970ac94911", "252f10c83610ebca1a059c0bae8255eba2f95be4d1d7bcfa89d7248a82d9f111", "d07227456ed0f3a3ca01456ee769b4662c1c679d754465b44c93b075fea751cd", "aece52e7-03ee-455a-b3c4-e57283966239", "c7e1a5948418c64b472abbe6a7b443ec83c4e31573874d600de828f89dd71339" ] ] } } } Sample configurations for JSON array input <facebookAds.removeUsersFromAudience configKey="FB_CONN_1"> <customAudienceId>{json-eval($.audience_id)}</customAudienceId> <properties>{json-eval($.properties)}</properties> <inputStructure>JSON_ARRAY</inputStructure> <responseVariable>audienceUpdateResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.removeUsersFromAudience> Sample request for JSON array input { "audience_id": "456456456", "properties": [ { "email": "[email protected]", "phone": "1-(650)-561-5622", "madid": "aece52e7-03ee-455a-b3c4-e57283966239", "fn": "Elizabeth", "ln": "Olsen", "zip": "94046", "ct": "Menlo Park", "st": "CA", "country": "US", "dob": "10\/21\/68", "doby": 1968, "gen": "F", "age": 48, "uid": 1234567890 }, { "email": "[email protected]", "phone": "1-(212) 736-3100", "madid": "BEBE52E7-03EE-455A-B3C4-E57283966239", "fn": "Andrew", "ln": "Jamison", "zip": "10118", "ct": "New York", "st": "NY", "country": "US", "dob": "10\/17\/78", "doby": 1978, "gen": "M", "age": 38, "uid": 1443637309 } ] } getCustomAudiencesThe getCustomAudiences operation retrieves all custom audiences. Provide a value for the filterByName parameter to retrieve specific audiences by name. Parameter Name Description Required adAccountId ID of the ad account. Yes filterByName Provide a name to filter and retrieve specific audiences. No responseVariable Variable name to store the response payload. Yes overwriteBody Replace the current message payload with the operation response. No (Default: false) Sample configuration <facebookAds.getCustomAudiences configKey="FB_CONN_1"> <adAccountId>{json-eval($.ad_account_id)}</adAccountId> <filterByName>{json-eval($.filter_name)}</filterByName> <responseVariable>audiencesResponse</responseVariable> <overwriteBody>false</overwriteBody> </facebookAds.getCustomAudiences> Sample request Retrieve all the custom audiences. { "ad_account_id": "123123123" } Retrieve specific audiences by name. { "ad_account_id": "123123123", "filter_name": "Custom Audience With Users" } Error codes related to Facebook Ads ConnectorΒΆ The connector may encounter errors during operation execution. When an error occurs, the ERROR_MESSAGE property will contain detailed information about the error. You can handle these errors using a Fault Sequence in your integration. For more information, see Using Fault Sequences. Error code Description 701101 General error. 701102 Invalid configuration error.