Skip to content

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.

init

The 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

createCampaign

The 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

Sample configuration

<facebookAds.createCampaign configKey="FB_CONN_1">
    <adAccountId>{json-eval($.account_id)}</adAccountId>
    <properties>{json-eval($.properties)}</properties>
</facebookAds.createCampaign>

Sample request

{
    "account_id":"123123123",
    "properties": {
        "name": "New Furniture Campaign",
        "objective": "OUTCOME_TRAFFIC",
        "status": "PAUSED",
        "special_ad_categories": ["EMPLOYMENT"]
    }
}
getCampaigns

The 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

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>
</facebookAds.getCampaigns>

Sample request

{
    "account_id": "123123123",
    "fields": "id,name",
    "is_completed": true,
    "status": [
        "PAUSED"
    ]
}
updateCampaign

The 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

Sample configuration

<facebookAds.updateCampaign configKey="FB_CONN_1">
    <campaignId>{json-eval($.campaign_id)}</campaignId>
    <properties>{json-eval($.properties)}</properties>
</facebookAds.updateCampaign>

Sample request

{
    "campaign_id": "123123123",
    "properties": {
        "name": "New Furniture Likes Campaign 2",
        "objective": "OUTCOME_ENGAGEMENT"
    }
}
dissociateCampaign

The 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

Sample configuration

<facebookAds.dissociateCampaign configKey="FB_CONN_1">
    <adAccountId>{json-eval($.account_id)}</adAccountId>
    <deleteStrategy>{json-eval($.strategy)}</deleteStrategy>
    <objectCount>{json-eval($.count)}</objectCount>
</facebookAds.dissociateCampaign>

Sample request

{
    "account_id": "123123123",
    "strategy": "DELETE_OLDEST",
    "count": 1
}
deleteCampaign

The deleteCampaign operation deletes a campaign.

Parameter Name Description Required
campaignId ID of the campaign. Yes

Sample configuration

<facebookAds.deleteCampaign configKey="FB_CONN_1">
    <campaignId>{json-eval($.campaign_id)}</campaignId>
</facebookAds.deleteCampaign>

Sample request

{
    "campaign_id": "123123123"
}
createAdSet

The 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

Sample configuration

<facebookAds.createAdSet configKey="FB_CONN_1">
    <adAccountId>{json-eval($.account_id)}</adAccountId>
    <properties>{json-eval($.properties)}</properties>
</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"
                ]
            }
        }
    }
}
getAdSets

The 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

Sample configuration

<facebookAds.getAdSets configKey="FB_CONN_1">
    <adAccountId>{json-eval($.account_id)}</adAccountId>
    <fields>{json-eval($.fields)}</fields>
</facebookAds.getAdSets>

Sample request

{
    "account_id":"123123123",
    "fields":"id,name,status,campaign"
}
getAdSet

The 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

Sample configuration

<facebookAds.getAdSet configKey="FB_CONN_1">
    <adSetId>{json-eval($.ad_set_id)}</adSetId>
    <fields>{json-eval($.fields)}</fields>
</facebookAds.getAdSet>

Sample request

{
    "ad_set_id":"456456456",
    "fields":"name, targeting"
}
updateAdSet

The 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

Sample configuration

<facebookAds.updateAdSet configKey="FB_CONN_1">
    <adSetId>{json-eval($.ad_set_id)}</adSetId>
    <properties>{json-eval($.properties)}</properties>
</facebookAds.updateAdSet>

Sample request

{
    "ad_set_id": "123123123",
    "properties": {
        "name": "New Furniture Ad set Updated",
        "status": "PAUSED",
        "bid_amount": "500"
    }
}
deleteAdSet

The deleteAdSet operation deletes an ad set.

Parameter Name Description Required
adSetId ID of the ad set. Yes

Sample configuration

<facebookAds.deleteAdSet configKey="FB_CONN_1">
    <adSetId>{json-eval($.ad_set_id)}</adSetId>
</facebookAds.deleteAdSet>

Sample request

{
    "ad_set_id": "123123123"
}
createAd

The 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

Sample configuration

<facebookAds.createAd configKey="FB_CONN_1">
    <adAccountId>{json-eval($.account_id)}</adAccountId>
    <properties>{json-eval($.properties)}</properties>
</facebookAds.createAd>

Sample request

{
    "account_id": "123123123",
    "properties": {
        "name": "New Furniture Ad",
        "status": "PAUSED",
        "adset_id": "456456456",
        "creative": {
            "creative_id": "789789789"
        }
    }
}
getAds

The 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

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>
</facebookAds.getAds>

Sample request

{
    "account_id": "123123123",
    "fields": "id,name,status,ad_active_time",
    "status": [
        "ACTIVE"
    ],
    "updated_since": 34564356
}
getAd

