How to Integrate Meta Ad Account with Pearl Diver

Permanent Token

Additional requirements:

• A Business app (Live).

• A System User (Admin role).

• Access to the Ad Account that Pearl Diver will act on.

• Ability to assign assets (App, Ad Account) to the System User.

UI reference: create Business app, create System User & assign assets, generate token with Token expiry = “Never” and ads_management scope.

Please note: The user setting up the permanent token integration must have full access/full control permissions within Meta Business Suite. Depending on your privacy settings,

1. Create a new app

Navigate to Settings > Accounts > Apps in Meta Business Manager and click + Add.

Select Create a new app ID. (This will open a new tab in your browser. Leave your original tab open, as we will return to it later.)

Fill in the App name and App contact email (this should be your email address), and click Next.

 

On the next step, select the last option Other and click Next.

On the next step, select Business and click Next.

Select the Create App button.

Once the app is created, return to your original browser window

2. Create a System User

The next step is to create the system user.

In your business account, go to Settings > Users > System users, and hit the + Add button & accept the non-discrimination policy.

Input a System user name and select Admin as the System user role. Click Create system user.

3. Assign Assets to System User

Next we need to assign this user to your current Ad account. Select the actions button (the three dots) and Assign assets.

Select the appropriate Ad account and toggle Full control to on.

4. Assign the System user to your newly created app

Navigate back to the app you created, and select Assign people.

Select your new system user and toggle Full control. Click Assign people to complete.

5. Generate Permanent Access Token

Navigate back to the System Users tab. You should see the your ad account under the Assigned assets section. Click Generate Token.

Select all 4 necessary permissions

1. ads_management

2. business_management

3. pages_read_engagement

4. pages_show_list

Copy the token that is created.

Well done, now lets enable Meta Integration

• Log into your Pearl Diver account and open the Dashboard.

• Under Actions, select the Meta option.

• Toggle Enable to start the integration setup process.

60 Day Token

Step 1: Authorize Meta Integration

1. A new window will open to authorize the Meta integration
2. Log into the Meta account associated with the correct ad account. The account you choose must have full access to the ad account you want Pearl Diver to upload your audience data to. Click Continue as to log in.
3. Select the desired option for pages you want Pearl Diver to upload data and click Continue
   
4. Select the desired option for the business you want Pearl Diver to upload data and click Continue. It must be affiliated with the ad account you want the data to be sent to.
   
5. You will then be shown a review page of your chosen settings. Click Continue to proceed.
   
6. You will then be shown a confirmation page. Click Got It to proceed.
   
7. You will see a Pearl Diver confirmation screen. Please close this tab. 
   
   Once you have closed the Authorization Successful window, the dashboard page will retrieve a list of the ad accounts your chosen Meta account has access to.
8. In the Ad Account drop down below the Authorized as section, select the Meta ad account you would like to send the audience data to. Once selected, click Update.
   

❓How will Pearl Diver audiences be displayed in my Meta ad account?

1. Click on Audiences in the sidebar menu of your Meta Ads Manager account 
   
   
   
   
2. Your Pearl Diver audiences will be listed as shown below:
   
3. Click the Pearl Diver audience to see information about the audience and how it's being utilized. Navigate to the History tab to verify records have synced from Pearl Diver
   To utilize the audience data in an ad campaign, select the Pearl Diver audience you would like to use in the audience section when creating an ad set.
   

❓Should I use Many to One and One to One Mapping

When you authorize Meta Ads for the first time in Pearl Diver, the system defaults to 1:1 audience mapping. This is the recommended setting for sending multiple audiences to your Meta ad account to ensure you can identify the different audiences in Meta

❓What happens to existing audiences if:

Switching from Many to One to One to One: 

1. Identify all connected audiences.

2. For each connected audience:

   1. Create a corresponding audience/list/tag in Meta or Google if it doesn’t already exist.

   2. Map the Pearl Diver audience to the new destination audience.

Switching from One to One to Many to One:

1. Consolidate audiences in Meta/Google, and map all Pearl Diver audiences to the consolidated list.

Example Use Case in Pearl Diver:

User creates an audience in Pearl Diver with demographic filters and is named "High-Value Customers." With 1:1 mapping, a Custom Audience is automatically created in Meta Ads with the same name and will appear as "PDV | High Value Customers" in the audience section in your Meta ad account 

Switching Mapping:

User switches from many:1 to 1:1 mapping for Meta Ads.

Pearl Diver identifies existing audiences and creates new Custom Audiences in Meta for each Pearl Diver audience.

Updating On-Site Resolution Audience Filters:

User modifies the "High-Value Customers" audience in Pearl Diver (changes filters, adds demographic filter, etc). The updates will sync to the corresponding audience/list/tag in Meta or Google.

FAQs

❓How do I enable 1:1 Web audience mapping for the Meta ads action?

When you authorize Meta Ads for the first time in Pearl Diver, the system defaults to 1:1 audience mapping. Once authorization is complete, you can start adding audiences, and each audience in Pearl Diver will be mapped individually to Meta Ads using the naming format "PDV | [Audience Name]".

❓Where can I change the audience mapping settings?

You can modify the audience mapping settings on the Actions page under the Audience Mapping section.

❓What happens when I change my audience mapping from 1:1 to many:1?

When you switch from 1:1 mapping to many:1, Pearl Diver will:

1. Create (or update) a single audience/list in Meta Ads.

2. Use the naming convention “Pearl Diver” for the audience/list.

❓What happens when I switch from many:1 to 1:1 mapping?

When switching from many:1 to 1:1, Pearl Diver will:

1. Create new audiences/lists in Meta Ads for each audience already connected to the action (if they don’t already exist).

❓What happens if some audiences fail to be created when switching to 1:1?

1. If any audience creation fails, an appropriate error message will be displayed.

2. Pearl Diver will retry or prompt the user to manually verify the connection in Meta Ads.

❓What happens when I switch from 1:1 to many:1?

When switching from 1:1 to many:1, Pearl Diver will:

1. Merge all connected audiences into a single Meta Ads audience/list.

2. Use the naming convention: “Pearl Diver”.

❓What if an audience with the name ‘Pearl Diver’ already exists in Meta Ads?

Pearl Diver will update the existing “Pearl Diver” audience instead of creating a duplicate.

❓Will my existing audience data be lost during mapping changes?

No, audience data remains intact. Pearl Diver updates audiences dynamically in Meta Ads without deleting any data.