WhatsApp MM Lite Onboarding API

openapi: 3.2.0
info:
  title: Meta Graph API - Application Connected Client Businesses MM…
  version: v23.0
  description: 'API for retrieving connected client businesses associated with a Meta application.


    This endpoint allows applications to retrieve information about businesses that have

    established client connections through the application. This is essential for managing

    business relationships and understanding client business configurations.'
  contact:
    name: Meta Business Platform Team
    url: https://developers.facebook.com/support
  license:
    name: Meta Platform Terms
    url: https://developers.facebook.com/terms
  termsOfService: https://developers.facebook.com/terms
servers:
- url: https://graph.facebook.com
  description: Production Graph API server
- url: https://graph.facebook.com
- url: https://graph.facebook.com
  description: WhatsApp Business Cloud API
- url: https://graph.facebook.com
  description: Meta Graph API production server
tags:
- name: MM Lite Onboarding
  description: APIs for managing Multi-Partner MM Lite onboarding requests and business agreements
paths:
  /{Version}/{Business-ID}/onboard_partners_to_mm_lite:
    post:
      summary: Onboard Partners to MM Lite
      description: 'Send a request from the partner to onboard an end business to MM Lite.

        This creates a business agreement request and sets OBO mobility intents

        on eligible WhatsApp Business Accounts.


        **Business Flow:**

        1. Validates partner business and app permissions

        2. Checks end business eligibility for MM Lite

        3. Identifies eligible shared WABAs and OBO WABAs

        4. Sets mobility intents on eligible OBO WABAs (BSPs only)

        5. Creates business agreement request

        6. Returns request ID for tracking


        **BSP vs TP Behavior:**

        - BSPs (Business Solution Providers): Can create OBO WABAs and set mobility intents

        - TPs (Technology Partners): Can only create onboarding requests, no OBO WABA management


        **Rate Limiting:**

        Subject to business partner integrations use case throttling limits.

        Use appropriate retry logic with exponential backoff.


        **Idempotency:**

        If a pending request already exists between the same partner and end business,

        the existing request ID is returned instead of creating a duplicate.'
      operationId: onboardPartnersToMMLite
      tags:
      - MM Lite Onboarding
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - name: Version
        in: path
        required: true
        description: 'Graph API version to use for this request. Determines the API behavior and available features.

          '
        schema:
          type: string
          pattern: ^v[0-9]+\.[0-9]+$
        example: v23.0
      - name: Business-ID
        in: path
        required: true
        description: 'The end business ID that will receive the MM Lite onboarding request.

          This is the business that the partner wants to establish an MM Lite relationship with.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '1234567890123456'
      - name: solution_id
        in: query
        required: false
        description: 'Optional WhatsApp Business Solution ID to associate with the onboarding request.

          If provided, the solution will be linked to the business agreement and OBO mobility intents.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '9876543210987654'
      responses:
        '200':
          description: Successfully created MM Lite onboarding request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MMLiteOnboardingRequest'
              examples:
                new_request:
                  summary: New onboarding request created
                  value:
                    request_id: '1234567890123456'
                existing_request:
                  summary: Existing pending request returned
                  value:
                    request_id: '2345678901234567'
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              examples:
                invalid_business_id:
                  summary: Invalid business ID format
                  value:
                    error:
                      message: 'Invalid parameter: business_id must be a valid numeric string'
                      type: OAuthException
                      code: 100
                      fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                invalid_solution_id:
                  summary: Invalid solution ID format
                  value:
                    error:
                      message: 'Invalid parameter: solution_id must be a valid numeric string'
                      type: OAuthException
                      code: 100
                      fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                no_eligible_wabas:
                  summary: No eligible WABAs found
                  value:
                    error:
                      message: No eligible WhatsApp Business Accounts found for MM Lite onboarding
                      type: GraphMethodException
                      code: 100
                      fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '401':
          description: Unauthorized - Invalid or missing access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Invalid OAuth access token
                  type: OAuthException
                  code: 190
                  error_subcode: 463
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '403':
          description: Forbidden - Insufficient permissions or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              examples:
                missing_permissions:
                  summary: App missing required permissions
                  value:
                    error:
                      message: Your app doesn't have the required whatsapp_business_management permission
                      type: OAuthException
                      code: 200
                      error_subcode: 1349174
                      fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                      error_user_title: Permission Denied
                      error_user_msg: Your app doesn't have permission to access this resource
                business_not_eligible:
                  summary: End business not eligible for MM Lite
                  value:
                    error:
                      message: End business is not eligible for MM Lite onboarding
                      type: GraphMethodException
                      code: 200
                      fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                duplicate_request:
                  summary: Duplicate onboarding request exists
                  value:
                    error:
                      message: A business agreement request already exists between these parties
                      type: GraphMethodException
                      code: 100
                      fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '404':
          description: Not Found - Business ID does not exist or is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Business not found
                  type: GraphMethodException
                  code: 803
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '422':
          description: Unprocessable Entity - Request parameters are valid but cannot be processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              examples:
                obo_mobility_error:
                  summary: Error setting OBO mobility intents
                  value:
                    error:
                      message: Failed to set OBO mobility intent on one or more WhatsApp Business Accounts
                      type: GraphMethodException
                      code: 100
                      fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                solution_not_found:
                  summary: Solution ID not found or not accessible
                  value:
                    error:
                      message: WhatsApp Business Solution not found or not accessible
                      type: GraphMethodException
                      code: 803
                      fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Application request limit reached
                  type: OAuthException
                  code: 4
                  error_subcode: 2446079
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
        '500':
          description: Internal Server Error - Unexpected server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: An unexpected error occurred. Please retry your request
                  type: GraphMethodException
                  code: 2
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
      security:
      - bearerAuth: []
