How to Connect Your First Ad Account to Blueprint

Before You Begin

Before you can connect an ad platform to Blueprint, you need two things: an active Blueprint workspace and admin-level access to the ad account you want to connect. If you are managing client accounts through a manager account (like a Google Ads MCC), make sure your login has the appropriate permissions to grant third-party access to the underlying ad accounts.

Blueprint handles the entire OAuth handshake on your behalf. You will not need to generate API keys, create developer tokens, or configure any credentials manually. The only thing you provide is your ad platform login during the authorization step. Blueprint requests the minimum scopes necessary to pull campaign data, keyword metrics, and spend information -- it never requests write access to your campaigns unless you explicitly enable budget application features later.

Each workspace can connect multiple accounts across all three supported platforms. There is no limit to the number of connections per platform, and pricing is based on the total number of connected ad accounts, not the number of platforms you use. You can start with one account on the Free tier and add more as your needs grow.

Connecting Google Ads

From your Blueprint workspace, navigate to Settings → Connections and click Connect Google Ads. You will be redirected to Google's standard OAuth 2.0 consent screen, where you sign in with the Google account that has access to your ad accounts and approve the requested permissions. Blueprint requests offline access, which means Google issues both an access token and a refresh token. The refresh token allows Blueprint to continue syncing your data indefinitely without requiring you to re-authorize.

Once authorization is complete, Blueprint runs an account discovery process using the Google Ads API's CustomerService.listAccessibleCustomers endpoint. This returns every Google Ads account your login can access, including those nested under MCC (manager) accounts. Blueprint automatically filters out manager accounts and only presents individual ad accounts for selection, since manager accounts do not contain campaign data themselves. You will see each discovered account listed with its name, customer ID, and current status.

Select the accounts you want to track and Blueprint immediately begins the initial data sync. Google Ads connections are the most straightforward of the three platforms because Google's refresh token mechanism means the connection essentially never expires. As long as you do not revoke Blueprint's access from your Google account settings, the connection will persist indefinitely with no manual intervention.

Connecting Microsoft Ads

Click Connect Microsoft Ads from the Connections page. Microsoft uses Azure AD for OAuth authentication, so you will see a standard Microsoft sign-in prompt. Enter the credentials for the Microsoft account that manages your advertising, and approve the permission request. Like Google, Microsoft issues a refresh token that allows Blueprint to maintain access without repeated authorization.

Microsoft's account discovery is slightly more involved than Google's. Blueprint uses a hybrid SOAP and REST approach to enumerate your ad accounts. The initial authentication call extracts your CustomerId from the response headers, which Blueprint then uses to query the Customer Management API for all accounts associated with your profile. The discovery process filters accounts by status, returning only those marked as Active or Paused -- suspended or draft accounts are excluded since they do not have actionable data.

One detail worth noting: Microsoft Ads requires a developer token for API access, but Blueprint already holds an approved token. You do not need to apply for one yourself. This is a common point of confusion for teams migrating from other tools that required manual token setup. With Blueprint, the Microsoft connection is a single click-and-authorize flow, just like Google.

Connecting Meta Ads

Meta Ads connections work through Facebook Login and the Meta Graph API. Click Connect Meta Ads to initiate the OAuth flow. You will be directed to Facebook's authorization screen, where you sign in with the Facebook account that has access to your ad accounts. Approve the requested permissions and you will be redirected back to Blueprint.

Meta's token lifecycle is fundamentally different from Google and Microsoft. Facebook Login initially issues a short-lived token that lasts only a few hours. Blueprint automatically exchanges this for a long-lived token using Meta's token exchange endpoint, extending the validity to approximately 60 days. However, Meta does not support refresh tokens the way Google and Microsoft do. When the long-lived token approaches expiration, Blueprint cannot silently renew it -- you will need to re-authorize.

Blueprint tracks token expiration dates for every Meta connection and surfaces an EXPIRING_SOON warning in your Connections panel when a token has 7 days or fewer remaining. This gives you ample time to re-authorize before data syncing is interrupted. During account discovery, Blueprint queries the Graph API for all ad accounts accessible to your login and handles the act_ prefix that Meta prepends to account IDs internally, so the accounts display with clean, readable identifiers in your workspace.

If you manage multiple clients through a Meta Business Manager, all of those ad accounts will appear during discovery. Select the ones you want to track, and Blueprint begins syncing immediately.

What Happens After Connection

The moment you connect an ad account, Blueprint kicks off a background sync job using its BullMQ-based job queue. The initial sync pulls historical data for campaigns, ad groups, keywords, and daily spend records. These background workers run with concurrency limits and rate-limit awareness so they never exceed the ad platform's API quotas.

After the initial pull, Blueprint maintains an ongoing sync schedule tailored to each data type. Campaign and keyword data for Google Ads and Microsoft Ads syncs every 6 hours, which keeps your dashboards current without hammering the APIs. Search term reports, which are heavier API calls, sync on a 7-day cadence. Quality Score snapshots are captured approximately every 3 days and stored in TimescaleDB hypertables for historical trend analysis. Meta Ads data follows a similar schedule, though the specific sync intervals may differ slightly due to Graph API rate limits.

All synced data flows directly into your Blueprint dashboards. Budget pacing calculations, AI-powered anomaly detection, quality score trend charts, and search term analysis all begin working as soon as the first data lands. There is no separate "processing" step or waiting period. Your workspace reflects the most recent sync data at all times, and each metric card shows the timestamp of its last successful update.

Managing Connections

You can view and manage all of your ad platform connections from Settings → Connections. Each connection displays its platform type, the associated account name and ID, the connection status, and the last successful sync timestamp. Connections can be in one of several states: ACTIVE (syncing normally), EXPIRING_SOON (Meta tokens approaching the 60-day limit), EXPIRED (token no longer valid), or ERROR (sync failures due to API issues).

For Google and Microsoft connections, you should rarely need to take any manual action. These platforms use refresh tokens that persist indefinitely unless explicitly revoked. If you change your ad platform password or revoke Blueprint's access from your Google or Microsoft account settings, the connection will transition to an ERROR state. In that case, click Reconnect to re-authorize and restore the sync.

Meta connections require more active management due to the 60-day token lifecycle. When you see the EXPIRING_SOON badge, click Reconnect to go through the Facebook Login flow again. Blueprint exchanges the new short-lived token for a fresh long-lived token, resetting the 60-day clock. If you miss the window and the token expires, no data is lost -- Blueprint simply pauses syncing until you re-authorize, then resumes from where it left off.

Only workspace Owners and Managers can add, remove, or reconnect ad platform connections. Analysts and Viewers can see connection status but cannot modify connections. This ensures that credential management stays with the people who should be handling it.