Skip to main content

​
WhatsApp Business Pre-Verified Phone Number API

Copy for LLM View as Markdown Version v23.0 API for managing WhatsApp Business Pre-Verified Phone Numbers, including validation, retrieval, and deletion operations. Pre-verified phone numbers are phone numbers that have been pre-validated by Business Solution Providers (BSPs) for WhatsApp Business API usage.

​
Base URL

| https://graph.facebook.com |

​
Endpoints

| GET | // | | DELETE | // |

​
GET //

Retrieve details about a specific pre-verified phone number, including validation status, formatting information, and any associated error messages. Use Cases: Check validation status of a pre-verified phone number Retrieve formatted display version of the phone number Get country code and formatting information Troubleshoot validation errors Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Phone number details can be cached for moderate periods, but validation status may change. Implement appropriate cache invalidation strategies.

​
Request Syntax

GET// Try it Select language cURLJavaScriptPython 
curl --request GET \
  --url 'https://graph.facebook.com/{Version}/{Pre-Verified-Phone-Number-ID}' \
  --header 'Authorization: Bearer <Token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
Select status code 200400401403404422429500 
\{
  "valid_phone_number": {
    "summary": "Valid pre-verified phone number",
    "value": {
      "id": "1234567890123456",
      "country_prefix": 1,
      "display_phone_number": "+1 (555) 123-4567",
      "is_input_id_valid": true
    }
  },
  "invalid_phone_number": {
    "summary": "Invalid pre-verified phone number",
    "value": {
      "id": "2345678901234567",
      "error_msg": "Phone number format is invalid",
      "is_input_id_valid": false
    }
  }
}
Header Parameters
User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters
Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Pre-Verified-Phone-Number-IDstring·required The pre-verified phone number ID to retrieve details for. This ID is provided by your Business Solution Provider (BSP) during the pre-verification process. Query Parameters
fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned (id, is_input_id_valid). Available fields: id, country_prefix, display_phone_number, error_msg, is_input_id_valid Responses
Retrieve details about a specific pre-verified phone number, including validation status, formatting information, and any associated error messages. Use Cases: Check validation status of a pre-verified phone number Retrieve formatted display version of the phone number Get country code and formatting information Troubleshoot validation errors Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Phone number details can be cached for moderate periods, but validation status may change. Implement appropriate cache invalidation strategies. 200 Successfully retrieved pre-verified phone number details Content Type: application/json Schema: PreVerifiedPhoneNumberValidation Show child attributes
PreVerifiedPhoneNumberValidation
idstring Unique identifier for the pre-verified phone number
country_prefixinteger [min: 1, max: 999] Country code prefix for the phone number
display_phone_numberstring Formatted display version of the phone number
error_msgstring Error message if validation failed
is_input_id_validboolean·required Whether the provided phone number ID is valid 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 404 Not Found - Pre-verified phone number ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes Select language cURLJavaScriptPython 
curl --request GET \
  --url 'https://graph.facebook.com/{Version}/{Pre-Verified-Phone-Number-ID}' \
  --header 'Authorization: Bearer <Token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
Select status code 200400401403404422429500 
\{
  "valid_phone_number": {
    "summary": "Valid pre-verified phone number",
    "value": {
      "id": "1234567890123456",
      "country_prefix": 1,
      "display_phone_number": "+1 (555) 123-4567",
      "is_input_id_valid": true
    }
  },
  "invalid_phone_number": {
    "summary": "Invalid pre-verified phone number",
    "value": {
      "id": "2345678901234567",
      "error_msg": "Phone number format is invalid",
      "is_input_id_valid": false
    }
  }
}

​
DELETE //

Delete a pre-verified phone number from the system. This operation removes the phone number from your pre-verified list and cannot be undone. Use Cases: Remove phone numbers that are no longer needed Clean up invalid or incorrect pre-verified phone numbers Manage phone number lifecycle and cleanup Important Notes: This operation is irreversible Deleted phone numbers cannot be recovered Ensure the phone number is not in active use before deletion Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff.

​
Request Syntax

DELETE// Try it Select language cURLJavaScriptPython 
curl --request DELETE \
  --url 'https://graph.facebook.com/{Version}/{Pre-Verified-Phone-Number-ID}' \
  --header 'Authorization: Bearer <Token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
Select status code 200400401403404422429500 
\{
  "success": "true"
}
Header Parameters
User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters
Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Pre-Verified-Phone-Number-IDstring·required The pre-verified phone number ID to delete. This ID is provided by your Business Solution Provider (BSP) during the pre-verification process. Responses
Delete a pre-verified phone number from the system. This operation removes the phone number from your pre-verified list and cannot be undone. Use Cases: Remove phone numbers that are no longer needed Clean up invalid or incorrect pre-verified phone numbers Manage phone number lifecycle and cleanup Important Notes: This operation is irreversible Deleted phone numbers cannot be recovered Ensure the phone number is not in active use before deletion Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. 200 Successfully deleted pre-verified phone number Content Type: application/json Schema: object Show child attributes
successboolean Indicates whether the deletion was successful 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 404 Not Found - Pre-verified phone number ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Phone number cannot be deleted due to current state Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes Select language cURLJavaScriptPython 
curl --request DELETE \
  --url 'https://graph.facebook.com/{Version}/{Pre-Verified-Phone-Number-ID}' \
  --header 'Authorization: Bearer <Token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
Select status code 200400401403404422429500 
\{
  "success": "true"
}

​
Authentication

| Scheme | Type | Location | | bearerAuth | HTTP Bearer | Header: Authorization |

​
Usage Examples

bearerAuth: Include Authorization: Bearer your-token-here in request headers

​
Global Authentication Requirements

All endpoints require: bearerAuth Did you find this page helpful? Thumbs up icon Thumbs down icon