> ## Documentation Index
> Fetch the complete documentation index at: https://deepline.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Meta Audiences

> Connect Meta Custom Audiences with a system user token, then create, sync, and read back audiences.

Use Meta Audiences to create and update Custom Audiences from an approved
first-party list. Plan consent, suppression, enrichment, and approval in
[Paid ads audiences](https://deepline.com/docs/ads-audiences.md); this page owns the Meta-specific contract.

## Connect with a system user token

Deepline connects to Meta with a **system user token** that you generate in
your own Meta Business portfolio. It takes about five minutes. The token:

* belongs to your business, not to a person, so it keeps working when someone
  leaves or changes their Facebook password;
* never expires if you choose **Never** in step 4;
* carries only `ads_management` and `ads_read`.

This is the same method reverse-ETL tools use for Meta. Hightouch, for example,
[recommends a system user token](https://hightouch.com/docs/destinations/meta)
over OAuth because an OAuth connection must be refreshed every 60 days.

### Before you start

You need:

* **Admin access to the Meta Business portfolio** that owns the ad account.
  Open [Business settings](https://business.facebook.com/latest/settings) and
  check that you can see **Users → System users**.
* **The ad account** you want Deepline to create audiences in. It must belong
  to, or be shared with, that Business portfolio. Its ID appears in Ads
  Manager next to the account name.
* **A Deepline workspace admin** to paste the token.

Your Business portfolio does not need to be verified, and the app does not need
Meta App Review. Meta lets a business's own app use the ads permissions on
that business's own ad accounts.

**1. Create a Business app**

Open [Create an app](https://developers.facebook.com/apps/creation/) in
Meta for Developers. If Meta shows "There's a new way to create apps with
Meta", select **Create app** to continue.

1. **App details.** Enter an app name such as `Deepline Audiences` and a
   contact email your team reads. Select **Next**.

   ![App details step with the app name and contact email](https://mintcdn.com/deepline2/TjtS-YlUuhNy1drn/images/integrations/meta-audiences/01-create-app-details.jpg?fit=max\&auto=format\&n=TjtS-YlUuhNy1drn\&q=85\&s=29d9a89e3c43bed1897d8feac48c32fe)

2. **Use cases.** Check **Create & manage ads with Marketing API**, then
   select **Next**. This use case is what makes `ads_management` and
   `ads_read` available to the token in step 4.

   ![Use cases step with Create & manage ads with Marketing API selected](https://mintcdn.com/deepline2/TjtS-YlUuhNy1drn/images/integrations/meta-audiences/02-create-app-use-case.jpg?fit=max\&auto=format\&n=TjtS-YlUuhNy1drn\&q=85\&s=6536e463cd5036123fd145fbbb12e040)

3. **Business.** Select the Business portfolio that owns your ad account,
   then select **Next**. An unverified portfolio works.

   ![Business step with the Business portfolio selected](https://mintcdn.com/deepline2/TjtS-YlUuhNy1drn/images/integrations/meta-audiences/03-create-app-business.jpg?fit=max\&auto=format\&n=TjtS-YlUuhNy1drn\&q=85\&s=579a180e7f983d0fa7f6ebfbbb9f3bbf)

4. **Requirements and Overview.** Meta lists no requirements for this use
   case. Check the overview and select **Create app**, which accepts Meta's
   Platform Terms for your business. Meta may ask for your password.

   ![Overview step showing the app name, use case and business](https://mintcdn.com/deepline2/TjtS-YlUuhNy1drn/images/integrations/meta-audiences/04-create-app-overview.jpg?fit=max\&auto=format\&n=TjtS-YlUuhNy1drn\&q=85\&s=be05317e822678443ba245957510c582)

Already have an app in this portfolio with a Marketing API use case? You
can reuse it and skip this step.

**2. Add a system user**

In Business settings, open
[Users → System users](https://business.facebook.com/settings/system-users)
and select **Add**. If you manage more than one Business portfolio, Meta
first asks you to pick one: choose the portfolio that owns your ad
account. Name the system user `Deepline`, keep the role **Employee**, and
select **Create system user**.

![Create system user dialog with the Employee role](https://mintcdn.com/deepline2/TjtS-YlUuhNy1drn/images/integrations/meta-audiences/05-create-system-user.jpg?fit=max\&auto=format\&n=TjtS-YlUuhNy1drn\&q=85\&s=ff8ec02dc50df972e35d8fcd92c67a14)

**Add** stays greyed out until an app belongs to the portfolio, and Meta
shows "In order to add a system user, an app must be part of this business
portfolio". That is why the app comes first. Keep the **Employee** role:
Meta allows only one Admin system user per business and recommends a
regular system user for asset access, as
[Hightouch also notes](https://hightouch.com/docs/destinations/meta).

**3. Give the system user the ad account and the app**

Select the new system user, then **Assign assets**.

* **Ad accounts:** select your ad account and turn on
  **Manage campaigns (ads)** under Partial access. Meta turns on View
  performance and Manage Creative Hub mockups with it.

  ![Ad account permissions with Manage campaigns (ads) turned on](https://mintcdn.com/deepline2/TjtS-YlUuhNy1drn/images/integrations/meta-audiences/06-ad-account-access.jpg?fit=max\&auto=format\&n=TjtS-YlUuhNy1drn\&q=85\&s=ebc3612a795dd779ed05ddfc6aa4ecfa)

* **Apps:** select the app from step 1 and turn on **Develop app**. Meta
  turns on View insights and Test app with it.

  ![App permissions with Develop app turned on](https://mintcdn.com/deepline2/TjtS-YlUuhNy1drn/images/integrations/meta-audiences/06b-app-access.jpg?fit=max\&auto=format\&n=TjtS-YlUuhNy1drn\&q=85\&s=999e03603a445a38961a9fa2bccb8e8c)

Select **Assign assets**. The system user should now list both:

![System user with the ad account and app assigned](https://mintcdn.com/deepline2/TjtS-YlUuhNy1drn/images/integrations/meta-audiences/07-assigned-assets.jpg?fit=max\&auto=format\&n=TjtS-YlUuhNy1drn\&q=85\&s=700b89b8ab0372092f797dad1b48f0f4)

Full control (Manage ad accounts / Manage app) also works; Hightouch's
guide asks for it. Deepline verified that the partial access above is
enough to create, sync, read and delete customer-list audiences.

**4. Generate the token**

On the system user, select **Generate token**.

1. **Select app:** pick the app from step 1, then **Next**.

   ![Generate token dialog with the app selected](https://mintcdn.com/deepline2/TjtS-YlUuhNy1drn/images/integrations/meta-audiences/08-token-select-app.jpg?fit=max\&auto=format\&n=TjtS-YlUuhNy1drn\&q=85\&s=cc25c71b7035adfdd323333900c5d577)

2. **Set expiration:** choose **Never**, then **Next**. Meta preselects
   "60 days (Recommended)". Deepline stores the token as permanent, so a
   60-day token stops working without warning when it expires.

   ![Token expiration set to Never](https://mintcdn.com/deepline2/TjtS-YlUuhNy1drn/images/integrations/meta-audiences/09-token-expiration-never.jpg?fit=max\&auto=format\&n=TjtS-YlUuhNy1drn\&q=85\&s=1f1ee896bf24f53f6f15207a7dae1658)

3. **Assign permissions:** type `ads_` in the search box and check
   **ads\_read** and **ads\_management**. Leave everything else unchecked.
   Deepline does not use `business_management`, `pages_manage_ads`, or any
   other permission.

   ![ads\_read and ads\_management checked](https://mintcdn.com/deepline2/TjtS-YlUuhNy1drn/images/integrations/meta-audiences/10-token-permissions.jpg?fit=max\&auto=format\&n=TjtS-YlUuhNy1drn\&q=85\&s=eda671a6d4731bfdcf5fa107425ce3d2)

4. Select **Generate token**, then copy the token. Meta shows it only once.
   Store it only in Deepline; don't paste it into chat, email or tickets.

You can't change a token's permissions after you generate it. To change
them, generate a new token and paste it into Deepline again.

**5. Accept the Custom Audience terms**

Meta rejects customer-list audiences until a person in your business
accepts its Custom Audience terms for that ad account. Open this link with
your ad account ID and select **Accept**:

`https://business.facebook.com/ads/manage/customaudiences/tos/?act=<ad account ID>`

When they're accepted, the page says "You have accepted these terms of
service on behalf of" your business:

![Custom Audience terms page showing the terms are accepted](https://mintcdn.com/deepline2/TjtS-YlUuhNy1drn/images/integrations/meta-audiences/11-custom-audience-terms-accepted.png?fit=max\&auto=format\&n=TjtS-YlUuhNy1drn\&q=85\&s=e77f608971120706c8f38d8374ca86cf)

Repeat for each ad account you connect. Creating one audience by hand in
Ads Manager's **Audiences** page also shows the terms prompt.

**6. Paste the token into Deepline**

In Deepline, open **Integrations**, find **Meta audiences** under Ad
Platform, and select **Connect**.

![Meta audiences in the Deepline integrations list](https://mintcdn.com/deepline2/TjtS-YlUuhNy1drn/images/integrations/meta-audiences/00-deepline-connect.png?fit=max\&auto=format\&n=TjtS-YlUuhNy1drn\&q=85\&s=f5f56d9fc443b9c63c3586ba94651c02)

Paste the token into **System user token** and select
**Connect with token**.

![Deepline's Meta Audiences setup page with the system user token field](https://mintcdn.com/deepline2/gfJZj49h0UbHFYIv/images/integrations/meta-audiences/12-deepline-setup-page.png?fit=max\&auto=format\&n=gfJZj49h0UbHFYIv\&q=85\&s=92437ef84d364f944e584f41e7701fe7)

### What Deepline checks when you connect

When you select **Connect with token**, Deepline:

1. lists every ad account the token can reach;
2. confirms it can read Custom Audiences in at least one account, starting
   with the default. If none can, it saves nothing and keeps any existing
   connection;
3. checks whether the Custom Audience terms are accepted for each account, and
   lists any account still missing them with an **Accept terms** link;
4. saves the token. It is stored encrypted and never returned by the API.

If there is exactly one ad account, Deepline enables it and makes it the
default. With more than one, enable the accounts Deepline may use, star a
default, and select **Save**. Tool calls that omit `ad_account_id` use the
default.

Agents can read each account's terms state from
`GET /api/v2/integrations/meta_audiences/accounts`, called with an org admin's
session or an API key owned by an org admin. The
`customAudienceTermsAccepted` field is `true`, `false`, or `null` when Meta
didn't report it. The endpoint returns the state from the last discovery;
**Refresh** (or `POST` to the same endpoint) discovers again.

### Rotate or revoke the token

* **Rotate:** generate a new token for the same system user (step 4) and paste
  it on the same Deepline page. Your enabled accounts and default carry over
  where the accounts still match.
* **Revoke:** in System users, select the system user and **Revoke tokens**.
  Meta rejects the token immediately, and Deepline reports the error on its
  next Meta call. Disconnect it under **Integrations** too.
* **Add an ad account:** assign it to the system user (step 3), accept its
  terms (step 5), then select **Refresh** on the Deepline Meta Audiences page.
  The existing token picks up newly assigned accounts.

### How this differs from other tools

| | Deepline | Hightouch ([guide](https://hightouch.com/docs/destinations/meta)) |
| - | - | - |
| Token permissions | `ads_management`, `ads_read` | `ads_management`, `business_management` |
| Ad account access | Manage campaigns (ads) | Full access |
| App access | Develop app | Full access |
| System user role | Employee | Employee |
| Expiration | Never | Never |

Deepline lists ad accounts through the token's own accounts, so it doesn't need
`business_management`. If you reuse a token that has it, Deepline ignores it.

> [!NOTE]
>
> Meta Login for Business is not offered for new connections while Deepline's
> Meta App Review is pending. Existing Login for Business connections keep
> working. To switch one to a token, paste a token on the same page; your
> enabled accounts carry over where they still match.

### Connection troubleshooting

| What you see | What it means | Fix |
| - | - | - |
| **Add** is greyed out on System users | No app belongs to the Business portfolio yet. | Create the app first (step 1), connected to this portfolio. |
| `ads_management` or `ads_read` missing from the permission list | The app doesn't have a Marketing API use case. | In the app dashboard, add the use case **Create & manage ads with Marketing API**, then generate the token again. |
| "This token can reach no ad accounts" | The system user has no ad account assigned. | Assign the ad account (step 3), then select **Connect with token** again. The same token works. |
| "Custom audience terms not accepted" when creating an audience | Nobody in the business has accepted the terms for that ad account. | Open the link in the message, or step 5, and select **Accept**. |
| `(#190)` "Error validating access token" | The token was revoked, expired (a 60-day token), or copied incompletely. | Generate a new token with expiration **Never** and paste it again. |
| `(#100) Unsupported get request` or "Requires business\_management permission" | The connection came from Meta Login for Business without the ads permissions. | Connect with a system user token as above. |
| An audience shows about 1,000 people right after an upload | Meta reports 1,000 as the minimum size for small or still-processing audiences. | Check again after Meta finishes processing; see the safeguards below. |

## Live actions and schema

Execute these IDs through the shared
[`POST /api/v2/integrations/{toolId}/execute` contract](https://deepline.com/docs/api-reference#execute-a-tool).
The table lists `payload` fields. Substitute an Action ID from it into
`GET /api/v2/integrations/{toolId}/get` to inspect the live schema.

| Action ID | Required payload | Important optional fields |
| - | - | - |
| `meta_audiences_create_audience` | `name` | `ad_account_id`, `customer_file_source` |
| `meta_audiences_list_audiences` | — | `ad_account_id` |
| `meta_audiences_get_audience_status` | `audience_id` | `ad_account_id` |
| `meta_audiences_sync_audience_members` | `audience_id`, `rows` | `ad_account_id`, `mode` |
| `meta_audiences_delete_audience` | `audience_id` | `ad_account_id` |

Each `rows` entry can carry a supported raw or SHA-256 identifier. Deepline
hashes supported raw identifiers locally before upload and reports invalid rows
separately.

## Meta-specific safeguards

* Create an audience once and store `data.audience.id` from the create result.
  Use that ID in later status, sync, and delete requests.
* Use `mode: "replace"` for a full snapshot and `mode: "append"` for an
  incremental addition. Send one complete member list per sync rather than
  splitting it into concurrent uploads.
* Read `operation_status`, `delivery_status`, and the
  `approximate_count_lower_bound` / `approximate_count_upper_bound` pair. Meta
  reports a range; a null count shortly after sync is not by itself a failure.
* If `operation_status` shows a replacement upload is still processing, poll
  `meta_audiences_get_audience_status` until it settles before resending the
  complete list in one call. Do not continue a partial upload with append.
* If `delivery_status` reports poor matching, improve the source list before
  treating the upload as successful.
* Deleting an audience is irreversible. Read the audience and account IDs back
  before calling the delete action.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.