Setup Facebook and Instagram¶

Warning

The Facebook API will be retired at the end of February 2023.

Link a Facebook Page¶

In order to advertise on Facebook through AdRoll, you must link your Facebook business page with your user account. You’ll only need to connect your Facebook Page once.

Giving us access to your Facebook page is a three step process:

Request Access
Approve Access
Finalize Setup

Request Access¶

The first step is to send an agency access requests to the owner of the specified page. This is done by making a POST request to the POST /facebook/fb_page_url endpoint with the the advertiser_eid and page_url parameters:

curl -X POST \
-H 'Authorization: Token YOUR_TOKEN' \
-d advertiser_eid="Y6N4RS7HQFE3BCHPSJ4VQ4" \
-d page_url="https://www.facebook.com/Cats-4-Gold-924916227619294/" \
https://services.adroll.com/facebook/fb_page_url?apikey=MYAPIKEY

{
    "created_date": "2016-05-27T23:27:11",
    "eid": "BN7O7BLPBRBXPK3ID3ZWAG",
    "fb_page_id": "924916227619294",
    "fb_page_url": "https://www.facebook.com/Cats-4-Gold-924916227619294",
    "id": 7,
    "is_page_backed": true,
    "name": "",
    "organization_eid": "LCRG5QO7YVAPVIDXUS32DJ",
    "page_access": false,
    "page_admin_access": false,
    "updated_date": "2016-05-27T23:46:10"
}

Approve Access¶

Next you must instruct the page owner to visit Facebook and approve access.

Finalize Setup¶

Once access has been granted by the page owner, send an another POST to the same endpoint as the first step:

curl -X POST \
-H 'Authorization: Token YOUR_TOKEN' \
-d advertiser_eid="Y6N4RS7HQFE3BCHPSJ4VQ4" \
-d page_url="https://www.facebook.com/Cats-4-Gold-924916227619294/" \
https://services.adroll.com/facebook/fb_page_url?apikey=MYAPIKEY

{
    "created_date": "2016-05-27T23:27:11",
    "eid": "BN7O7BLPBRBXPK3ID3ZWAG",
    "fb_page_id": "924916227619294",
    "fb_page_url": "https://www.facebook.com/Cats-4-Gold-924916227619294",
    "id": 7,
    "is_page_backed": true,
    "name": "",
    "organization_eid": "LCRG5QO7YVAPVIDXUS32DJ",
    "page_access": true,
    "page_admin_access": true,
    "updated_date": "2016-05-27T23:47:05"
}

You’ll know the authorization was successful when the page_access and page_admin_access fields are true.

Update a Facebook Page¶

You can update the Facebook Page used by an Advertiser by repeating the steps in Link a Facebook Page.

Read a Facebook Page¶

You can verify page access by calling GET /facebook/fb_page_url and verifying that page_access and page_admin_access fields are true.

curl -H 'Authorization: Token YOUR_TOKEN' \
https://services.adroll.com/facebook/fb_page_url?apikey=MYAPIKEY

{
    "fb_page_id": "924916227619294",
    "fb_page_img": "https://scontent.xx.fbcdn.net/v/t1.0-1/c8.0.50.50/p50x50/13227202_924916487619268_2595545300798231503_n.jpg?oh=841895bd5e393a55db271b4ab9b4a212&oe=57C28088",
    "fb_page_name": "Cats 4 Gold",
    "is_published": true,
    "page_access": true,
    "page_admin_access": true
}

Link an Instagram Account¶

To run advertisements on Instagram, you have two options for linking your Instagram account:

Business Manager claimed Instagram Account
Page Backed Instagram Account

Note

You must complete the steps in Link a Facebook Page prior to setting up Instagram

Business Manager claimed Instagram Account¶

Sending a request to POST /facebook/instagram_account with an account_id will attempt to assign access to an Instagram account that has been claimed by an advertiser. Refer to Claim an Instagram Account for Business.

The advertiser must have added us as a partner in their Business Manager.

curl -X POST \
-H 'Authorization: Token YOUR_TOKEN' \
-d advertiser_eid="Y6N4RS7HQFE3BCHPSJ4VQ4" \
-d account_id="1147545608621523" \
https://services.adroll.com/facebook/instagram_account?apikey=MYAPIKEY

{
    "instagram_actor_id": 1147545608621523
}

Page Backed Instagram Account¶

Sending a request to POST /facebook/instagram_account with no account_id will assign a Page Backed Instagram Account to the advertiser. See Page Backed Instagram Account.

The Facebook page backing the Instagram account is the one assigned in the Assign Facebook Page step. If multiple Advertisers are being managed, the advertiser_eid parameter can be used to specify which Advertiser.

curl -X POST \
-H 'Authorization: Token YOUR_TOKEN' \
-d advertiser_eid="Y6N4RS7HQFE3BCHPSJ4VQ4" \
https://services.adroll.com/facebook/instagram_account?apikey=MYAPIKEY

{
    "instagram_actor_id": 994849830607651
}

Error Codes¶

Code	Message	Reason
1359102	A Facebook Ad Account is required	We have not completed its integration with Facebook. Wait a few minutes and try again
1359102	A Facebook page URL is required	The Facebook Page integration process has not been completed

Target Instagram¶

You target Instagram by including instagramstream in the placement_targets parameter of the POST /api/v1/adgroup/create endpoint:

curl -H 'Authorization: Token YOUR_TOKEN' \
-F campaign=F6FMJOTUHVENRAFAR34OV7 \
-F placement_targets="[\"desktopfeed\",\"mobilefeed\",\"rightcolumn\",\"FAN\",\"instagramstream\"]" \
-F name="Test AdGroup" \
'https://services.adroll.com/api/v1/adgroup/create?apikey=MYAPIKEY'