News for Developers

Back to News

API Changes for Custom Audience Sharing

As we shared in June, we've introduced a new upload and sharing flow for Custom Audiences from a customer file. When uploading Custom Audiences from a customer file, advertisers need to accept our Custom Audiences terms, provide audience origin information, and establish audience sharing relationships through Business Manager. As noted, these changes are designed to provide increased transparency, accountability, and ease of use for our targeting products.

Timeline of Changes

As we make these changes, we want to share how API-expected behavior will change for customer file Custom Audiences. Follow this timeline for these changes:

AUGUST 7, 2018

Given the changes happening on August 15, 2018 that could prevent campaign creation, editing, or duplication using shared customer file Custom Audiences, we'll add a new backend field to Custom Audiences that can be queried to identify if that audience is affected or not. This will enable you to notify advertisers who may not yet realize they need to take action before August 15, 2018 to continue using their shared customer file Custom Audiences.

AUGUST 15, 2018

After this date, any previously shared customer file Custom Audience that does not have a Business Manager relationship in place and was not shared through the new flow will no longer be available for use in new ad sets. Campaigns set up before August 15 targeting customer file Custom Audiences shared before July 2, 2018 (including managed Custom Audiences) will continue to deliver until October 1, 2018, as long as those campaigns are not paused or edited after August 15, 2018.

OCTOBER 1, 2018

As previously announced, we will end delivery for shared Custom Audiences that do not have a Business Manager relationship in place, facilitated by the new sharing flow. Delivery will only continue for campaigns leveraging audiences that have been shared through established Business Manager partnerships using the new Custom Audience flow.

Technical Specifications

To further support the above updates, we introduced the following functionality to our interfaces:

View Current Sharing Status for Shared Customer File Custom Audiences

With the below edge and fields on the custom_audience_id node, audience recipients can verify if there's an established relationship between the business that owns the audience and the business that owns the recipient ad account. Your application needs to provide the ID of the recipient ad account under the ad_account_id parameter.

Sample API Call, where possible values of Sharing Status are NO_RELATIONSHIP, PENDING_RELATIONSHIP, and ACCEPTED_RELATIONSHIP.

GET <custom_audience_id>?ad_account_id=<ad_account_id>&fields=['sharing_status']

Response:

curl \
{
    “sharing_status” : {
        “sharing_relationship_id”: <RELATIONSHIP_ID> , 
        “status”: Sharing Status, 
    } 
}

Based on sharing status returned in the API, there can be various implications for audience usage:

  • ACCEPTED_RELATIONSHIP - Indicates that there is already an accepted sharing relationship established between initiator and recipient business, and they can continue to use the shared audience without any changes.

  • PENDING_RELATIONSHIP:
    • Indicates that there is a sharing relationship initiated by business owner of the audience towards the business recipient, but they've not yet agreed to it.
    • Recipient business admin needs to accept this relationship > go to Audience Manager or Business Manager settings to accept using this audience for adset creation.

  • NO_RELATIONSHIP:
    • Indicates that audience was shared earlier without a sharing relationship established between both businesses.
    • Recipient can continue to use the audience until August 15, 2018 without a problem. However, starting August 15, 2018, they cannot use it for new ad creation, unless the business owner shared an audience and the business admin recipient accepts the relationship. For more information, see Sharing Custom Audiences between Business Managers.

View Recipient Ad Accounts and Corresponding Sharing Status on the Audience Node

The following API feature allows audience owners to verify the list of recipient ad accounts for a customer file Custom Audience, where possible values of Sharing Status are NO_RELATIONSHIP, PENDING_RELATIONSHIP, and ACCEPTED_RELATIONSHIP.

GET <custom_audience_id>/shared_account_info

Response:

{
  "data": [
    {
      "account_id": <recipient_account_id>,
      "account_name": <recipient_account_name>,
      "business_id": <recipient_business_id>,
      "business_name": <recipient_business_name>,
      "sharing_status": Sharing Status,
    },
    ...
  ],
}