Marketing API

Get Started with the Flexible Ad Format

This document shows you how the flexible ad format empowers multi-asset creative automation by grouping related assets in a single ad without needing to select a specific format.

Before You Start

You need to familiarize yourself with these steps to set up your ad campaigns for the flexible ad format:

  1. Create a Campaign
  2. Create an Ad Set
  3. Create the Ad or a standalone Creative
  4. Enable the Ad

Limitations

  • Currently only OUTCOME_SALES and OUTCOME_APP_PROMOTION campaign objectives support the flexible ad format.

Create an Ad using the Flexible Ad Format

You can use creative_asset_groups_spec to provide multiple creative assets, with the following limitations:

  • At least 1 image or video is required per group.
  • All call_to_actions provided must have the same type.
  • There can be no more than 5 texts per text_type in a group.

For example, to create an ad using the flexible ad format through the /ads endpoint:

curl \
  -F 'adset_id=<ADSET_ID>' \
  -F "creative={
    'name': 'Sample Creative',
    'object_story_spec': {  
      ...    
    },
  }" \
  -F 'creative_asset_groups_spec={
  "groups": [
    {
      "images": [
        {
          "hash": <IMAGE_HASH_1>,
        },
        {
          "hash": <IMAGE_HASH_2>,
        }
      ],
      "videos": [
        {
          "video_id": <VIDEO_ID_1>,
        },
        {
          "video_id": <VIDEO_ID_2>,
        },
      ],
      "texts": [
        {
          "text": "Summer Sale",
          "text_type": "primary_text",
        },
        {
          "text": "Everything 50% Off",
          "text_type": "headline",
        }
      ],
      "call_to_action": {
        "type": "LEARN_MORE",
        "value": {
          "link": "https://www.example.com/",
        }
      }
    }
  ],
}' \
  -F 'status=PAUSED' \
  -F "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/ads

Read the Flexible Ad Format

To check your ad, read creative_asset_group_spec:

curl -G \
  -d 'fields=creative_asset_groups_spec' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<AD_ID>/
Response
{
  "creative_asset_groups_spec": {
    "groups": [
      {
        "images": [
          {
            "hash": <IMAGE_HASH_1>,
          },
          {
            "hash": <IMAGE_HASH_2>,
          }
        ],
        "texts": [
          {
            "text": "Summer Sale",
            "text_type": "primary_text"
          },
          {
            "text": "Everything 50% off",
            "text_type": "headline"
          }
        ],
        "videos": [
          {
            "video_id": <VIDEO_ID_1>,
            "image_hash": <VIDEO_THUMBNAIL_HASH_1>
          },
          {
            "video_id": <VIDEO_ID_2>,
            "image_hash": <VIDEO_THUMBNAIL_HASH_2>
          }
        ],
        "group_uuid": <GROUP_ID>
      }
    ]
  },
  "id": <AD_ID>
}

See Also

To learn more about the components and concepts mentioned in this guide, visit the following guides: