Format International Phone

International Phone Number Validation and Correction
Normalize and validate an international phone number using the current upstream formatting rules.

Method: GET
Path: /v1/websitetools/international-phone-format
Demo: https://api.gugudata.io/v1/websitetools/international-phone-format/demo
OpenAPI: https://gugudata.io/assets/openapi/gugudata.openapi.3.1.json

Request Parameters:

appkey (string, required): Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.

phone (string, required): Phone number to normalize and validate.

Response Fields:

dataStatus (object, required): Response metadata returned by the current v1 contract.

dataStatus.requestParameter (string, required): Normalized request parameters echoed by the service. Sensitive credentials are omitted when available.

dataStatus.statusCode (integer, required): Application-level status code returned by the current v1 contract. Successful demo responses currently return 200.

dataStatus.status (string, required): Application-level status enum. Successful demo responses currently return SUCCESS.

dataStatus.statusDescription (string, required): Application-level status message returned by the current v1 contract.

dataStatus.responseDateTime (string, required): Response timestamp returned by the current service contract.

dataStatus.dataTotalCount (integer, required): Total number of records that match the request.

data (object, required): Primary response payload returned by the endpoint.

data.isValid (boolean, required): Whether the mobile number is valid

data.correctedMobileNumber (string, required): Corrected mobile number

data.countryCode (string, required): Country phone prefix, e.g., +1

data.countryCode2 (string, required): ISO-3166 two-letter country code

data.countryCode3 (string, required): ISO-3166 three-letter country code

HTTP Status Codes:

200: Request processed successfully. Some endpoints expose a separate application-level status field in the response body, such as dataStatus.statusCode.

400: Invalid request parameters or request format. Check required fields, data types, and request body format.

401: Missing or unknown application key. Provide a valid appkey with the request.

403: The application key is recognized but access is not allowed. The key may be expired, inactive, or not permitted for the requested API.

429: Request rate or trial usage limit exceeded. Reduce concurrency or retry after the limit window resets.

500: Internal service error. Retry later or contact support if the error persists.

503: Upstream service unavailable. Retry later; the requested upstream dependency is temporarily unavailable.

Business Status Codes:

200 SUCCESS: No additional remark.

400 Parameter Error: No additional remark.

401 Unauthorized: Invalid APPKEY

429 Too Many Requests: Request rate limit exceeded

500 Internal Server Error: No additional remark.

Key Features:

Intelligently detect the validity of international mobile numbers.

Determine whether the provided mobile number is valid in a specific country based on the provided country code parameter.

Intelligently correct the provided mobile number format into a unified international format for consistent use in scenarios such as sending SMS messages.

Millisecond-level response performance.

Full API supports HTTPS (TLS v1.0 / v1.1 / v1.2 / v1.3).

Fully compatible with Apple ATS.

Nationwide multi-node CDN deployment.

Ultra-fast API response with load balancing across multiple servers.

Details:
https://gugudata.io/details/international-phone-format

application/json

Bodyapplication/json

Example

{
  "dataStatus": {
    "requestParameter": "string",
    "statusCode": 0,
    "status": "string",
    "statusDescription": "string",
    "responseDateTime": "string",
    "dataTotalCount": 0
  },
  "data": {
    "isValid": false,
    "correctedMobileNumber": "string",
    "countryCode": "string",
    "countryCode2": "string",
    "countryCode3": "string"
  },
  "DataStatus": {
    "StatusCode": 100,
    "StatusDescription": "OK",
    "ResponseDateTime": "2026-01-01 00:00:00",
    "DataTotalCount": 1
  }
}

Request

Request Code Samples

Responses