The 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

Sample configuration

<facebookAds.getAd configKey="FB_CONN_1">
    <adId>{json-eval($.ad_id)}</adId>
    <fields>{json-eval($.fields)}</fields>
</facebookAds.getAd>

Sample request

{
    "ad_id":"789789789",
    "fields":"id,name,status,campaign,ad_active_time"
}
updateAd

The 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

Sample configuration

<facebookAds.updateAd configKey="FB_CONN_1">
    <adId>{json-eval($.ad_id)}</adId>
    <properties>{json-eval($.properties)}</properties>
</facebookAds.updateAd>

Sample request

{
    "ad_id": "456456456",
    "properties": {
        "name": "New Furniture Ad 2",
        "status": "PAUSED"
    }
}
deleteAd

The deleteAd operation deletes an ad.

Parameter Name Description Required
adId ID of the ad. Yes

Sample configuration

<facebookAds.deleteAd configKey="FB_CONN_1">
    <adId>{json-eval($.ad_id)}</adId>
</facebookAds.deleteAd>

Sample request

{
    "ad_id": "456456456"
}
createCustomAudience

The createCustomAudience operation creates a custom audience.

Parameter Name Description Required
adAccountId ID of the ad account. Yes
properties Custom audience properties. Yes

Sample configuration

<facebookAds.createCustomAudience configKey="FB_CONN_1">
    <adId>{json-eval($.ad_id)}</adId>
    <properties>{json-eval($.properties)}</properties>
</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"
    }
}
createAdCreative

The createAdCreative operation creates an ad creative.

Parameter Name Description Required
adAccountId ID of the ad account. Yes
properties Ad creative properties. Yes

Sample configuration

<facebookAds.createAdCreative configKey="FB_CONN_1">
    <adId>{json-eval($.ad_id)}</adId>
    <properties>{json-eval($.properties)}</properties>
</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"
                }
            }
        }
    }
}
updateCustomAudience

The updateCustomAudience operation updates a custom audience.

Parameter Name Description Required
customAudienceId ID of the custom audience. Yes
properties Custom audience update properties. Yes

Sample configuration

<facebookAds.updateCustomAudience configKey="FB_CONN_1">
    <customAudienceId>{json-eval($.audience_id)}</customAudienceId>
    <properties>{json-eval($.properties)}</properties>
</facebookAds.updateCustomAudience>

Sample request

{
    "audience_id": "456456456",
    "properties": {
        "name": "My Custom Audience Update",
        "subtype": "CUSTOM", 
        "description": "Audience based on website traffic",
    }
}
addUsersToAudience

The 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

Sample configurations for Facebook API compatible input

<facebookAds.addUsersToAudience configKey="FB_CONN_1">
    <customAudienceId>{json-eval($.audience_id)}</customAudienceId>
    <properties>{json-eval($.properties)}</properties>
</facebookAds.addUsersToAudience>

<facebookAds.addUsersToAudience configKey="FB_CONN_1">
    <customAudienceId>{json-eval($.audience_id)}</customAudienceId>
    <properties>{json-eval($.properties)}</properties>
    <inputStructure>FACEBOOK_API_COMPATIBLE</inputStructure>
</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>
</facebookAds.addUsersToAudience>

Sample request for JSON array input

{
    "audience_id": "456456456",
    "properties": [
        {
            "email": "elizabetho@fb.com",
            "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": "andrewj@fb.com",
            "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
        }
    ]
}
removeUsersFromAudience

The 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

Sample configurations for Facebook API compatible input

<facebookAds.removeUsersFromAudience configKey="FB_CONN_1">
    <customAudienceId>{json-eval($.audience_id)}</customAudienceId>
    <properties>{json-eval($.properties)}</properties>
</facebookAds.removeUsersFromAudience>

<facebookAds.removeUsersFromAudience configKey="FB_CONN_1">
    <customAudienceId>{json-eval($.audience_id)}</customAudienceId>
    <properties>{json-eval($.properties)}</properties>
    <inputStructure>FACEBOOK_API_COMPATIBLE</inputStructure>
</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>
</facebookAds.removeUsersFromAudience>

Sample request for JSON array input

{
    "audience_id": "456456456",
    "properties": [
        {
            "email": "elizabetho@fb.com",
            "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": "andrewj@fb.com",
            "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
        }
    ]
}
getCustomAudiences

The 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

Sample configuration

<facebookAds.getCustomAudiences configKey="FB_CONN_1">
    <adAccountId>{json-eval($.ad_account_id)}</adAccountId>
    <filterByName>{json-eval($.filter_name)}</filterByName>
</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"
}

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.