WhatsApp Official Business Account 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: Official Business Account
  description: APIs for managing Official Business Account status and verification
paths:
  /{Version}/{Phone-Number-ID}/official_business_account:
    get:
      summary: Get Official Business Account Status
      description: 'Retrieve the Official Business Account (OBA) status and related information for a WhatsApp Business Account phone number.


        **Use Cases:**

        - Check current OBA verification status

        - Monitor OBA application progress

        - Retrieve status messages for business account verification

        - Validate business credibility status


        **Rate Limiting:**

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


        **Caching:**

        OBA status information can be cached for moderate periods, but status may change

        during verification processes. Implement appropriate cache invalidation strategies.'
      operationId: getOfficialBusinessAccountStatus
      tags:
      - Official Business Account
      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: Phone-Number-ID
        in: path
        required: true
        description: 'Your WhatsApp Business phone number ID. This ID represents the phone number

          status entity and can be obtained from your WhatsApp Business Account phone numbers list.

          '
        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 (oba_status, status_message).

          Available fields: oba_status, status_message

          '
        schema:
          type: string
        example: oba_status,status_message
      responses:
        '200':
          description: Successfully retrieved Official Business Account status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfficialBusinessAccountStatus'
              examples:
                pending_status:
                  summary: Pending OBA application
                  value:
                    id: '1234567890123456'
                    oba_status: PENDING
                    status_message: Your Official Business Account application is under review
                approved_status:
                  summary: Approved OBA status
                  value:
                    id: '2345678901234567'
                    oba_status: APPROVED
                    status_message: Your Official Business Account has been approved
                rejected_status:
                  summary: Rejected OBA application
                  value:
                    id: '3456789012345678'
                    oba_status: REJECTED
                    status_message: Your Official Business Account application was rejected. Please review the requirements and reapply.
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: 'Invalid parameter: phone_number_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 this WhatsApp Business Account phone number
                  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 - Phone number ID does not exist or is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: WhatsApp Business Account phone number 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 phone number
                  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: []
    post:
      summary: Update Official Business Account Status
      description: 'Update or modify the Official Business Account (OBA) status for a WhatsApp Business Account phone number.

        This endpoint allows businesses to submit new applications, withdraw existing applications, or resubmit

        after addressing rejection reasons.


        **Use Cases:**

        - Submit initial Official Business Account application

        - Withdraw pending OBA application

        - Resubmit OBA application after addressing rejection feedback

        - Update application data for pending applications


        **Application Data Requirements:**

        When submitting or resubmitting an OBA application, certain business information may be required

        depending on the current status and previous submissions.


        **Rate Limiting:**

        Standard Graph API rate limits apply with additional restrictions on application submissions

        to prevent abuse. Use appropriate retry logic with exponential backoff.


        **Status Transitions:**

        - Applications can only be submitted when no active application exists

        - Withdrawals are only allowed for pending applications

        - Resubmissions are only allowed after rejection'
      operationId: GraphWhatsAppBusinessAccountToNumberCurrentStatusOfficialBusinessAccountPost
      tags:
      - Official Business Account
      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: Phone-Number-ID
        in: path
        required: true
        description: 'Your WhatsApp Business phone number ID. This ID represents the phone number

          status entity and can be obtained from your WhatsApp Business Account phone numbers list.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '1234567890123456'
      requestBody:
        required: true
        description: Official Business Account status update request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfficialBusinessAccountUpdateRequest'
            examples:
              submit_application:
                summary: Submit new OBA application
                value:
                  action: SUBMIT_APPLICATION
                  application_data:
                    business_name: Acme Corporation Ltd
                    business_description: Leading provider of innovative business solutions and consulting services
                    website_url: https://www.acmecorp.com
                    contact_email: business@acmecorp.com
              withdraw_application:
                summary: Withdraw pending application
                value:
                  action: WITHDRAW_APPLICATION
              resubmit_application:
                summary: Resubmit after rejection
                value:
                  action: RESUBMIT_APPLICATION
                  application_data:
                    business_name: Acme Corporation Ltd
                    business_description: Updated business description addressing previous feedback
                    website_url: https://www.acmecorp.com
                    contact_email: business@acmecorp.com
      responses:
        '200':
          description: Successfully updated Official Business Account status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfficialBusinessAccountUpdateResponse'
              examples:
                successful_submission:
                  summary: Successful application submission
                  value:
                    success: true
                    message: Official Business Account application submitted successfully
                    updated_status:
                      id: '1234567890123456'
                      oba_status: PENDING
                      status_message: Your Official Business Account application is under review
                    tracking_id: oba_req_1234567890abcdef
                successful_withdrawal:
                  summary: Successful application withdrawal
                  value:
                    success: true
                    message: Official Business Account application withdrawn successfully
                    updated_status:
                      id: '1234567890123456'
                      oba_status: CANCELLED
                      status_message: Official Business Account application has been cancelled
                    tracking_id: oba_req_fedcba0987654321
        '400':
          description: Bad Request - Invalid parameters, malformed request, or invalid state transition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              examples:
                invalid_action:
                  summary: Invalid action for current status
                  value:
                    error:
                      message: 'Cannot submit application: An active application already exists'
                      type: OAuthException
                      code: 100
                      fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                missing_data:
                  summary: Missing required application data
                  value:
                    error:
                      message: 'Missing required application data: business_name is required for SUBMIT_APPLICATION'
                      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 modify this WhatsApp Business Account phone number
                  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 modify this resource
        '404':
          description: Not Found - Phone number ID does not exist or is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: WhatsApp Business Account phone number not found
                  type: GraphMethodException
                  code: 803
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '409':
          description: Conflict - Invalid state transition or conflicting request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              examples:
                invalid_transition:
                  summary: Invalid status transition
                  value:
                    error:
                      message: 'Cannot withdraw application: No pending application found'
                      type: GraphMethodException
                      code: 100
                      fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                concurrent_modification:
                  summary: Concurrent modification detected
                  value:
                    error:
                      message: Application status was modified by another request. Please refresh and try again
                      type: GraphMethodException
                      code: 100
                      fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '422':
          description: Unprocessable Entity - Request is valid but cannot be processed due to business rules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              examples:
                invalid_data:
                  summary: Invalid application data format
                  value:
                    error:
                      message: 'Invalid website URL format: URL must be a valid HTTPS URL'
                      type: GraphMethodException
                      code: 100
                      fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                business_rules:
                  summary: Business rule violation
                  value:
                    error:
                      message: Business name cannot exceed 255 characters
                      type: GraphMethodException
                      code: 100
                      fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '429':
          description: Too Many Requests - Rate limit exceeded or too many application attempts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              examples:
                rate_limit:
                  summary: Standard rate limit exceeded
                  value:
                    error:
                      message: Application request limit reached
                      type: OAuthException
                      code: 4
                      error_subcode: 2446079
                      fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                      is_transient: true
                application_limit:
                  summary: Application submission limit reached
                  value:
                    error:
                      message: Too many application attempts. Please wait before submitting again
                      type: OAuthException
                      code: 4
                      error_subcode: 2446080
                      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:
  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
  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
    OfficialBusinessAccountUpdateResponse:
      type: object
      description: Response for Official Business Account status update operation
      required:
      - success
      - message
      properties:
        success:
          type: boolean
          description: Indicates if the operation was successful
          example: true
        message:
          type: string
          description: Human-readable message describing the result of the operation
          example: Official Business Account application submitted successfully
        updated_status:
          $ref: '#/components/schemas/OfficialBusinessAccountStatus'
        tracking_id:
          type: string
          description: Unique identifier for tracking the application/update request
          example: oba_req_1234567890abcdef
    OfficialBusinessAccountUpdateRequest:
      type: object
      description: Request payload for updating Official Business Account status
      required:
      - business_website_url
      - primary_country_of_operation
      properties:
        business_website_url:
          type: string
          format: uri
          description: Official business website URL
          example: https://www.meta.com
        primary_country_of_operation:
          type: string
          description: Primary country where the business operates
          example: US
        primary_language:
          type: string
          description: Primary language used by the business
          example: en_US
        parent_business_or_brand:
          type: string
          description: Parent business or brand name
          example: Acme Corporation Ltd
          maxLength: 255
        supporting_links:
          type: array
          description: Supporting links that demonstrate business notability (minimum 5, maximum 10)
          minItems: 5
          maxItems: 10
          items:
            type: string
            format: uri
          example:
          - https://www.example.com/press1
          - https://www.example.com/press2
          - https://www.example.com/press3
          - https://www.example.com/press4
          - https://www.example.com/press5
        additional_supporting_information:
          type: string
          description: Additional information to support the Official Business Account application
          example: Leading provider of innovative business solutions
          maxLength: 1000
    WhatsAppBusinessAppealStatus:
      type: string
      description: Official Business Account appeal and verification status
      enum:
      - PENDING
      - APPROVED
      - REJECTED
      - UNDER_REVIEW
      - EXPIRED
      - CANCELLED
      example: PENDING
    OfficialBusinessAccountStatus:
      type: object
      description: Official Business Account status information for a WhatsApp Business Account phone number
      required:
      - id
      - oba_status
      - status_message
      properties:
        id:
          type: string
          description: Unique identifier for the WhatsApp Business Account phone number
          example: '1234567890123456'
        oba_status:
          $ref: '#/components/schemas/WhatsAppBusinessAppealStatus'
        status_message:
          type: string
          description: Human-readable message describing the current Official Business Account status
          example: Your Official Business Account application is under review
  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

        '