> ## Documentation Index
> Fetch the complete documentation index at: https://documents.xobito.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Validate a phone number

> Check whether a phone number is in valid format and extract country details.

<Info>
  **Live as of 2026-05-28.** This endpoint is now available on production.
</Info>

Validate a phone number format and return parsed country/national parts. **This endpoint checks format only.** It does not verify whether the number is registered on WhatsApp.

<Note>
  To verify WhatsApp registration, send a template message and inspect the response — there is no format-level way to check registration.
</Note>

## Endpoint

```
POST /api/v1/{subdomain}/phone/validate
```

Required ability: `messages.send`.

## Headers

| Header          | Value                        |
| --------------- | ---------------------------- |
| `Authorization` | `Bearer <your-64-hex-token>` |
| `Content-Type`  | `application/json`           |
| `Accept`        | `application/json`           |

## Path parameters

<ParamField path="subdomain" type="string" required={true}>
  Your workspace subdomain.
</ParamField>

## Body parameters

<ParamField body="phone_number" type="string" required={true}>
  Phone number to validate. E.164 format recommended.
</ParamField>

## Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://dash.xobito.com/api/v1/acme/phone/validate \
    -H "Authorization: Bearer <your_token>" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"phone_number": "+919909919284"}'
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch(
    "https://dash.xobito.com/api/v1/acme/phone/validate",
    {
      method: "POST",
      headers: {
        Authorization: "Bearer <your_token>",
        "Content-Type": "application/json",
        Accept: "application/json",
      },
      body: JSON.stringify({ phone_number: "+919909919284" }),
    }
  );
  const body = await res.json();
  ```

  ```python Python theme={null}
  import requests

  r = requests.post(
      "https://dash.xobito.com/api/v1/acme/phone/validate",
      headers={
          "Authorization": "Bearer <your_token>",
          "Accept": "application/json",
      },
      json={"phone_number": "+919909919284"},
  )
  body = r.json()
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://dash.xobito.com/api/v1/acme/phone/validate');
  curl_setopt_array($ch, [
      CURLOPT_POST => true,
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
          'Authorization: Bearer <your_token>',
          'Content-Type: application/json',
          'Accept: application/json',
      ],
      CURLOPT_POSTFIELDS => json_encode(['phone_number' => '+919909919284']),
  ]);
  $body = json_decode(curl_exec($ch), true);
  curl_close($ch);
  ```
</CodeGroup>

## Example response — valid

```json 200 OK theme={null}
{
  "status": "success",
  "message": "Phone number format is valid",
  "data": {
    "phone": "+919909919284",
    "phone_digits": "919909919284",
    "format_valid": true,
    "country_code": "91",
    "country": "India",
    "national_number": "9909919284",
    "e164": "+919909919284",
    "reason": null,
    "note": "Format validation only. To verify WhatsApp registration, send a template message and check response."
  }
}
```

## Example response — invalid

```json 200 OK theme={null}
{
  "status": "success",
  "message": "Phone number format is invalid",
  "data": {
    "phone": "+00000",
    "phone_digits": "00000",
    "format_valid": false,
    "country_code": null,
    "country": null,
    "national_number": null,
    "e164": null,
    "reason": "Number is too short to be valid",
    "note": "Format validation only. To verify WhatsApp registration, send a template message and check response."
  }
}
```

See [Data Types → Phone validation response](/developers/data-types#phone-validation-response).

## Error responses

| Status | When                    | Example body                                                                                                         |
| ------ | ----------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `401`  | Missing / invalid token | `{"status":"error","message":"Invalid API token"}`                                                                   |
| `403`  | Missing ability         | `{"status":"error","message":"Token does not have the required ability: messages.send"}`                             |
| `422`  | Validation              | `{"status":"error","message":"Validation failed","errors":{"phone_number":["The phone number field is required."]}}` |
| `429`  | Rate limit              | `{"message":"Too many requests","retry_after":45}`                                                                   |
| `500`  | Server error            | `{"status":"error","message":"Failed to validate phone number"}`                                                     |