import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "zudoku/ui/Card";
import { Button } from "zudoku/ui/Button";

## Phone Validation API

The **Phone Validation API** validates phone numbers and returns structured metadata about each number. Accept numbers in **E.164** format or national format with an optional **region** code. Responses include validity, formatting, country, line type, carrier, geocoder data, and time zones.

<div className="not-prose my-4">
  <Card>
    <CardContent className="pt-6">
      <div className="flex flex-wrap items-center gap-3">
        <Button asChild>
          <a href="/api/phone-validation">View API Documentation →</a>
        </Button>
        <span className="text-sm text-muted-foreground">
          Interactive reference, request/response schemas, and examples
        </span>
      </div>
      <p className="mt-3 text-sm text-muted-foreground">
        Use the <strong>Interactive Playground</strong> on the API reference page to test endpoints with your Console <code>client_id</code> and <code>client_secret</code>.
      </p>
    </CardContent>
  </Card>
</div>

**Base URL:** `https://api.omaxtelecom.com/numbers/`

---

## What can you do?

| Capability | Endpoint | Description |
|------------|----------|-------------|
| **Single validation** | `POST /phone-validation` | Validate one phone number |
| **Bulk validation** | `POST /phone-validation/bulk` | Submit a batch validation job (async) |
| **Job status** | `GET /phone-validation/bulk/{job_id}` | Poll bulk job progress and results |
| **Health** | `GET /phone-validation/health` | Check service availability (no auth) |

---

## Authentication

All endpoints except `/phone-validation/health` require OAuth 2.0 Client Credentials via **OmaxTelecom ID**:

```http
Authorization: Bearer <access_token>
```

Obtain a token from the shared OmaxTelecom API auth endpoint. This is **not** under the Phone Validation base URL — see the [Auth API reference](/api/auth):

```
POST https://api.omaxtelecom.com/auth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}
```

Get your `client_id` and `client_secret` from [OmaxTelecom Console](https://console.omaxtelecom.com).

For M2M clients without an `organization` claim in the token, include:

```http
X-Organization-Id: <organization_id>
```

---

## Billing

When `price_per_validation` is greater than zero for your organisation, each successful validation is charged via the Console Wallet API — including repeat validations for the same number.

| HTTP status | Error code | Meaning |
|-------------|------------|---------|
| `402` | `INSUFFICIENT_BALANCE` | Wallet balance too low |
| `403` | `PHONE_VALIDATION_DISABLED` | Phone validation not enabled for your organisation |
| `403` | `BILLING_NOT_CONFIGURED` | Billing is not configured |
| `403` | `ORGANIZATION_NOT_FOUND` | Organisation not registered |
| `422` | `VALIDATION_ERROR` | Invalid request body or phone number format |

---

## Response envelope

Successful responses:

```json
{
  "success": true,
  "data": {
    "valid": true,
    "possible": true,
    "phone_number": "+38766000111",
    "national_format": "066 000-111",
    "country_code": "BA",
    "calling_code": "387",
    "number_type": "MOBILE",
    "geocoder": {
      "description": "Bosnia and Herzegovina",
      "locale": "en"
    },
    "time_zones": ["Europe/Sarajevo"],
    "carrier": {
      "name": "BH Telecom",
      "locale": "en"
    }
  }
}
```

Error responses:

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The phone number field format is invalid."
  }
}
```

### Validation result fields

| Field | Description |
|-------|-------------|
| `valid` | Whether the number is valid for the detected region |
| `possible` | Whether the number could be valid with more digits |
| `phone_number` | Normalized E.164 phone number |
| `national_format` | Nationally formatted number |
| `country_code` | ISO 3166-1 alpha-2 country code |
| `calling_code` | International calling code |
| `number_type` | Line type (e.g. `MOBILE`, `FIXED_LINE`) |
| `geocoder` | Geographic description for the number |
| `time_zones` | Associated time zones |
| `carrier` | Carrier name when available |

---

## Examples

### Validate E.164 number

```bash
curl -X POST "https://api.omaxtelecom.com/numbers/phone-validation?phone_number=%2B38766000111&locale=en" \
  -H "Authorization: Bearer <access_token>"
```

**Response `200 OK`:**

```json
{
  "success": true,
  "data": {
    "valid": true,
    "possible": true,
    "phone_number": "+38766000111",
    "national_format": "066 000-111",
    "country_code": "BA",
    "calling_code": "387",
    "number_type": "MOBILE",
    "geocoder": {
      "description": "Bosnia and Herzegovina",
      "locale": "en"
    },
    "time_zones": ["Europe/Sarajevo"],
    "carrier": {
      "name": "BH Telecom",
      "locale": "en"
    }
  }
}
```

### Validate national number with region

```bash
curl -X POST "https://api.omaxtelecom.com/numbers/phone-validation?phone_number=066000111&region=BA&locale=en" \
  -H "Authorization: Bearer <access_token>"
```

Returns the same normalized result as the E.164 example above.

### Bulk validation

```bash
curl -X POST "https://api.omaxtelecom.com/numbers/phone-validation/bulk" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "locale": "en",
    "validations": [
      {"phone_number": "+38766000111"},
      {"phone_number": "066000111", "region": "BA"}
    ]
  }'
```

**Response `202 Accepted`:**

```json
{
  "success": true,
  "data": {
    "job_id": "9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c"
  }
}
```

Poll the job:

```bash
curl "https://api.omaxtelecom.com/numbers/phone-validation/bulk/9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c" \
  -H "Authorization: Bearer <access_token>"
```

**Response `200 OK` (processing):**

```json
{
  "success": true,
  "data": {
    "job_id": "9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c",
    "status": "processing",
    "total_count": 2,
    "processed_count": 1,
    "failed_count": 0,
    "items": [
      {
        "phone_number": "+38766000111",
        "region": null,
        "locale": "en",
        "status": "completed",
        "result": {
          "valid": true,
          "possible": true,
          "phone_number": "+38766000111",
          "national_format": "066 000-111",
          "country_code": "BA",
          "calling_code": "387",
          "number_type": "MOBILE"
        },
        "error": null
      },
      {
        "phone_number": "066000111",
        "region": "BA",
        "locale": "en",
        "status": "pending",
        "result": null,
        "error": null
      }
    ]
  }
}
```

### Health check

```bash
curl "https://api.omaxtelecom.com/numbers/phone-validation/health"
```

**Response `200 OK`:**

```json
{
  "ok": true,
  "timestamp": "2026-08-20T16:42:00+00:00"
}
```

---

## Getting started

1. Enable phone validation for your organisation in [OmaxTelecom Console](https://console.omaxtelecom.com).
2. Obtain an access token via **OmaxTelecom ID** using your `client_id` and `client_secret`.
3. Call `GET /phone-validation/health` to confirm the service is reachable.
4. Validate a single number with `POST /phone-validation`.
5. Use bulk endpoints when you need to validate large lists asynchronously.

## API Documentation

<div className="not-prose my-6">
  <Card>
    <CardHeader>
      <CardTitle>Complete API Reference</CardTitle>
      <CardDescription>
        Explore all endpoints with interactive examples, schemas, and authentication details.
      </CardDescription>
    </CardHeader>
    <CardContent>
      <Button asChild>
        <a href="/api/phone-validation">View API Documentation →</a>
      </Button>
    </CardContent>
  </Card>
</div>

## Need Help?

Contact [support@omaxtelecom.com](mailto:support@omaxtelecom.com) for integration support.