Overview
Meta's advertising platform — covering Facebook, Instagram, Messenger, and the Audience Network — is one of the most significant digital advertising channels available, with sophisticated targeting capabilities, broad audience reach, and a comprehensive API that enables programmatic campaign management and performance data retrieval. For marketing agencies, performance marketers, e-commerce businesses, and advertising technology companies, the Meta Marketing API is the integration point that connects custom tools, automated reporting systems, campaign management platforms, and analytics infrastructure to Meta's advertising ecosystem.
The Meta Marketing API is a REST API built on the Graph API framework — Meta's unified API layer for accessing Facebook platform data. Every object in Meta's advertising system — ad accounts, campaigns, ad sets, ads, creatives, audiences — is a node in the Graph with properties and connections to other nodes. Reading advertising data means querying graph nodes and their edges; writing advertising data means creating and updating nodes. Understanding the Graph API's structure — how objects relate to each other, how the hierarchy from ad account to campaign to ad set to ad works, and how the fields and edges system gives access to data — is the foundation for effective Meta Marketing API integration.
Meta's advertising API also includes capabilities beyond campaign management and reporting: the Conversions API for server-side event tracking (replacing and supplementing the pixel), the Audience API for programmatic custom and lookalike audience management, the Lead Ads API for retrieving lead form submissions, and the Business Management API for managing business assets across accounts. Each of these serves distinct integration use cases that marketing technology stacks commonly require.
We build Meta Marketing API integrations for marketing agencies, e-commerce businesses, performance marketing teams, and advertising technology companies that need to connect their systems to Meta's advertising platform for reporting, campaign automation, audience management, and conversion tracking.
What Meta Ads Integration Covers
Meta Marketing API authentication. Meta's API uses the Graph API authentication model — access tokens that represent the permissions granted to an application by a user or system.
App registration: Meta app registration at developers.facebook.com, creating the app that the integration operates under. The app ID and app secret used in token generation and API calls. The app review process for permissions that require Meta's approval before the integration can use them with real advertiser accounts.
System user tokens: the recommended authentication approach for server-to-server integrations that do not involve user interaction. A system user is created in Meta Business Manager, granted access to the relevant ad accounts with the appropriate permission level (Standard for reporting, Admin for campaign management), and a system user access token is generated that does not expire. The system user token stored securely and used in all API calls — the long-lived token that does not require periodic refresh for server-side integrations.
User access tokens: the OAuth 2.0 access tokens obtained through the user-facing login flow — used for integrations where the end user authorises the application to access their Meta advertising data. Access tokens expire after 60 days and require the long-lived token exchange that extends the token lifetime from 1 hour to 60 days. The ads_read permission for reading advertising data, ads_management for creating and managing ads, business_management for business-level operations.
API version management: Meta's Marketing API is versioned, with new versions released periodically and old versions deprecated after a migration window. The API version specified in the URL path (/v20.0/...). The version management that pins integrations to a specific API version and handles the migration when the pinned version approaches deprecation.
Campaign and ad reporting. The reporting capabilities that provide performance data for campaigns, ad sets, and ads.
Insights API: the /{object_id}/insights endpoint for performance data across any level of the campaign hierarchy — account-level, campaign-level, adset-level, or ad-level. The fields parameter for selecting which metrics to retrieve — impressions, reach, frequency, clicks, ctr, cpc, cpm, spend, actions (for conversion events), action_values (for conversion revenue), cost_per_action_type. The date_preset parameter for predefined date ranges (today, yesterday, last_7d, last_14d, last_28d, last_30d, last_month, this_month, this_year) or the time_range parameter for custom date ranges.
Breakdowns: the breakdowns parameter for segmenting insights data by dimension — age, gender, country, region, impression_device (mobile, desktop), publisher_platform (facebook, instagram, audience_network, messenger), platform_position (feed, right_hand_column, instant_article, marketplace, etc.), device_platform. The dimension breakdown that disaggregates aggregate performance into the segments that audience analysis requires.
Async reports: for large data requests — many ad objects over long date ranges — the async report endpoint that creates a report job and returns a report_run_id. The polling loop that checks /{report_run_id} until the report status is Job Completed, then retrieves the data from the result URL. The async approach that avoids timeout failures for large reporting queries.
Attribution windows: Meta's attribution windows for conversion reporting — the lookback window after an ad impression or click within which a conversion is attributed to the ad. The action_attribution_windows parameter that specifies which attribution windows to report on — 1d_click, 7d_click, 28d_click, 1d_view, 7d_view, 28d_view. The attribution window alignment that ensures reported conversions match the advertiser's expected attribution model.
Campaign management API. Creating and updating campaigns, ad sets, and ads programmatically.
Campaign creation: the POST /{ad_account_id}/campaigns endpoint for creating campaigns. The campaign object with name, objective (OUTCOME_TRAFFIC, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_APP_PROMOTION, OUTCOME_AWARENESS), status (ACTIVE, PAUSED), special_ad_categories (NONE, or the special category for housing, employment, credit, or social issues ads), and the campaign budget optimisation settings.
Ad set creation: the POST /{ad_account_id}/adsets endpoint for creating ad sets. The ad set object with name, campaign_id, targeting (the detailed targeting specification), billing_event (IMPRESSIONS, LINK_CLICKS, APP_INSTALLS, etc.), optimization_goal, bid_strategy, daily_budget or lifetime_budget, start_time and end_time for scheduled ad sets. The complex targeting specification that defines the audience — geo_locations, age_min, age_max, genders, interests, behaviors, custom_audiences references, excluded_custom_audiences.
Ad creation: the POST /{ad_account_id}/ads endpoint for creating ads. The ad with name, adset_id, creative (either a creative_id reference to an existing creative or an inline creative specification), and status.
Ad creative: the POST /{ad_account_id}/adcreatives endpoint for creating reusable ad creatives. The creative object with the format-specific properties — object_story_spec for link ads, carousel ads, and collection ads; asset_feed_spec for dynamic creative; video_id for video ads. The link data with the message, link, description, image_hash or image_url, and the call-to-action button configuration.
Status updates: the POST /{campaign_id}, POST /{adset_id}, POST /{ad_id} endpoints for updating object properties including status changes — pausing or activating campaigns, ad sets, and ads.
Batch requests: the POST /v{version}/ batch endpoint that allows up to 50 API calls to be made in a single HTTP request. The batch request that significantly reduces the number of HTTP round trips for operations that touch many objects — updating the status of 50 ad sets in a single batch request rather than 50 individual requests.
Custom Audiences API. Programmatic management of custom audiences for retargeting and lookalike creation.
Custom audience creation: the POST /{ad_account_id}/customaudiences endpoint for creating custom audiences. The custom audience types — CUSTOM (customer list upload), WEBSITE (pixel-based), APP (app event-based), OFFLINE_CONVERSION (offline event-based), ENGAGEMENT (Facebook/Instagram engagement-based). The customer list custom audience that uploads hashed customer data (email, phone, name) for matching against Meta's user base.
Customer list upload: the POST /{custom_audience_id}/users endpoint for adding users to a customer list custom audience. The hashed data payload — SHA256 hashes of email addresses, phone numbers, first names, last names, and other matchable fields. The normalisation and hashing that must be applied before uploading — lowercase, stripped of whitespace for emails; country code prepended, stripped of symbols for phone numbers. The schema that describes the fields being uploaded — EMAIL, PHONE, FN (first name), LN (last name), ZIP, COUNTRY, BIRTH_YEAR.
Lookalike audience creation: the POST /{ad_account_id}/customaudiences endpoint with subtype set to LOOKALIKE. The lookalike specification with the source audience (origin_audience_id), the country, and the ratio (0.01 to 0.20 for the lookalike percentage of the country's population).
Audience size and status: the GET /{custom_audience_id} endpoint for checking audience delivery status and approximate size — the approximate_count that indicates how many users are in the audience, useful for confirming that uploaded audiences have matched sufficient users to be deliverable.
Meta Conversions API. Server-side event sending that complements or replaces the browser-based Meta Pixel.
Conversions API endpoint: the POST /{pixel_id}/events endpoint for sending conversion events from the server to Meta. The event payload with the event_name (Purchase, Lead, AddToCart, ViewContent, CompleteRegistration, etc.), the event_time in Unix timestamp, the event_source_url, the action_source (website, app, physical_store, chat, phone_call, email), and the user_data object with hashed customer identifiers.
User data for matching: the hashed customer data in the user_data object — em (SHA256 hashed email), ph (SHA256 hashed phone), fn (SHA256 hashed first name), ln (SHA256 hashed last name), ct (SHA256 hashed city), st (SHA256 hashed state/province), zp (SHA256 hashed postal code), country (SHA256 hashed 2-letter country code), db (SHA256 hashed date of birth in YYYYMMDD format), ge (SHA256 hashed gender), client_ip_address, client_user_agent, fbc (Facebook click ID from the _fbc cookie), fbp (Facebook browser ID from the _fbp cookie). More user data fields improve matching accuracy and event attribution quality.
Custom data: the custom_data object in the event payload for purchase and other value-bearing events — currency, value (the revenue value of the conversion), content_ids (product IDs for product-specific conversions), content_type, num_items, order_id. The order ID deduplication that prevents the same purchase from being counted twice when both the Pixel and the Conversions API fire for the same event.
Event deduplication: the event_id parameter in the Conversions API event payload that matches the eventID parameter in the browser Pixel event. Meta uses the event_id to deduplicate events when both browser and server sources fire for the same user action — critical for measuring accurate conversion rates when both sources are active.
Test events: the test_event_code parameter for testing Conversions API events against Meta's test event tool in Events Manager — confirming that events are being received and matched correctly before going live.
Lead Ads API. Retrieving lead form submissions from Meta Lead Ads.
Lead retrieval: the /{lead_ad_id}/leads endpoint for retrieving leads from a specific lead ad. The /{form_id}/leads endpoint for retrieving all leads submitted to a specific lead form. The lead object with the id, created_time, ad_id, ad_name, adset_id, adset_name, campaign_id, campaign_name, form_id, and the field_data array of name-value pairs for each form field the lead submitted.
Webhook for real-time lead delivery: configuring a webhook in Meta's developer portal to receive lead submissions in real time rather than polling — the leadgen webhook event that fires when a new lead is submitted. The webhook payload with the leadgen_id that the integration uses to retrieve the full lead data via the API.
Pagination: lead retrieval uses cursor-based pagination — the cursors.after value from the response's paging object used as the after parameter in the next request. The pagination loop that retrieves all leads without missing any when the total count exceeds the page size.
Facebook Page and Instagram Business API. Social media data for organic performance reporting alongside paid advertising.
Page insights: the /{page_id}/insights endpoint for Facebook Page performance data — page reach, engagement, impressions, fan growth, and post-level performance. The organic and paid breakdown for pages that run ads alongside organic content.
Instagram business insights: the /{ig_user_id}/insights endpoint for Instagram business account metrics — follower growth, reach, impressions, and the post-level insights for each piece of content.
Rate Limit Management
Meta's Marketing API enforces rate limits that production integrations must respect.
Business Use Case (BUC) rate limits: the primary rate limiting mechanism for the Marketing API — each ad account has a rate limit allocation based on the account's spend tier. The allocation is expressed as a percentage consumed, with 100% being the limit. The X-Business-Use-Case-Usage response header that reports the current percentage consumed for each business use case. The rate limit management that monitors this header and throttles requests when approaching the limit.
App-level rate limits: the X-App-Usage header for application-level rate limits that apply across all users and accounts using the same app. The application-level limit that caps total API call volume regardless of per-account limits.
Retry-After: the Retry-After response header included with 429 responses that indicates when the rate limit resets. The exponential backoff with respect for the Retry-After value that prevents aggressive retrying that would further exhaust the rate limit.
Technologies Used
- Python — Meta Marketing API integration for reporting pipelines, campaign automation, and analytics workflows using the
facebook-python-business-sdk - TypeScript / Node.js — Meta Marketing API integration for web-based marketing tools and dashboards using the
facebook-nodejs-business-sdk - C# / ASP.NET Core — Meta Marketing API integration for .NET marketing platforms and reporting systems
- Rust / Axum — high-performance Conversions API event processing and reporting data pipelines
- OAuth 2.0 / System User Tokens — Meta Marketing API authentication
- REST / HTTP / Graph API — Meta Marketing API communication
- Webhooks — real-time lead ad and conversion event delivery
- SHA256 — user data hashing for Conversions API and custom audience uploads
- SQL (PostgreSQL / MySQL) — ad performance data storage, campaign configuration, attribution data
- Redis — rate limit state management, caching of frequently accessed campaign data
- Google BigQuery — large-scale Meta advertising data warehouse for cross-channel analytics
- Hangfire / scheduled jobs — scheduled performance data retrieval, campaign synchronisation
- Docker — containerised integration service deployment
- GitHub Actions — CI/CD pipeline for integration service deployment
Meta Ads in the Marketing Technology Stack
For performance marketers and marketing agencies, Meta is one component of the multi-channel marketing technology stack alongside Google Ads, LinkedIn, TikTok, and other advertising platforms. The Meta Marketing API integration in this context is one channel connector in a broader campaign management and reporting infrastructure — the connector that retrieves Meta performance data and normalises it into the unified format that cross-channel reporting requires, alongside the Google Ads API connector, the LinkedIn Marketing API connector, and the other channel-specific integrations.
The Conversions API integration is increasingly critical as browser-based tracking becomes less reliable due to ad blockers, cookie deprecation, and iOS privacy changes. Server-side conversion tracking through the Conversions API provides the signal quality that Meta's ad delivery optimisation depends on — without complete conversion signals, Meta's algorithm cannot optimise campaign delivery effectively.
Meta Advertising Data, Connected to Your Marketing Stack
Meta Marketing API integrations built to production standards — correct system user token management, comprehensive Insights API queries with proper attribution window handling, robust Conversions API event sending with deduplication, custom audience management for retargeting infrastructure, and the rate limit management that keeps the integration operating without disruption.