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

## Number Lookup API

The **Number Lookup API** performs carrier lookups for phone numbers in **E.164** format. Responses include carrier name, line type, and MCC/MNC codes. Version 1 supports **carrier** lookup only.

<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/number-lookup">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 lookup** | `POST /number-lookup` | Carrier lookup for one E.164 number |
| **Bulk lookup** | `POST /number-lookup/bulk` | Submit a batch lookup job (async) |
| **Job status** | `GET /number-lookup/bulk/{job_id}` | Poll bulk job progress and results |
| **Health** | `GET /number-lookup/health` | Check service availability (no auth) |

---

## Authentication

All endpoints except `/number-lookup/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 Number Lookup 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_lookup` is greater than zero for your organisation, each lookup is charged via the Console Wallet API — including repeat lookups for the same number.

| HTTP status | Error code | Meaning |
|-------------|------------|---------|
| `402` | `INSUFFICIENT_BALANCE` | Wallet balance too low |
| `403` | `NUMBER_LOOKUP_DISABLED` | Number lookup not enabled for your organisation |
| `403` | `BILLING_NOT_CONFIGURED` | Billing is not configured |
| `403` | `ORGANIZATION_NOT_FOUND` | Organisation not registered |
| `422` | — | Invalid E.164 format or request validation error |
| `503` | `NUMBER_LOOKUP_UNAVAILABLE` | Lookup provider unavailable |

---

## Phone number format

All phone numbers must be in **E.164** format, for example `+38766000111`.

---

## Response envelope

Successful responses:

```json
{
  "success": true,
  "data": {
    "phone_number": "+38766000111",
    "country_code": "BA",
    "national_format": "066 000-111",
    "valid": true,
    "carrier": {
      "name": "BH Telecom",
      "type": "mobile",
      "mcc": "218",
      "mnc": "90"
    }
  }
}
```

Error responses:

```json
{
  "success": false,
  "error": {
    "code": "NUMBER_LOOKUP_UNAVAILABLE",
    "message": "Number lookup service unavailable"
  }
}
```

### Lookup result fields

| Field | Description |
|-------|-------------|
| `phone_number` | Normalized E.164 phone number |
| `country_code` | ISO 3166-1 alpha-2 country code |
| `national_format` | Nationally formatted number |
| `valid` | Whether the number is considered valid |
| `carrier.name` | Carrier name when available |
| `carrier.type` | Line type (e.g. `mobile`, `landline`) |
| `carrier.mcc` | Mobile Country Code |
| `carrier.mnc` | Mobile Network Code |

---

## Examples

### Single carrier lookup

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

**Response `200 OK`:**

```json
{
  "success": true,
  "data": {
    "phone_number": "+38766000111",
    "country_code": "BA",
    "national_format": "066 000-111",
    "valid": true,
    "carrier": {
      "name": "BH Telecom",
      "type": "mobile",
      "mcc": "218",
      "mnc": "90"
    }
  }
}
```

### Invalid number (still returns 200)

When a number is found but marked invalid, the API returns `200 OK` with `valid: false`:

```json
{
  "success": true,
  "data": {
    "phone_number": "+15551234567",
    "country_code": "US",
    "national_format": "(555) 123-4567",
    "valid": false
  }
}
```

### Bulk lookup

```bash
curl -X POST "https://api.omaxtelecom.com/numbers/number-lookup/bulk" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": [
      "+38766000111",
      "+38761111222"
    ]
  }'
```

**Response `202 Accepted`:**

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

Poll the job (recommended interval: 1–3 seconds):

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

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

```json
{
  "success": true,
  "data": {
    "job_id": "9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c",
    "status": "completed",
    "total_count": 2,
    "processed_count": 2,
    "failed_count": 0,
    "items": [
      {
        "phone_number": "+38766000111",
        "status": "completed",
        "result": {
          "phone_number": "+38766000111",
          "country_code": "BA",
          "national_format": "066 000-111",
          "valid": true,
          "carrier": {
            "name": "BH Telecom",
            "type": "mobile",
            "mcc": "218",
            "mnc": "90"
          }
        },
        "error": null
      },
      {
        "phone_number": "+38761111222",
        "status": "completed",
        "result": {
          "phone_number": "+38761111222",
          "country_code": "BA",
          "national_format": "061 111-222",
          "valid": true,
          "carrier": {
            "name": "HT Eronet",
            "type": "mobile",
            "mcc": "218",
            "mnc": "03"
          }
        },
        "error": null
      }
    ]
  }
}
```

Maximum **1000** unique phone numbers per bulk request.

### Health check

```bash
curl "https://api.omaxtelecom.com/numbers/number-lookup/health"
```

**Response `200 OK`:**

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

---

## Getting started

1. Enable number lookup 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 /number-lookup/health` to confirm the service is reachable.
4. Look up a single number with `POST /number-lookup`.
5. Use bulk endpoints when you need to look up 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/number-lookup">View API Documentation →</a>
      </Button>
    </CardContent>
  </Card>
</div>

## Need Help?

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