facebook-python-business-sdk

facebook-business is Meta’s official Python client for the Business SDK, a single package that wraps the Marketing API alongside the Pages, Business Manager, Instagram, and related Graph API surfaces. Instead of hand-rolling HTTP calls against the Graph API, developers get a generated object model — AdAccount, Campaign, AdSet, Ad, AdCreative, Page, and hundreds of other nodes — each with typed fields and CRUD methods that map directly onto Graph API edges and endpoints.

The SDK is built around a central FacebookAdsApi session object and a large adobjects package where nearly every Graph API node has its own generated class. Object classes inherit shared CRUD, cursor-based pagination, and change-tracking behavior from a small set of abstract base classes, so new API nodes are added mechanically as Meta’s Graph API evolves rather than requiring hand-written client code for each one.

It is the standard entry point for partners and agencies building ad management tooling, reporting pipelines, or automated campaign creation against Meta’s advertising platform, and is maintained internally at Meta before being exported to GitHub on each release.

What You Get

• A generated object model (AdAccount, Campaign, AdSet, Ad, AdCreative, Page, CustomAudience, and hundreds more) with typed fields and edge-mapped CRUD methods
• A FacebookAdsApi session class handling authentication, app-secret proof, and HTTP transport (sync via requests, with optional aiohttp async support)
• Cursor-based pagination and change-tracking built into a shared AbstractCrudObject/AbstractObject base so new fields and edges behave consistently across the whole SDK
• Server-side Conversions API helpers under adobjects.serverside for sending offline/web events directly to Meta
• A large library of auto-generated usage examples under examples/, one per API edge, mirroring the Graph API reference documentation

Common Use Cases

• Building agency or in-house tooling to create and manage ad campaigns, ad sets, and creatives at scale
• Pulling advertising performance and attribution data into internal reporting or BI pipelines
• Automating Custom Audience creation and updates (e.g. hashed-email or website-visitor audiences) for ad targeting
• Sending server-side conversion events to Meta’s Conversions API for offline or web event tracking
• Managing Business Manager assets — Pages, ad accounts, users, and permissions — programmatically across many client accounts

Under The Hood

Architecture The SDK centers on a FacebookAdsApi session object (facebook_business/api.py) that owns the HTTP transport, and a large facebook_business/adobjects package where each Graph API node (AdAccount, Campaign, Ad, Page, CustomAudience, etc.) is its own generated class. Every node class extends AbstractCrudObject, which in turn extends AbstractObject (adobjects/abstractobject.py) — a MutableMapping-based data holder with a TypeChecker for field typing and a changelog (_changes) that tracks mutated fields between reads and writes. CRUD calls on any object resolve through the shared api instance (defaulting to FacebookAdsApi.get_default_api() if none is passed explicitly), and list-returning edges come back as a Cursor object supporting pagination. This means the object model itself carries almost no per-endpoint logic — behavior is inherited, and new Graph API nodes are added by generating another thin subclass rather than writing bespoke request code.

Tech Stack Pure Python, declared as compatible with Python 2 and 3, built on requests for HTTP, six for 2/3 compatibility shims, curlify for debug request logging, pycountry for country/currency reference data, and capi-param-builder-python for Conversions API parameter construction; aiohttp is pulled in conditionally for async support on Python 3.5.3+. Packaging is a conventional setup.py/requirements.txt project (no pyproject.toml), released to PyPI via a GitHub Actions workflow triggered on tag push, with Facebook’s internal Pyre type checker configured (.pyre_configuration) for static analysis of the source tree.

Code Quality Tests live under facebook_business/test/ and split into unit tests (unit.py, exercising things like CustomAudience hashing and object field typing) and a separate integration test runner that exercises live API objects (Ad, AdAccount, AdCreative, AdSet, Campaign) against real endpoints; both are wired into a tox matrix (py39–py311) run via GitHub Actions on every push and PR. The bulk of the codebase — the adobjects package — is machine-generated from Meta’s internal API spec rather than hand-written, so its consistency comes from the generator rather than manual review; the auto-generated examples/ directory still contains Python-2-only syntax (bare print statements) in places, indicating it isn’t kept in lockstep with the SDK’s stated Python 3 support.

API Design The object-per-node model reads naturally once the pattern is learned (AdAccount(id).get_campaigns(), Campaign(id).api_update(params=...)), and typed fields plus inherited CRUD methods mean IDE autocomplete works well across the hundreds of generated classes. The tradeoff is a steep initial learning curve: getting started requires a registered Meta developer app, an access token with specific ad-management permissions, and an understanding of Graph API concepts (nodes, edges, fields) that the SDK mirrors rather than abstracts away — the README’s own quick-start walks through app registration and token generation before any code runs.