WhatsApp Phone Number Verification 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: Phone Number Verification
  description: APIs for WhatsApp Business phone number verification process
paths:
  /{Version}/{Phone-Number-ID}/request_code:
    post:
      summary: Request Phone Number Verification Code
      description: 'Request a verification code for a WhatsApp Business phone number via SMS or voice call.

        This is the first step in the phone number verification process.


        **Use Cases:**

        - Initial verification of newly added phone numbers

        - Re-verification when phone number status requires it

        - Switching between SMS and voice verification methods


        **Rate Limiting:**

        Standard Graph API rate limits apply. Additional rate limiting may be enforced

        for verification code requests to prevent abuse.


        **Security:**

        Verification codes are sent only to the registered phone number and expire

        after a short time period. Multiple failed attempts may result in temporary blocking.'
      operationId: requestVerificationCode
      tags:
      - Phone Number Verification
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/ContentType'
      - 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 (EntWhatsAppBusinessAccountToNumberCurrentStatus) and can be

          obtained from your WhatsApp Business Account phone numbers list.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: 1234567890123456
      requestBody:
        required: true
        description: Verification code request parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestCodeRequest'
            examples:
              sms_verification:
                summary: Request SMS verification code
                value:
                  code_method: SMS
                  language: en_US
              voice_verification:
                summary: Request voice verification code
                value:
                  code_method: VOICE
                  language: es_ES
      responses:
        '200':
          description: Successfully requested verification code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestCodeResponse'
              examples:
                success_response:
                  summary: Successful verification code request
                  value:
                    success: true
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: 'Invalid parameter: code_method must be SMS or VOICE'
                  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 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: 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: Phone number is not eligible for verification at this time
                  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: []
  /{Version}/{Phone-Number-ID}/verify_code:
    post:
      summary: Verify Phone Number Verification Code
      description: 'Verify a phone number verification code for a WhatsApp Business Account phone number.

        This endpoint is used to complete the phone number verification process by submitting

        the verification code received via SMS or voice call.


        **Use Cases:**

        - Complete phone number verification during initial setup

        - Verify phone number ownership for messaging capabilities

        - Finalize phone number registration process

        - Complete phone number migration verification


        **Rate Limiting:**

        Verification attempts are rate-limited to prevent abuse. Failed attempts may result

        in temporary blocking. Use appropriate retry logic with exponential backoff.


        **Security:**

        Verification codes are time-limited (typically 10 minutes) and single-use.

        Multiple failed attempts may trigger additional security measures.'
      operationId: verifyPhoneNumberCode
      tags:
      - Phone Number Verification
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/ContentType'
      - 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: 'The WhatsApp Business Account phone number ID that needs verification.

          This ID is provided when you add a phone number to your WhatsApp Business Account.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '1234567890123456'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyCodeRequest'
            examples:
              verify_code:
                summary: Verify phone number with 6-digit code
                value:
                  code: '123456'
      responses:
        '200':
          description: Successfully verified the phone number verification code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyCodeResponse'
              examples:
                successful_verification:
                  summary: Successful verification response
                  value:
                    success: true
                    id: '1234567890123456'
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Invalid verification code format
                  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 verify this 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: Phone number not found
                  type: GraphMethodException
                  code: 803
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '422':
          description: Unprocessable Entity - Invalid or expired verification code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: The verification code is invalid or has expired
                  type: GraphMethodException
                  code: 100
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  error_user_title: Verification Failed
                  error_user_msg: The verification code you entered is invalid or has expired
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Too many verification attempts. Please try again later
                  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:
  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
    ContentType:
      name: Content-Type
      in: header
      description: Media type of the request body
      required: true
      schema:
        type: string
        enum:
        - application/json
        - application/x-www-form-urlencoded
        - multipart/form-data
        default: application/json
        example: application/json
  schemas:
    RequestCodeResponse:
      type: object
      description: Response after successfully requesting a verification code
      required:
      - success
      properties:
        success:
          type: boolean
          description: Indicates whether the verification code request was successful
          example: true
    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
    RequestCodeRequest:
      type: object
      description: Request body for requesting a verification code
      required:
      - code_method
      - language
      properties:
        code_method:
          type: string
          description: Method for receiving the verification code
          enum:
          - SMS
          - VOICE
          example: SMS
        language:
          type: string
          description: Language locale for the verification message
          pattern: ^[a-z]{2}_[A-Z]{2}$
          minLength: 5
          maxLength: 5
          example: en_US
    VerifyCodeRequest:
      type: object
      required:
      - code
      properties:
        code:
          type: string
          pattern: ^[0-9]{6}$
          description: 6-digit verification code received via SMS or voice
          example: '123456'
    VerifyCodeResponse:
      type: object
      description: Response from phone number verification code verification
      required:
      - success
      properties:
        success:
          type: boolean
          description: Indicates whether the verification code was successfully verified
          example: true
        id:
          type: string
          description: The phone number ID that was verified
          example: '1234567890123456'
  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

        '