| Photo | Video | Carousel | Playable | |
|---|---|---|---|---|
Mobile Install Ad | ✓ | ✓ | ✓ | ✓ |
Mobile Engagement Ad | ✓ | ✓ | ✓ | |
Desktop Install Ad | ✓ | ✓ | ✓ | |
Desktop Engagement Ad | ✓ | ✓ | ✓ | |
Desktop App Ad for Virtual Goods | ✓ | ✓ | ✓ |


APP_INSTALLS, LINK_CLICKS, or CONVERSIONS.user_os field. The placement should have a device_platforms field with value of [‘mobile’] and highly recommend the use of the spec’s other fields to target mobile devices on Facebook. Optionally, you can specify publisher_platforms if you only want certain platforms.device_platforms must be desktop. Optionally, you can specify facebook_positions if you do not want both Facebook desktop Feed and Right-Hand-Side column.GET_OFFER is used for virtual goods, the price must be discounted. Please see virtual goods for more information.call_to_action field of a post or the ad creative’s object_story_spec. You can also specify the mobile app’s deep link in the app_link field, or the desktop app’s virtual good object in the product_link field.| Key | Value | Required |
|---|---|---|
type | Call to action types for mobile, regardless of install or engagement: SHOP_NOWBOOK_TRAVELLEARN_MORESIGN_UPDOWNLOADINSTALL_MOBILE_APPUSE_MOBILE_APPWATCH_VIDEOWATCH_MOREOPEN_LINKCall to action types for desktop install or engagement: USE_APP (desktop apps)PLAY_GAME (desktop game apps)Call to action types for desktop app ads for virtual goods: BUY_NOWGET_OFFER | yes |
value | JSON dictionary of:
{"link": "<APP_STORE_LINK>","app_link": "<MOBILE_DEEP_LINK>","product_link": "<VIRTUAL_GOOD_DEEP_LINK>","link_title": "<NAME_FOR_LINK>"} | yes
|
value.link | refers to the App Store, Google Play Store, or Facebook Canvas App URL, e.g. https://itunes.apple.com/us/app/facebook/id284882215 | yes |
value.app_link | To define the deep link destination only for mobile apps, e.g. myapp://product/12345.
To specify a deep link for desktop apps you should specify it directly in the URL link field. | yes, only for mobile install or engagement ads |
value.product_link | To define the URL that points to the product's Open Graph virtual good object. See here for setup details. | yes, only for desktop virtual goods |
value.link_title | Allows you to customize the name for the link, which shows up below the ad's image | no |

