Facebook Marketing API

openapi: 3.0.3
info:
  title: Facebook Marketing API
  description: >-
    Programmatically manage Facebook ad campaigns, ad sets, ad creatives, Custom
    Audiences, and advertising reports.
  version: '21.0'
  contact:
    name: Meta Platforms
    url: https://developers.facebook.com
  x-generated-from: documentation
  x-last-validated: '2026-04-18'
servers:
  - url: https://graph.facebook.com/v21.0
    description: Facebook Marketing API v21.0
security:
  - BearerAuth: []
paths:
  /act_{ad-account-id}:
    get:
      operationId: getAdAccount
      summary: Facebook Get Ad Account
      description: Retrieve an ad account by ID.
      tags:
        - Ad Accounts
      parameters:
        - name: ad-account-id
          in: path
          required: true
          description: The ad account ID.
          schema:
            type: string
          example: '123456789'
        - name: fields
          in: query
          description: Comma-separated list of fields to return.
          schema:
            type: string
          example: id,name,account_status,currency
      responses:
        '200':
          description: Ad account retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdAccount'
              examples:
                GetAdAccount200Example:
                  summary: Default getAdAccount 200 response
                  x-microcks-default: true
                  value:
                    id: act_123456789
                    name: My Ad Account
                    account_status: 1
                    currency: USD
                    balance: '500.00'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /act_{ad-account-id}/campaigns:
    get:
      operationId: listCampaigns
      summary: Facebook List Campaigns
      description: Retrieve campaigns for an ad account.
      tags:
        - Campaigns
      parameters:
        - name: ad-account-id
          in: path
          required: true
          description: The ad account ID.
          schema:
            type: string
          example: '123456789'
        - name: limit
          in: query
          description: Maximum number of campaigns to return.
          schema:
            type: integer
          example: 25
      responses:
        '200':
          description: Campaigns retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createCampaign
      summary: Facebook Create Campaign
      description: Create a new advertising campaign.
      tags:
        - Campaigns
      parameters:
        - name: ad-account-id
          in: path
          required: true
          description: The ad account ID.
          schema:
            type: string
          example: '123456789'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignRequest'
            examples:
              CreateCampaignRequestExample:
                summary: Default createCampaign request
                x-microcks-default: true
                value:
                  name: Spring Sale 2026
                  objective: OUTCOME_SALES
                  status: PAUSED
                  special_ad_categories: []
      responses:
        '200':
          description: Campaign created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
        '400':
          description: Invalid campaign configuration.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{campaign-id}:
    get:
      operationId: getCampaign
      summary: Facebook Get Campaign
      description: Retrieve a specific campaign by ID.
      tags:
        - Campaigns
      parameters:
        - name: campaign-id
          in: path
          required: true
          description: The campaign ID.
          schema:
            type: string
          example: '400001234567890'
      responses:
        '200':
          description: Campaign retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /act_{ad-account-id}/adsets:
    get:
      operationId: listAdSets
      summary: Facebook List Ad Sets
      description: Retrieve ad sets for an ad account.
      tags:
        - Ad Sets
      parameters:
        - name: ad-account-id
          in: path
          required: true
          description: The ad account ID.
          schema:
            type: string
          example: '123456789'
      responses:
        '200':
          description: Ad sets retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdSetList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createAdSet
      summary: Facebook Create Ad Set
      description: Create a new ad set within a campaign.
      tags:
        - Ad Sets
      parameters:
        - name: ad-account-id
          in: path
          required: true
          description: The ad account ID.
          schema:
            type: string
          example: '123456789'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdSetRequest'
      responses:
        '200':
          description: Ad set created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /act_{ad-account-id}/ads:
    get:
      operationId: listAds
      summary: Facebook List Ads
      description: Retrieve ads for an ad account.
      tags:
        - Ads
      parameters:
        - name: ad-account-id
          in: path
          required: true
          description: The ad account ID.
          schema:
            type: string
          example: '123456789'
      responses:
        '200':
          description: Ads retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /act_{ad-account-id}/insights:
    get:
      operationId: getAccountInsights
      summary: Facebook Get Account Insights
      description: Retrieve advertising insights for an ad account.
      tags:
        - Insights
      parameters:
        - name: ad-account-id
          in: path
          required: true
          description: The ad account ID.
          schema:
            type: string
          example: '123456789'
        - name: date_preset
          in: query
          description: Predefined date range for insights.
          schema:
            type: string
            enum:
              - today
              - yesterday
              - last_7d
              - last_30d
              - this_month
          example: last_7d
      responses:
        '200':
          description: Insights retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /act_{ad-account-id}/customaudiences:
    get:
      operationId: listCustomAudiences
      summary: Facebook List Custom Audiences
      description: Retrieve custom audiences for an ad account.
      tags:
        - Audiences
      parameters:
        - name: ad-account-id
          in: path
          required: true
          description: The ad account ID.
          schema:
            type: string
          example: '123456789'
      responses:
        '200':
          description: Custom audiences retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomAudienceList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createCustomAudience
      summary: Facebook Create Custom Audience
      description: Create a new custom audience.
      tags:
        - Audiences
      parameters:
        - name: ad-account-id
          in: path
          required: true
          description: The ad account ID.
          schema:
            type: string
          example: '123456789'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomAudienceRequest'
      responses:
        '200':
          description: Custom audience created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 access token with ads_management permission.
  schemas:
    AdAccount:
      type: object
      description: A Facebook ad account.
      properties:
        id:
          type: string
          description: Ad account ID prefixed with act_.
          example: act_123456789
        name:
          type: string
          description: Account name.
          example: My Ad Account
        account_status:
          type: integer
          description: Account status code.
          example: 1
        currency:
          type: string
          description: Account currency code.
          example: USD
        balance:
          type: string
          description: Account balance.
          example: '500.00'
        spend_cap:
          type: string
          description: Spend cap for the account.
    Campaign:
      type: object
      description: An advertising campaign.
      properties:
        id:
          type: string
          description: Campaign ID.
          example: '400001234567890'
        name:
          type: string
          description: Campaign name.
          example: Spring Sale 2026
        objective:
          type: string
          description: Campaign objective.
          example: OUTCOME_SALES
        status:
          type: string
          description: Campaign status.
          enum:
            - ACTIVE
            - PAUSED
            - DELETED
            - ARCHIVED
          example: ACTIVE
        daily_budget:
          type: string
          description: Daily budget in cents.
          example: '5000'
        lifetime_budget:
          type: string
          description: Lifetime budget in cents.
        created_time:
          type: string
          format: date-time
          description: Campaign creation time.
        updated_time:
          type: string
          format: date-time
          description: Campaign last update time.
    CampaignRequest:
      type: object
      description: Request to create a campaign.
      properties:
        name:
          type: string
          description: Campaign name.
          example: Spring Sale 2026
        objective:
          type: string
          description: Campaign objective.
          example: OUTCOME_SALES
        status:
          type: string
          description: Initial campaign status.
          example: PAUSED
        special_ad_categories:
          type: array
          items:
            type: string
          description: Special ad categories.
      required:
        - name
        - objective
        - special_ad_categories
    CampaignList:
      type: object
      description: Paginated list of campaigns.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Campaign'
        paging:
          $ref: '#/components/schemas/Paging'
    AdSet:
      type: object
      description: An ad set within a campaign.
      properties:
        id:
          type: string
          description: Ad set ID.
          example: '500001234567890'
        name:
          type: string
          description: Ad set name.
          example: Women 25-34 Interest Targeting
        campaign_id:
          type: string
          description: Parent campaign ID.
        status:
          type: string
          description: Ad set status.
          enum:
            - ACTIVE
            - PAUSED
            - DELETED
            - ARCHIVED
        daily_budget:
          type: string
          description: Daily budget in cents.
        start_time:
          type: string
          format: date-time
          description: Ad set start time.
        end_time:
          type: string
          format: date-time
          description: Ad set end time.
        targeting:
          type: object
          description: Targeting specification.
        bid_amount:
          type: string
          description: Bid amount in cents.
    AdSetRequest:
      type: object
      description: Request to create an ad set.
      properties:
        name:
          type: string
          description: Ad set name.
        campaign_id:
          type: string
          description: Parent campaign ID.
        daily_budget:
          type: string
          description: Daily budget in cents.
        targeting:
          type: object
          description: Targeting specification.
        status:
          type: string
          description: Initial ad set status.
      required:
        - name
        - campaign_id
        - targeting
    AdSetList:
      type: object
      description: Paginated list of ad sets.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AdSet'
        paging:
          $ref: '#/components/schemas/Paging'
    Ad:
      type: object
      description: An individual advertisement.
      properties:
        id:
          type: string
          description: Ad ID.
          example: '600001234567890'
        name:
          type: string
          description: Ad name.
          example: Spring Sale Banner Ad
        adset_id:
          type: string
          description: Parent ad set ID.
        campaign_id:
          type: string
          description: Parent campaign ID.
        status:
          type: string
          description: Ad status.
          enum:
            - ACTIVE
            - PAUSED
            - DELETED
            - ARCHIVED
        creative:
          type: object
          description: Creative specification.
          properties:
            id:
              type: string
    AdList:
      type: object
      description: Paginated list of ads.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Ad'
        paging:
          $ref: '#/components/schemas/Paging'
    Insight:
      type: object
      description: Advertising performance insight.
      properties:
        impressions:
          type: string
          description: Number of impressions.
          example: '15000'
        clicks:
          type: string
          description: Number of clicks.
          example: '450'
        spend:
          type: string
          description: Amount spent.
          example: '125.50'
        cpc:
          type: string
          description: Cost per click.
          example: '0.28'
        cpm:
          type: string
          description: Cost per thousand impressions.
          example: '8.37'
        ctr:
          type: string
          description: Click-through rate.
          example: '3.00'
        reach:
          type: string
          description: Number of unique users reached.
          example: '12000'
        date_start:
          type: string
          format: date
          description: Start date of the insight period.
        date_stop:
          type: string
          format: date
          description: End date of the insight period.
    InsightList:
      type: object
      description: Paginated list of insights.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Insight'
        paging:
          $ref: '#/components/schemas/Paging'
    CustomAudience:
      type: object
      description: A custom audience for ad targeting.
      properties:
        id:
          type: string
          description: Custom audience ID.
          example: '700001234567890'
        name:
          type: string
          description: Audience name.
          example: Website Visitors Last 30 Days
        description:
          type: string
          description: Audience description.
        approximate_count:
          type: integer
          description: Approximate audience size.
          example: 25000
        subtype:
          type: string
          description: Audience subtype.
          enum:
            - CUSTOM
            - LOOKALIKE
            - WEBSITE
        delivery_status:
          type: object
          description: Audience delivery status.
    CustomAudienceRequest:
      type: object
      description: Request to create a custom audience.
      properties:
        name:
          type: string
          description: Audience name.
        description:
          type: string
          description: Audience description.
        subtype:
          type: string
          description: Audience subtype.
        customer_file_source:
          type: string
          description: Source of customer data.
      required:
        - name
        - subtype
    CustomAudienceList:
      type: object
      description: Paginated list of custom audiences.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CustomAudience'
        paging:
          $ref: '#/components/schemas/Paging'
    Paging:
      type: object
      description: Pagination cursors.
      properties:
        cursors:
          type: object
          properties:
            before:
              type: string
            after:
              type: string
        next:
          type: string
          format: uri
        previous:
          type: string
          format: uri