WhatsApp Application Business Connections API

openapi: 3.2.0
info:
  title: Meta Graph API - Application Connected Client Businesses…
  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: Application Business Connections
  description: APIs for managing application connected client business relationships
paths:
  /{Version}/{Application-ID}/connected_client_businesses:
    get:
      summary: Get Connected Client Businesses
      description: 'Retrieve a list of client businesses connected to the specified application.


        **Use Cases:**

        - Monitor application-business client relationships

        - Verify connected business configurations

        - Retrieve business connection status and details

        - Manage client business access and permissions


        **Rate Limiting:**

        Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff.


        **Caching:**

        Business connection data can be cached for moderate periods, but status information may change.

        Implement appropriate cache invalidation strategies.'
      operationId: getConnectedClientBusinesses
      tags:
      - Application Business Connections
      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: Application-ID
        in: path
        required: true
        description: 'Your Meta Application ID. This ID is provided when you create the application

          and can be found in your App Dashboard.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '1234567890123456'
      - name: fields
        in: query
        required: false
        description: 'Comma-separated list of fields to include in the response. If not specified,

          default fields will be returned (id, name, verification_status, business_status).

          Available fields: id, name, verification_status, business_status, created_time, updated_time

          '
        schema:
          type: string
        example: id,name,verification_status,business_status
      - name: limit
        in: query
        required: false
        description: 'Maximum number of connected client businesses to return per page. Default is 25, maximum is 100.

          '
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
        example: 25
      - name: after
        in: query
        required: false
        description: 'Cursor for pagination. Use this to get the next page of results.

          '
        schema:
          type: string
        example: QVFIUjNpUWpVWmRBd0Rn
      - name: before
        in: query
        required: false
        description: 'Cursor for pagination. Use this to get the previous page of results.

          '
        schema:
          type: string
        example: QVFIUjNpUWpVWmRBd0Dn
      responses:
        '200':
          description: Successfully retrieved connected client businesses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectedClientBusinessesResponse'
              examples:
                multiple_businesses:
                  summary: Multiple connected client businesses
                  value:
                    data:
                    - id: '1234567890123456'
                      name: Example Client Business A
                      verification_status: VERIFIED
                      business_status: ACTIVE
                      created_time: '2023-01-15T10:30:00Z'
                      updated_time: '2023-06-20T14:45:00Z'
                    - id: '2345678901234567'
                      name: Example Client Business B
                      verification_status: PENDING
                      business_status: PENDING_APPROVAL
                      created_time: '2023-03-10T09:15:00Z'
                      updated_time: '2023-03-10T09:15:00Z'
                    paging:
                      cursors:
                        after: QVFIUjNpUWpVWmRBd0Rn
                      next: https://graph.facebook.com/v23.0/1234567890/connected_client_businesses?after=QVFIUjNpUWpVWmRBd0Rn
                single_business:
                  summary: Single connected client business
                  value:
                    data:
                    - id: '1234567890123456'
                      name: Example Client Business
                      verification_status: VERIFIED
                      business_status: ACTIVE
                empty_response:
                  summary: No connected client businesses
                  value:
                    data: []
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: 'Invalid parameter: application_id must be a valid numeric string'
                  type: OAuthException
                  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'
              example:
                error:
                  message: Your app doesn't have permission to access connected client businesses for this application
                  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
        '404':
          description: Not Found - Application ID does not exist or is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Application 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'
              example:
                error:
                  message: The requested fields are not available for this application
                  type: GraphMethodException
                  code: 100
                  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:
    BusinessStatus:
      type: string
      description: Current status of the connected client business
      enum:
      - ACTIVE
      - INACTIVE
      - SUSPENDED
      - PENDING_APPROVAL
      example: ACTIVE
    ConnectedClientBusiness:
      type: object
      description: Connected client business information and configuration
      required:
      - id
      - name
      properties:
        id:
          type: string
          description: Unique identifier for the connected client business
          example: '1234567890123456'
        name:
          type: string
          description: Name of the connected client business
          minLength: 1
          maxLength: 255
          example: Example Client Business
        verification_status:
          $ref: '#/components/schemas/BusinessVerificationStatus'
        business_status:
          $ref: '#/components/schemas/BusinessStatus'
        created_time:
          type: string
          format: date-time
          description: Timestamp when the business connection was created
          example: '2023-01-15T10:30:00Z'
        updated_time:
          type: string
          format: date-time
          description: Timestamp when the business connection was last updated
          example: '2023-06-20T14:45:00Z'
    CursorPaging:
      type: object
      description: Cursor-based pagination information
      properties:
        cursors:
          type: object
          properties:
            before:
              type: string
              description: Cursor pointing to the start of the page of data
              example: QVFIUjNpUWpVWmRBd0dn
            after:
              type: string
              description: Cursor pointing to the end of the page of data
              example: QVFIUjNpUWpVWmRBd0Rn
        previous:
          type: string
          description: URL for the previous page of results
          example: https://graph.facebook.com/v23.0/1234567890/connected_client_businesses?before=QVFIUjNpUWpVWmRBd0Dn
        next:
          type: string
          description: URL for the next page of results
          example: https://graph.facebook.com/v23.0/1234567890/connected_client_businesses?after=QVFIUjNpUWpVWmRBd0Rn
    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
    ConnectedClientBusinessesResponse:
      type: object
      description: Response containing list of connected client businesses
      properties:
        data:
          type: array
          description: Array of connected client businesses
          items:
            $ref: '#/components/schemas/ConnectedClientBusiness'
        paging:
          $ref: '#/components/schemas/CursorPaging'
    BusinessVerificationStatus:
      type: string
      description: Verification status of the connected client business
      enum:
      - VERIFIED
      - UNVERIFIED
      - PENDING
      - REJECTED
      example: VERIFIED
  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

        '