Skip to main content
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; 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 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 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 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
  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
  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
  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
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 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 roleAdd 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.
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
  • 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
Select Assign assets. The system user should now list both:System user with the ad account and app assignedFull 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
  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
  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
  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 acceptedRepeat 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 listPaste the token into System user token and select Connect with token.Deepline's Meta Audiences setup page with the system user token field

​
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 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.
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

​
Live actions and schema

Execute these IDs through the shared POST /api/v2/integrations/{toolId}/execute contract. The table lists payload fields. Substitute an Action ID from it into GET /api/v2/integrations/{toolId}/get to inspect the live schema. 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.