object_story_spec: {'link_data': ...} field.curl -X POST \
-F 'name="Sample Creative"' \
-F 'object_story_spec={
"page_id": "<PAGE_ID>",
"link_data": {
"call_to_action": {
"type": "INSTALL_MOBILE_APP",
"value": {
"link": "<APP_STORE_URL>"
}
},
"image_hash": "<IMAGE_HASH>",
"link": "<APP_STORE_URL>",
"message": "Try it out"
}
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
child_attachments’ link field, specify an app store link.child_attachment. You do not have to specify the link again in the call_to_action:{'value':{'link':... }}}curl -X POST \
-F 'name="Carousel app ad"' \
-F 'object_story_spec={
"page_id": "<PAGE_ID>",
"link_data": {
"message": "My message",
"link": "http://www.example.com/appstoreurl",
"caption": "WWW.ITUNES.COM",
"name": "The link name",
"description": "The link description",
"child_attachments": [
{
"link": "http://www.example.com/appstoreurl",
"image_hash": "<IMAGE_HASH>",
"call_to_action": {
"type": "USE_MOBILE_APP",
"value": {
"app_link": "<DEEP_LINK>"
}
}
},
{
"link": "http://www.example.com/appstoreurl",
"image_hash": "<IMAGE_HASH>",
"call_to_action": {
"type": "USE_MOBILE_APP",
"value": {
"app_link": "<DEEP_LINK>"
}
}
},
{
"link": "http://www.example.com/appstoreurl",
"image_hash": "<IMAGE_HASH>",
"call_to_action": {
"type": "USE_MOBILE_APP",
"value": {
"app_link": "<DEEP_LINK>"
}
}
},
{
"link": "http://www.example.com/appstoreurl",
"image_hash": "<IMAGE_HASH>",
"call_to_action": {
"type": "USE_MOBILE_APP",
"value": {
"app_link": "<DEEP_LINK>"
}
}
}
],
"multi_share_optimized": true
}
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
object_story_spec: {'video_data':...} field.curl \
-F 'name=Sample Creative' \
-F 'object_story_spec={
"page_id": "<PAGE_ID>",
"video_data": {
"call_to_action": {"type":"INSTALL_MOBILE_APP","value":{"link":"<APP_STORE_URL>"}},
"image_url": "<THUMBNAIL_URL>",
"video_id": "<VIDEO_ID>"
}
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
/promotable_posts edge.curl https://graph.facebook.com/v25.0/<PAGE_ID>/promotable_posts
pages_manage_ads permissionADVERTISE task on the Page"call_to_action={ 'type':'LEARN_MORE', 'value':{ 'link':'https://itunes.apple.com/us/app/facebook/id284882215', 'app_link':'facebook://path/to/page' } }"
https://graph.facebook.com/v25.0/?type=og&scrape=true&id=<APP_LINK>
https://graph.facebook.com/v25.0/<APP_ID>/insights/application_mobile_app_installs?&access_token=<ACCESS_TOKEN
breakdown, equal to one of the following values. You cannot currently combine breakdowns.| Name | Description |
|---|---|
gender_age | Break down your statistics on audience’s age and gender |
country | Break down your statistics on audience’s country |
locale | Break down your statistics on audience’s locale |
https://graph.facebook.com/v25.0/<APP_ID>/insights/application_mobile_app_installs?breakdown=gender_age&access_token=<ACCESS_TOKEN>
https://graph.facebook.com/v25.0/<APP_ID>/insights/application_mobile_app_installs?breakdown=country&access_token=<ACCESS_TOKEN>
https://graph.facebook.com/v25.0/<APP_ID>/insights/application_mobile_app_installs?breakdown=locale&access_token=<ACCESS_TOKEN>
PAGE_ACCESS_TOKEN and Pages API session to create Page Post.curl \
-F 'message=Sign up today' \
-F 'picture=<IMAGE_URL>' \
-F 'link=<LINK>' \
-F 'published=1' \
-F 'call_to_action={"type":"SIGN_UP","value":{"link":"<LINK>"}}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<PAGE_ID>/feed
{STORY_ID} is in form of '{PAGE_ID}_{POST_ID}')curl -X POST \
-F 'object_story_id="<PAGE_ID>_<POST_ID>"' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
curl -X POST \
-F 'name="My AdGroup with Redownload"' \
-F 'adset_id="<AD_SET_ID>"' \
-F 'creative={
"creative_id": "<CREATIVE_ID>"
}' \
-F 'redownload=1' \
-F 'status="PAUSED"' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/ads
PAGE_ACCESS_TOKEN and Pages API session to create Page Post.url -X POST \
-F 'message="This is a test message"' \
-F 'call_to_action={
"type": "BUY_NOW",
"value": {
"link": "<APP_STORE_URL>",
"app_link": "<DEEP_LINK>"
}
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<PAGE_ID>/feed
curl -X POST \
-F 'object_story_id="<PAGE_ID>_<POST_ID>"' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
curl \
-F 'name=LifetimeBudgetSet' \
-F 'lifetime_budget=100000' \
-F 'bid_amount=500' \
-F 'billing_event=IMPRESSIONS' \
-F 'optimization_goal=LINK_CLICKS' \
-F 'promoted_object={"application_id":"<APP_ID>","object_store_url":"<APP_STORE_URL>"}' \
-F 'targeting={
"facebook_positions": ["feed"],
"geo_locations": {"countries":["US"]},
"publisher_platforms": ["facebook","audience_network"],
"user_os": ["IOS"]
}' \
-F 'campaign_id=<CAMPAIGN_ID>' \
-F 'end_time=2018-02-06T04:45:30+0000' \
-F 'status=PAUSED' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adsets
curl \
-F 'name=My Ad' \
-F 'adset_id=<AD_SET_ID>' \
-F 'creative={"creative_id":"<CREATIVE_ID>"}' \
-F 'redownload=1' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/ads
PAGE_ACCESS_TOKEN and Pages API session to create Page Post.curl \
-F 'message=Check out this App today. Available on iTunes.' \
-F 'published=1' \
-F 'link=<APP_STORE_URL>' \
-F 'picture=<IMAGE_URL>' \
-F 'call_to_action={
"type": "LEARN_MORE",
"value": {"link":"<APP_STORE_URL>","app_link":"<APP_DEEP_LINK>"}
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<PAGE_ID>/feed
curl -X POST \
-F 'object_story_id="<PAGE_ID>_<POST_ID>"' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
promoted_object to include a custom_event_type to optimize towards, please refer to ad set docs for more details.curl -X POST \
-F 'name="A CPA Ad Set optimized for App Events"' \
-F 'campaign_id="<AD_CAMPAIGN_ID>"' \
-F 'daily_budget=300' \
-F 'start_time="2025-11-13T15:11:01-0800"' \
-F 'end_time="2025-11-20T15:11:01-0800"' \
-F 'billing_event="IMPRESSIONS"' \
-F 'optimization_goal="OFFSITE_CONVERSIONS"' \
-F 'bid_amount=100' \
-F 'status="PAUSED"' \
-F 'promoted_object={
"application_id": "<APP_ID>",
"object_store_url": "<APP_STORE_URL>",
"custom_event_type": "PURCHASE"
}' \
-F 'targeting={
"facebook_positions": [
"feed"
],
"geo_locations": {
"countries": [
"US"
]
},
"user_os": [
"iOS"
]
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adsets
curl \
-F 'name=My Ad' \
-F 'adset_id=<AD_SET_ID>' \
-F 'creative={"creative_id":"<CREATIVE_ID>"}' \
-F 'redownload=1' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/ads
PAGE_ACCESS_TOKEN and Pages API session to create Page Post. curl \
-F 'name=My Video' \
-F 'message=Check out this app!' \
-F 'thumbnail=<APP_STORE_URL>' \
-F 'published=0' \
-F 'call_to_action={"type":"INSTALL_MOBILE_APP","value":{"link":"<APP_STORE_URL>"}}' \
-F 'source=@<VIDEO_PATH>' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<PAGE_ID>/videos
curl \
-F 'name=My Video' \
-F 'message=Check out this app!' \
-F 'thumbnail=<APP_STORE_URL>' \
-F 'published=0' \
-F 'call_to_action={
"type": "LEARN_MORE",
"value": {"link":"<APP_STORE_URL>","app_link":"<APP_DEEP_LINK>"}
}' \
-F 'source=@<VIDEO_PATH>' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<PAGE_ID>/videos
curl \
-F 'name=My Video' \
-F 'message=Check out this app!' \
-F 'thumbnail=<THUMBNAIL_PATH>' \
-F 'published=0' \
-F 'call_to_action={"type":"PLAY_GAME","value":{"link":"<THUMBNAIL_PATH>"}}' \
-F 'source=@<VIDEO_PATH>' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<PAGE_ID>/videos
curl \
-F 'message=Buy coins now!' \
-F 'picture=<IMAGE_URL>' \
-F 'link=<LINK>' \
-F 'published=1' \
-F 'call_to_action={"type":"BUY_NOW","value":{"link":"<LINK>","product_link":"<PRODUCT_LINK>"}}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<PAGE_ID>/feed
curl \
-F 'name=My Video' \
-F 'message=Buy coins now!' \
-F 'thumbnail=<THUMBNAIL_PATH>' \
-F 'published=0' \
-F 'call_to_action={
"type": "BUY_NOW",
"value": {"link":"<THUMBNAIL_PATH>","product_link":"<THUMBNAIL_PATH>"}
}' \
-F 'source=@<VIDEO_PATH>' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<PAGE_ID>/videos
creative.template_url_spec. If not provided, the ad will lead users to your website.curl \
-F 'name=Advantage+ Catalog Ads Template Creative Sample' \
-F 'template_url_spec={
"config": {
"app_id": "1596400373958175"
}
}' \
-F 'access_token=<CCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
object_story_spec after web fallback is added.curl -X POST \
-F 'name="Traffic app fallback web sample"' \
-F 'object_story_spec={
"page_id": "<PAGE_ID>",
"template_data": {
"call_to_action": {
"type": "INSTALL_MOBILE_APP",
"value": {
"link": "https://www.example.com"
“app_link”: “<DEEPLINK_URL>
“object_store_urls”: [
<STORE_URL_OF_APP>
]
}
},
"message": "Test {{product.name | titleize}}",
"link": "https://www.example.com"",
"name": "Headline {{product.price}}",
"description": "Description {{product.description}}"
}
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
link field. If fallback needs to be a website, provide the object_store_urls value as a list with just one value — the app store URL of the app — and the link field with the website fallback URL.curl -X POST \
-F 'name="App Installs Campaign with Dynamic Product Ads"' \
-F 'objective="OUTCOME_APP_PROMOTION"' \
-F 'status="PAUSED"' \
-F 'special_ad_categories=[]' \
-F 'is_adset_budget_sharing_enabled=0' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/campaigns
curl \
-F 'name=Mobile App Installs Ad Set with Dynamic Product Ads' \
-F 'bid_amount=3000' \
-F 'billing_event=IMPRESSIONS' \
-F 'optimization_goal=APP_INSTALLS' \
-F 'daily_budget=15000' \
-F 'campaign_id=<CAMPAIGN_ID>' \
-F 'targeting={
"geo_locations": {"countries":["US"]},
"publisher_platforms": ["facebook","audience_network"],
"device_platforms": ["mobile"],
"user_os": ["IOS"],
"dynamic_audience_ids": ["<PRODUCT_AUDIENCE_ID>"]
}' \
-F 'promoted_object={
"product_set_id": "<PRODUCT_SET_ID>",
"application_id": "<APP_ID>",
"object_store_url": "<APP_STORE_URL>"
}' \
-F 'status=PAUSED' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adsets
curl -X POST \
-F 'name="Advantage+ catalog ads template creative sample"' \
-F 'object_story_spec={
"page_id": "<PAGE_ID>",
"template_data": {
"call_to_action": {
"type": "INSTALL_MOBILE_APP",
"value": {
"link": "http://www.example.com/appstoreurl"
}
},
"message": "Test {{product.name | titleize}}",
"link": "http://www.example.com/appstoreurl",
"name": "Headline {{product.price}}",
"description": "Description {{product.description}}"
}
}' \
-F 'product_set_id="<PRODUCT_SET_ID>"' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
curl \
-F 'name=My Ad' \
-F 'adset_id=<AD_SET_ID>' \
-F 'creative={"creative_id":"<CREATIVE_ID>"}' \
-F 'redownload=1' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/ads
curl -X POST \
-F "name=<NAME>" \
-F "source=<>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adplayables"
name: Name that differentiates the ad asset from other playable ads in the ad account; for example, {ad_name} -> {playable_asset_name}source: Absolute path of the file on your local machineaccess_token: Can be generated from the Graph API Explorer... <head> ... <meta name="ref-application-id" content="<YOUR_APP_ID>"> <meta name="ref-asset-id" content="<YOUR_ASSET_ID>"> ... </head> ...
curl \
-F 'name=Sample Creative' \
-F 'object_story_spec={
"page_id": "<PAGE_ID>",
"video_data": {
"call_to_action": {
"type":"INSTALL_MOBILE_APP",
"value":{
"application":<APP_ID>,
"link":"<APP_STORE_URL>"
}
},
"image_url": "<THUMBNAIL_URL>",
"link_description": "try it out",
"video_id": "<VIDEO_ID>"
}
}' \
-F 'playable_asset_id=<PLAYABLE_ASSET_ID>' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
curl \
-F 'name=My Ad' \
-F 'status=ACTIVE' \
-F 'adset_id=<AD_SET_ID>' \
-F 'creative={"creative_id":"<CREATIVE_ID>"}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/ads