# Setup Guide

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

To connect Facebook Ads to DinMo, you need:

* An active **Meta Ads Manager** account with the following permissions for the accounts you'd like to sync:
  * An `ads_read` permission to sync Ads report information for any Ad accounts that you own or have been granted access to through this permission.
  * An `ads_management` permission to sync Ads accounts' metadata. This permission also requests the `id` and `account_timezone` fields of Ad accounts. The `account_timezone` field is required to save the correct report date in the destination.
  * A `business_management` permission is mandatory to ensure a successful setup. Without this permission, setup tests will fail.
* The breakdowns and fields you'd like to sync.

### Setup instructions <a href="#setupinstructions" id="setupinstructions"></a>

#### STEP 1: Begin DinMo configuration <a href="#beginfivetranconfiguration" id="beginfivetranconfiguration"></a>

1. In the connection setup form, enter the **Destination schema** name of your choice.
2. (Hybrid Deployment only) If your destination is configured for Hybrid Deployment, the Hybrid Deployment Agent associated with your destination is pre-selected in the **Select an existing agent** drop-down menu. To use a different agent, select the agent of your choice, and then select the same agent for your destination.
3. Select the **Authentication Method** you want to use:

   * Select **Grant User Access** to authorize through OAuth. Click **Authorize** to allow DinMo access to your Facebook Ads account using OAuth. We recommend this authentication method to most users because it bases the API's rate limit on the DinMo application instead of a user's advertising account. The DinMo application has a higher rate limit than a system user token. See our Facebook Ads troubleshooting article on rate limits for more information.

     We recommend logging in while in Incognito mode to ensure authorization of the correct account.
   * Select **Use System User Token** to authorize through a [System User Token](https://developers.facebook.com/docs/facebook-login/guides/access-tokens#usertokens). We recommend this authentication method to organizations that don't want to ask their end-users to grant user access. Such organizations may include digital marketing agencies or Powered by DinMo users.
     1. You must grant the [`ads_read`](https://developers.facebook.com/docs/permissions/reference/ads_read), [`ads_management`](https://developers.facebook.com/docs/permissions/reference/ads_management), and [`business_management`](https://developers.facebook.com/docs/permissions/reference/business_management) permissions while generating the system user token.
     2. In the **Access Token** field, enter your System User Token.
     3. Click **Validate system user access token** to validate the token permissions.

   The app for which you generated the system token must have the Standard or Advanced [access level](https://developers.facebook.com/docs/graph-api/overview/access-levels/). If the app has the default No Access level, the system user tokens generated for these apps can not query the Ads API. Note that requirements for each access level are managed by a third party and can be changed at any time. If you see sudden access level errors after the connection setup, check your [App review status](https://developers.facebook.com/docs/app-review) and make sure the requirements for the specified access level are met.
4. Select your sync mode:
   * Select **Sync All Accounts** to sync all accounts you have access to.
   * Select **Sync Specific Accounts** to sync specific accounts only. Use the **Accounts** list to add accounts you'd like to sync.

#### STEP 2: Set up custom report (Optional) <a href="#optionalsetupcustomreport" id="optionalsetupcustomreport"></a>

Before setting up a custom report, verify whether the data is available through the Facebook API. To do this, build the custom reports you require using the [Facebook Graph API Explorer](https://developers.facebook.com/docs/graph-api/guides/explorer/) and then replicate it in DinMo. The explorer indicates fields compatibility, any potential errors, and if the data you require is available.

Also, see our Facebook Ads custom reports documentation to learn about their limitations and view sample custom reports.

1. Click **+ Custom report** if you want to sync a custom report.
2. Enter the **Report name**. It must be unique within this connection.
3. Select the type of time Aggregation for the report.
4. (optional) Set the **Show Advanced Options** toggle to ON if you want to sync the optional fields.
5. (optional) Select an Action Report Time for the report.
6. (optional) Set the Click Attribution Window.
7. (optional) Set the View Attribution Window.
8. (optional) Set the Engaged-view Attribution Window.
9. (optional) Set the **Show Advanced Options** toggle to ON if you want the Facebook API to return your ads results using the unified attribution settings defined at the ad set level.
10. Click **Next**.
11. (optional) Select Breakdowns you want to include in the report.
12. (optional) Select Action Breakdowns you want to include in the report.
13. Add at least one field to finalize your report.

    To sync `conversions` and `actions` data, include the `action_type` field from the **Action Breakdowns** selection as well as the following fields:

    * For conversions: `conversions` and `actions` from the **Fields** selection.
    * For conversion values: `conversion_values` and `action_values` from the **Fields** selection. To avoid discrepancies, we recommend using a union of the two resulting child tables (e.g., `<table_name>_conversions` and `<table_name>_actions`).

    For more information on this configuration and the output of this data, see our Conversions and actions documentation.
14. Click **Save** to add your Custom report.

    Repeat the 14 steps above if you want to add another Custom report.

#### STEP 3: Finish DinMo configuration <a href="#finishfivetranconfiguration" id="finishfivetranconfiguration"></a>

1. In the **Historical Sync Time Frame** drop-down, select how many months' worth of reporting data you'd like to include in your initial sync.

   DinMo can only retrieve up to 37 months\` worth of data from Facebook Ads. This limitation is from the source side.
2. (Optional) Set the **Sync all metadata** toggle to OFF if you want to sync only report data without any metadata.
3. Click **Save & Test**. DinMo will take it from here and sync metadata and insights from your Facebook account.

Most API requests sent by Facebook Ads connections are sent between 3 a.m. and 7 a.m. (UTC). We recommend that you set the start time of your connection outside this high-load period. This action mitigates possible rate limit issues and optimizes sync time.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.dinmo.io/integrations/dinmo-ingest/meta-ads/setup-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.