components:
  schemas:
    GraphAPIError:
      type: object
      description: Standard Graph API error response
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          - type
          - code
          properties:
            message:
              type: string
              description: Human-readable error message
              example: Invalid parameter
            type:
              type: string
              description: Error category type
              example: OAuthException
            code:
              type: integer
              description: Numeric error code
              example: 100
            error_subcode:
              type: integer
              description: More specific error subcode when available
              example: 33
            fbtrace_id:
              type: string
              description: Unique identifier for debugging and support requests with Meta
              example: AXsgnV2Cm3ZMGF3dF_cfYIn
            is_transient:
              type: boolean
              description: Indicates whether this error is temporary and the request should be retried
              example: false
            error_user_title:
              type: string
              description: User-friendly error title for display purposes
              example: Permission Denied
            error_user_msg:
              type: string
              description: User-friendly error message for display purposes
              example: Your app doesn't have permission to access this resource
    MMLiteOnboardingRequest:
      type: object
      description: MM Lite onboarding request details
      required:
      - request_id
      properties:
        request_id:
          type: string
          description: Unique identifier for the MM Lite onboarding request
          example: '1234567890123456'
  parameters:
    Authorization:
      name: Authorization
      in: header
      description: 'Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token.

        '
      required: true
      schema:
        type: string
        pattern: ^Bearer\s+[A-Za-z0-9\-_.]+.*$
        example: Bearer EAABwzLixnjYBOzYmNMJJGfHq9DgNh...
    UserAgent:
      name: User-Agent
      in: header
      description: The user agent string identifying the client software making the request.
      required: false
      schema:
        type: string
        default: Meta-Business-Messaging-OpenAPI/1.0.0;spec=2025-10-21
        pattern: ^[a-zA-Z0-9\-_]+\/[0-9]+\.[0-9]+\.[0-9]+(;[a-zA-Z0-9\-=\.]+)?(\s+[a-zA-Z0-9\-_]+\/[0-9\-\.]+)?$
        example: Meta-Business-Messaging-OpenAPI/1.0.0;spec=2025-10-21
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'System user access token with whatsapp_business_management permission. Format: Bearer YOUR_SYSTEM_USER_ACCESS_TOKEN

        '