.png)
Facebook Marketing API Integration Guide
Connect Meta advertising accounts, campaigns, leads, audiences, media, and Insights with enterprise systems through versioned Graph API requests, selected webhooks, and scheduled workflows.
Facebook Marketing API integration options at a glance
The Facebook Marketing API is delivered through Meta's versioned Graph API, using HTTPS requests and JSON responses to manage Ad Accounts, Campaigns, Ad Sets, Ads, Ad Creatives, audiences, media, and Insights. Selected Meta objects and events can produce webhook notifications, although coverage is not universal. Martini can consume these REST endpoints, handle cursor-based pagination, submit batch or asynchronous Insights requests, poll reporting jobs, and map results into enterprise applications or data platforms. Secure workflows can use Meta user or system-user access tokens stored as secrets. Scheduled reconciliation complements webhooks where real-time coverage is incomplete, while media workflows can call documented image and video upload endpoints.
| Integration point | Supported by Facebook Marketing API? | Common use cases | How Martini supports it |
|---|---|---|---|
| Graph API REST endpoints | Yes | Read and manage Ad Accounts, Campaigns, Ad Sets, Ads, Ad Creatives, audiences, leads, and other supported advertising resources using versioned HTTPS and JSON operations. | Martini can consume the versioned Graph API through REST workflows, parameterize fields and filters, paginate collection edges, and map responses to target systems. |
| Authentication and permissions | Yes | Authenticate with OAuth-derived user access tokens, system-user tokens, app tokens where appropriate, and required permissions such as ads_read, ads_management, and business_management. | Martini can store tokens in secrets, configure authenticated API requests, and keep environment-specific credentials separate from workflow logic. |
| Webhooks and outbound callbacks | Limited | Receive notifications for selected Meta products, objects, and fields, including supported lead-generation and Page-related events. Coverage does not extend to every Marketing API object or state transition. | Martini can receive supported webhook notifications, validate and route them, then call the Graph API to retrieve current resource details. |
| Batch requests | Yes | Submit multiple Graph API operations in one HTTP request to reduce network overhead. Individual operations can still fail independently. | Martini can construct batch requests, inspect each operation result, separate successful and failed items, and apply targeted retry or error handling. |
| Asynchronous Insights | Yes | Run large Insights reports asynchronously, poll report jobs, and retrieve completed performance data for Campaign, Ad Set, Ad, or other supported levels. | Martini can submit the job, persist its identifier, poll with bounded backoff, process paginated results, and write normalized metrics to a destination. |
| Media upload APIs | Limited | Upload advertising images and videos and reference processed media in Ad Creatives. These endpoints are not general-purpose file storage and processing behavior varies by endpoint. | Martini can send media to documented upload endpoints, track returned IDs and processing states, and orchestrate subsequent creative operations. |
| Insights analytics access | Yes | Retrieve advertising performance metrics, breakdowns, date ranges, and attribution-sensitive reporting through the Insights API. | Martini can schedule incremental reporting, transform nested JSON and breakdowns, and reconcile recent historical windows for late-arriving changes. |
| SDKs and generated tooling | Yes | Use Meta-supported SDKs or generated tooling for supported languages and API versions where application code is preferred. | An external SDK is not required for Martini workflows because Martini can consume the HTTPS Graph API directly; custom code can be used only when additional flexibility is needed. |
How Facebook Marketing API exposes data and business events
Facebook Marketing API REST APIs
The Marketing API is exposed through Meta's versioned Graph API. It uses HTTPS requests, JSON responses, graph-style object IDs and edges, field selection, filters, date ranges, and cursor-based pagination to read and manage supported advertising resources.
Martini implementation pattern
Martini implementation pattern: A workflow authenticates with a securely managed Meta token, calls the required Graph API endpoint, follows pagination links or cursors, maps the JSON response, applies business rules, and writes an idempotent result to the target system. API version and account configuration remain environment-managed values.
Implementation sequence
Facebook Marketing API Webhooks
Meta Webhooks provides notifications for selected products, objects, and fields, including supported lead-generation and Page-related scenarios. Notifications are selective and generally indicate that something changed rather than containing a complete source record.
Martini implementation pattern
Martini implementation pattern: A Martini webhook-facing workflow receives and validates the notification, identifies the relevant Page, lead, or advertising resource, and performs a follow-up Graph API read using the required permissions. The workflow stores the event identifier and processing status so retries do not create duplicate downstream data.
Implementation sequence
Facebook Marketing API Async Insights
Meta supports asynchronous Insights reporting for large queries. A client submits a report request, waits for the job to complete, and retrieves the resulting performance data, subject to API version, permissions, and report configuration.
Martini implementation pattern
Martini implementation pattern: A scheduled workflow submits an asynchronous Insights request, stores the job identifier, polls with bounded backoff, handles failure or delayed states, then retrieves and transforms the completed report. A recent overlap window can be reprocessed because attribution results may change after the initial report.
Implementation sequence
Facebook Marketing API Batch Requests
Graph API batch requests allow multiple operations to be submitted in a single HTTP request. The batch reduces network overhead, but each operation can produce its own success or failure result.
Martini implementation pattern
Martini implementation pattern: A Martini workflow builds a bounded batch from independent resource requests, submits it to Meta, parses each operation result, and routes failures separately from successful responses. Failed operations can be retried according to status and error type without replaying successful operations.
Implementation sequence
Facebook Marketing API Media Uploads
Meta provides advertising image and video operations for creative workflows. Uploaded media can require processing before it is available for use in an Ad Creative, and limits and supported formats vary by endpoint.
Martini implementation pattern
Martini implementation pattern: A Martini workflow obtains the source media, calls the applicable Meta upload endpoint, stores the returned media identifier, and checks processing status before continuing to creative creation or update. Failures and unsupported formats are routed to an operational error path.
Implementation sequence
Common Facebook Marketing API integration patterns
Pattern 1: Synchronize advertising assets to a data platform
When to use this pattern
Use this pattern when planning, reporting, or governance teams need a durable copy of Ad Accounts, Campaigns, Ad Sets, Ads, and Ad Creatives. Scheduled reconciliation is appropriate because not every advertising change has universal webhook coverage.
Integration direction
Example Mapping
| Facebook Marketing API Field | Canonical Field | Target Field |
|---|---|---|
| id | sourceObjectId | meta_object_id |
| name | assetName | campaign_name |
| status | lifecycleStatus | status |
| campaign_id | parentCampaignId | campaign_id |
Martini implementation pattern
A scheduled Martini workflow reads configured Ad Accounts, follows cursor-based pagination, maps each object to a canonical advertising model, and upserts rows using stable Meta IDs. It records checkpoints, validates required relationships, and retries transient API failures without duplicating successful writes.
Martini capabilities used
- workflows
- scheduled triggers
- API consumption
- data mapping
- business rules
- error handling
Pattern 2: Load asynchronous Insights reports
When to use this pattern
Use this pattern for large or attribution-sensitive performance reports that should be loaded into a warehouse or reporting application. It supports Campaign, Ad Set, Ad, and other levels available to the configured Insights request.
Integration direction
Example Mapping
| Facebook Marketing API Field | Canonical Field | Target Field |
|---|---|---|
| date_start | reportStartDate | report_date |
| campaign_id | campaignId | campaign_id |
| spend | advertisingSpend | spend |
| impressions | impressionCount | impressions |
Martini implementation pattern
Martini submits an asynchronous Insights job, persists the job identifier, polls with bounded backoff, retrieves paginated results, and transforms breakdowns into warehouse rows. The workflow reprocesses a recent overlap window to account for late attribution and records report configuration for auditability.
Martini capabilities used
- workflows
- scheduling
- API consumption
- asynchronous orchestration
- data mapping
- retry handling
Pattern 3: Synchronize Meta leads with a sales application
When to use this pattern
Use this pattern when a supported Meta lead-generation event should create or update a lead in Salesforce or HubSpot. Webhook availability and permissions must be confirmed for the specific Page and form configuration.
Integration direction
Example Mapping
| Facebook Marketing API Field | Canonical Field | Target Field |
|---|---|---|
| id | sourceLeadId | Meta_Lead_ID__c |
| created_time | submittedAt | CreatedDate |
| field_data | leadFields | Lead fields |
| page_id | sourcePageId | LeadSourcePageId |
Martini implementation pattern
Martini receives the selected webhook notification, validates the event, retrieves the current Lead through the Graph API, and maps the returned field data to the sales application. It applies consent and duplicate rules, uses the Meta Lead ID as an idempotency key, and retains replay status for operational recovery.
Martini capabilities used
- webhook consumption
- workflows
- API consumption
- data mapping
- validation
- idempotency and error handling
Pattern 4: Activate approved customer segments as Custom Audiences
When to use this pattern
Use this pattern when a CRM, commerce platform, or data warehouse provides an approved customer segment for advertising activation. The design should include consent, hashing, suppression, and reconciliation controls where applicable.
Integration direction
Example Mapping
| Facebook Marketing API Field | Canonical Field | Target Field |
|---|---|---|
| customer_id | customerIdentifier | audience_match_identifier |
| emailAddress | hashed_email | |
| segment_status | membershipStatus | audience_membership_action |
| consent_status | marketingConsent | eligibility_rule |
Martini implementation pattern
Martini retrieves approved segment membership, filters records according to consent and lawful-use rules, applies the required transformation or hashing, and submits the result through the applicable Meta audience workflow. It records upload status, handles removals or suppressions, and reconciles source membership with Meta state.
Martini capabilities used
- workflows
- API consumption
- data transformation
- business rules
- secrets management
- error handling
Applications commonly integrated with Facebook Marketing API
Facebook Marketing API integrations commonly connect advertising operations with sales, commerce, analytics, finance, and enterprise workflow applications. The exact flow depends on the Meta assets, permissions, API version, and capabilities enabled for the organization.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Synchronize Meta lead-generation submissions with Salesforce Leads or Contacts and optionally send approved customer segments for audience activation. | Facebook Marketing API → Martini → Salesforce | Martini can receive supported Meta webhook notifications, retrieve the current Lead through the Graph API, apply consent and deduplication rules, and upsert the result into Salesforce. A separate scheduled workflow can prepare approved audience data for Meta. |
| HubSpot | Route Meta lead-generation data into HubSpot and use approved marketing segments in audience activation workflows. | Facebook Marketing API → Martini → HubSpot | A Martini workflow can validate a selected Meta notification, retrieve lead details, map fields to HubSpot properties, and perform an idempotent write. Outbound audience workflows can transform approved segment membership before sending it to Meta. |
| Shopify | Coordinate product or catalog data, advertising activity, and commerce reporting across Meta and Shopify. | Shopify → Martini → Facebook Marketing API | Martini can retrieve or receive approved Shopify product data, transform it for the applicable Meta catalog workflow, and separately load Meta Insights into a commerce reporting store. Exact catalog behavior depends on the Meta product configuration. |
| Google Ads | Consolidate Meta and Google Ads campaign performance for cross-channel reporting, attribution, and budget analysis. | Facebook Marketing API → Martini → Google Ads | Martini can retrieve Meta Insights and Google Ads data through their respective APIs, normalize campaign dimensions and metrics, and write both datasets to a shared reporting model. This is generally a reporting integration rather than a direct operational dependency between the advertising platforms. |
| Snowflake | Centralize Campaign, Ad Set, Ad, and Insights data for attribution, forecasting, and cross-channel analytics. | Facebook Marketing API → Martini → Snowflake | Scheduled Martini workflows can paginate Meta objects, submit asynchronous Insights jobs for large ranges, normalize metrics and breakdowns, and load results into Snowflake with stable Meta IDs and overlap-window reconciliation. |
| BigQuery | Store advertising Insights and operational audience data for dashboards and analytical workloads. | Facebook Marketing API → Martini → BigQuery | Martini can retrieve completed Insights results, transform nested JSON and reporting dimensions into analytical rows, and write them to BigQuery. Checkpoints, report identifiers, and recent-window reprocessing help manage late attribution changes. |
| ServiceNow | Route access requests, integration failures, and advertising-platform operational exceptions into enterprise workflow management. | Facebook Marketing API → Martini → ServiceNow | Martini can classify Meta API failures or authorization exceptions, enrich them with Ad Account and workflow context, and call ServiceNow APIs to create or update incidents and requests. Retry and correlation keys prevent duplicate operational tickets. |
| NetSuite | Combine advertising spend and performance metrics with financial or campaign-cost reporting. | Facebook Marketing API → Martini → NetSuite | A scheduled Martini workflow can retrieve Meta Insights, map campaign and spend dimensions to the organization's NetSuite model, validate accounting-period rules, and write the result to NetSuite or an intermediate financial data platform. |
How to build a Facebook Marketing API integration in Martini
Objective
Configure the Meta API version, Ad Account scope, access token type, permissions, and environment-specific secrets before building resource workflows.
Instructions in Martini
- Use a user or system-user access token appropriate to the operation
- Store tokens and sensitive configuration in Martini secrets
- Confirm Business Manager, Ad Account, Page, audience, or lead asset assignments
- Keep the Meta API version configurable
Objective
Select a webhook, schedule, or API invocation based on the required freshness and the coverage available for the relevant Meta object or event.
Instructions in Martini
- Use supported Meta webhook notifications for selected event-driven flows
- Use scheduled workflows for reporting, reconciliation, and unsupported change coverage
- Use an API-triggered workflow when another system needs controlled execution
- Combine webhooks with periodic reconciliation where necessary
Objective
Call the relevant Graph API resource and retrieve complete source data while respecting pagination, permissions, and asynchronous job behavior.
Instructions in Martini
- Request only the fields required by the integration
- Follow cursor-based pagination until completion
- Persist asynchronous Insights job identifiers
- Retrieve current resource data after webhook notifications
Objective
Coordinate API calls, polling, enrichment, conditional routing, and downstream writes as a maintainable Martini workflow.
Instructions in Martini
- Separate notification intake from follow-up resource retrieval when appropriate
- Route transient failures to bounded retry handling
- Use correlation identifiers across API calls and target writes
- Keep successful and failed batch operations distinct
Objective
Transform Meta JSON objects, nested field data, metrics, and breakdowns into the canonical target model before applying business rules.
Instructions in Martini
- Map stable Meta IDs to source identifiers
- Validate required fields and relationships
- Normalize dates, metrics, statuses, and reporting dimensions
- Handle optional fields by API version and asset configuration
Objective
Persist advertising assets, leads, Insights, audiences, or operational exceptions in target applications using deterministic upsert and reconciliation logic.
Instructions in Martini
- Use stable Meta IDs or report dimensions as idempotency keys
- Apply consent and suppression rules for customer and audience data
- Write to warehouses, sales applications, financial systems, or workflow platforms
- Record checkpoints and processing status
Common Facebook Marketing API data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Ad Account | Owns campaigns, ad sets, ads, billing configuration, and account-level reporting context. | Snowflake, BigQuery, Salesforce, NetSuite | Martini retrieves Ad Account details and identifiers, applies permission-aware configuration, and uses the account ID as the scope for downstream workflows and reconciliation. |
| Campaign | Groups advertising activity around an objective and contains related Ad Sets. | Planning applications, data warehouses, Salesforce, NetSuite | Martini paginates Campaign edges, maps objectives and status fields, and upserts using the stable Meta object ID while tolerating optional fields. |
| Ad Set | Defines targeting, budget, schedule, optimization, and delivery configuration within a Campaign. | Data warehouses, planning applications, reporting platforms | Martini transforms nested targeting and delivery attributes, validates required destination fields, and links the object to its Campaign using Meta identifiers. |
| Ad | Represents the deliverable advertising unit associated with an Ad Set and Ad Creative. | Data warehouses, campaign management applications, reporting platforms | Martini retrieves Ads with selected fields, maps status and relationship identifiers, and applies deterministic upsert and error handling rules. |
| Ad Creative | Contains advertising content and configuration such as media, copy, links, and creative metadata. | Creative repositories, campaign planning applications, data warehouses | Martini can map creative metadata and coordinate media upload IDs with later creative operations, including processing-state checks. |
| Insights | Provides performance reporting for campaigns, ad sets, ads, and other supported dimensions. | Snowflake, BigQuery, Google Ads reporting layers, NetSuite | Martini submits synchronous or asynchronous requests as appropriate, polls jobs, handles pagination, normalizes breakdowns, and reprocesses an overlap window for attribution changes. |
Authentication and security considerations
Token-based access
Facebook Marketing API uses Meta's Graph API authentication model. User access tokens, system-user access tokens, and other token types are subject to the operation, permissions, and asset assignments available to the token holder.
Permissions and asset assignments
Permissions such as ads_read, ads_management, and business_management do not replace the need for access to the relevant Business Manager, Ad Account, Page, audience, or lead asset.
Secrets and data protection
- Store Meta access tokens in Martini secrets rather than workflow code or client-side applications.
- Plan for token expiry, revocation, permission changes, and environment-specific credentials.
- Protect lead, audience, and customer data with access controls, retention rules, encryption, and applicable consent controls.
- Validate webhook requests and retain sufficient event context for replay and audit.
Operational considerations for Facebook Marketing API integrations
Rate limits and pagination
Meta applies usage controls, and Graph API collections commonly use cursor-based pagination. Limit concurrency, request only needed fields, inspect errors and response signals, and persist progress for long-running synchronizations.
Asynchronous reporting
Large Insights requests require job polling with bounded backoff. Persist job identifiers, handle failed or delayed states, and avoid treating initial reporting results as immutable.
Idempotency and reconciliation
Use Meta object IDs, Lead IDs, report dimensions, date ranges, and source keys to prevent duplicates. Combine selected webhooks with scheduled reconciliation because webhook coverage is not universal.
Schema and media changes
API versions, permissions, account configuration, and asset type affect fields and operations. Validate required fields, tolerate optional fields, and handle image or video processing states before using uploaded media in creatives.
Why use Martini instead of scripts or point-to-point integrations?
Orchestrate more than an API call
Martini coordinates authentication, webhook intake, Graph API retrieval, pagination, asynchronous Insights polling, batch result handling, downstream writes, and operational recovery in maintainable workflows.
Separate integration logic from credentials
Environment-specific Meta tokens, API versions, account identifiers, and target configuration can be managed separately from reusable workflow logic, supporting safer deployment and controlled changes.
Apply consistent transformation and controls
Martini maps Meta's object and reporting models to canonical enterprise structures, applies consent and business rules, enforces idempotency, and routes failures for retry or investigation.
Reduce point-to-point coupling
Instead of embedding Meta-specific calls separately in every application, Martini can expose controlled APIs, centralize reconciliation and error handling, and reuse integration assets across sales, analytics, finance, and operational workflows.
Frequently asked questions
The Facebook Marketing API is integrated through Meta's versioned Graph API using HTTPS and JSON. Enterprise workflows can read and manage Ad Accounts, Campaigns, Ad Sets, Ads, Ad Creatives, audiences, leads, media, and Insights, while selected Meta objects support webhook notifications. Scheduled reconciliation and asynchronous Insights jobs are used where event coverage or request size requires them.
Yes. Martini can consume Meta's Graph and Marketing REST APIs, receive supported Meta webhook notifications, orchestrate asynchronous Insights jobs, handle pagination and batch responses, transform JSON payloads, and expose controlled internal APIs where another system needs access to advertising data.
No. A dedicated Facebook Marketing API connector is not required. Martini can use Meta's native Graph API endpoints, supported webhook notifications, media upload operations, authentication methods, and scheduled workflows through standard API consumption and orchestration capabilities.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Facebook Marketing API with Martini. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Meta, cloud infrastructure, data storage, or other third-party services depending on subscription, usage, and deployment model.
Use the versioned Graph API for current resource and management operations, including Campaigns, Ad Sets, Ads, Creatives, audiences, leads, and Insights. Use batch requests for independent operations, asynchronous Insights for large reports, and media endpoints for advertising image or video workflows. GraphQL and SOAP should not be assumed because they were not confirmed for this API.
Meta Webhooks supports notifications for selected products, objects, and fields, including some lead-generation and Page-related scenarios. Coverage is not universal across Marketing API objects or state transitions. A robust integration treats a webhook as a notification and follows it with a Graph API read, supplemented by scheduled reconciliation.
Use cursor-based pagination, durable checkpoints, stable Meta IDs, and deterministic upserts. Insights should generally be reprocessed over a recent overlap window because attribution results can arrive late or change. Webhook retries and scheduled reconciliation require stored processing status and idempotency rules to prevent duplicate downstream writes.
Yes. Martini can expose a controlled API that abstracts selected Meta resources or reporting data for internal applications. A workflow behind that API can authenticate to Meta, apply permission and business rules, transform the response, and prevent consumers from needing direct access to Meta tokens or account-specific implementation details.
Related Martini documentation
Transformation
Operations
Connect Facebook Marketing API with Martini
Use Martini to build maintainable workflows for Meta advertising data, leads, audiences, media, and Insights across your enterprise applications.