Facebook Business Manager Pages API

openapi: 3.1.0
info:
  title: Facebook Business Manager Facebook Marketing Ad Accounts Pages API
  description: Create and manage ad campaigns, analyze performance, and automate advertising workflows across Meta platforms. The Marketing API provides programmatic access to Facebook's advertising system, enabling businesses to create campaigns, ad sets, and ads, manage budgets and bidding strategies, define targeting audiences, and retrieve performance metrics.
  version: '25.0'
  contact:
    name: Meta Developer Support
    url: https://developers.facebook.com/support
  termsOfService: https://developers.facebook.com/terms
servers:
- url: https://graph.facebook.com/v25.0
  description: Facebook Graph API Production Server
security:
- bearerAuth: []
tags:
- name: Pages
  description: Retrieve and manage Facebook Page settings, information, and metadata.
paths:
  /{page_id}:
    get:
      operationId: getPage
      summary: Facebook Business Manager Get page details
      description: Retrieves information about a Facebook Page including name, category, description, fan count, and other metadata.
      tags:
      - Pages
      parameters:
      - $ref: '#/components/parameters/pageId'
      - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successfully retrieved page details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /{page_id}/subscribed_apps:
    post:
      operationId: subscribePageApp
      summary: Facebook Business Manager Subscribe app to page
      description: Installs a Webhooks-configured app on the Page so the app can receive real-time updates about changes to the Page.
      tags:
      - Pages
      parameters:
      - $ref: '#/components/parameters/pageId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - subscribed_fields
              properties:
                subscribed_fields:
                  type: array
                  items:
                    type: string
                  description: List of Page fields to subscribe to, such as feed, messages, messaging_postbacks.
      responses:
        '200':
          description: App subscribed to page successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    pageId:
      name: page_id
      in: path
      required: true
      description: The ID of the Facebook Page
      schema:
        type: string
    fields:
      name: fields
      in: query
      required: false
      description: Comma-separated list of fields to include in the response
      schema:
        type: string
  responses:
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request parameters or malformed request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Invalid or expired access token or insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Human-readable error message
            type:
              type: string
              description: Error type classification
            code:
              type: integer
              description: Numeric error code
            error_subcode:
              type: integer
              description: Numeric error subcode
            fbtrace_id:
              type: string
              description: Unique trace ID for debugging
    Page:
      type: object
      properties:
        id:
          type: string
          description: The ID of the Page
        name:
          type: string
          description: The name of the Page
        category:
          type: string
          description: The primary category of the Page
        category_list:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
          description: List of categories associated with the Page
        about:
          type: string
          description: Short description of the Page
        description:
          type: string
          description: Detailed description of the Page
        fan_count:
          type: integer
          description: Total number of Page likes
        followers_count:
          type: integer
          description: Total number of Page followers
        link:
          type: string
          format: uri
          description: The URL of the Page on Facebook
        website:
          type: string
          format: uri
          description: The website listed on the Page
        phone:
          type: string
          description: Phone number listed on the Page
        emails:
          type: array
          items:
            type: string
          description: Email addresses listed on the Page
        location:
          type: object
          properties:
            street:
              type: string
            city:
              type: string
            state:
              type: string
            country:
              type: string
            zip:
              type: string
            latitude:
              type: number
            longitude:
              type: number
        cover:
          type: object
          properties:
            id:
              type: string
            source:
              type: string
              format: uri
          description: The Page cover photo
        picture:
          type: object
          properties:
            data:
              type: object
              properties:
                url:
                  type: string
                  format: uri
          description: The Page profile picture
        verification_status:
          type: string
          description: Verification status of the Page
        is_published:
          type: boolean
          description: Whether the Page is published and visible
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 access token with ads_management or ads_read permissions. Obtain tokens via the Facebook Login flow.
externalDocs:
  description: Facebook Marketing API Documentation
  url: https://developers.facebook.com/docs/marketing-api