# ID & Format Oracle (`thenightowl/id-format-oracle`) Actor

Validate and format identifiers worldwide, offline: IBAN/BIC, VAT and tax numbers, national IDs, company registrations, phones, postal codes, 240+ standard numbers, plus Emirates ID, Saudi ID, Kuwait Civil ID. MCP server + REST for AI agents. States what was checked and its confidence. No logging.

- **URL**: https://apify.com/thenightowl/id-format-oracle.md
- **Developed by:** [Mohamad Najia](https://apify.com/thenightowl) (community)
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 validation checks

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## ID & Format Oracle — validate identifiers worldwide, offline, for AI agents

**MCP server + REST API.** Give your agent one tool set that answers "is this number well-formed?" for IBANs, BICs, VAT and
tax numbers, national IDs, company registrations, phone numbers, postal codes and 240+ standard numbers (ISBN, LEI, IMEI,
ISIN…) across 90 countries — plus a curated GCC/MENA layer that no library ships: **Emirates ID, UAE TRN, Saudi
National ID/Iqama, Saudi VAT, Kuwait Civil ID, Qatar ID, Bahrain CPR, Egypt National ID.**

Every answer says **what was checked** (format, dates, check digits), **how sure it is** (`data_confidence`), **why** it
failed, and **where the rule comes from** (`sources[]`). Deterministic code plus versioned data: no AI inside, no
registry lookups, no query logging — nothing about your users leaves the request.

### Tools (7)

| tool | use when | price |
|---|---|---|
| `validate_identifier` | you know the type (`code` from `list_identifiers`): national IDs, tax/VAT, company numbers, standards | $0.001 |
| `detect_identifier` | a form field or document holds a number of unknown type — returns candidate types, best first | $0.003 |
| `validate_iban` | IBAN → validity, country, bank code/name, BIC, SEPA, printed form | $0.001 |
| `validate_bic` | BIC/SWIFT code → validity, bank, country, branch, test flag | $0.001 |
| `validate_phone` | any phone number → valid/possible, E.164, type (mobile/fixed…), region, time zones | $0.001 |
| `validate_postal_code` | postal/ZIP format for 158 countries; says when a country has none (UAE, Qatar) | $0.001 |
| `list_identifiers` | discover the 250+ supported codes, by country or category | free |

Prices are per successful call on Apify (pay-per-event). Self-hosted: `list_identifiers`, `validate_postal_code` and
`validate_bic` are free without a key at 30 req/min; keyed plans for the rest.

### Example

```json
// validate_identifier {"number": "784-1990-1234567-?", "code": "ae_emirates_id"}
{
  "result": {"valid": true, "identifier": "ae_emirates_id", "country": "AE", "compact": "784199012345670",
             "formatted": "784-1990-1234567-0", "checks": ["format", "year", "luhn"], "details": {"birth_year": 1990}},
  "data_confidence": "high",
  "estimated_items": [],
  "sources": ["https://learn.microsoft.com/en-us/purview/sit-defn-uae-identity-card-number", "https://icp.gov.ae/en/", "https://en.wikipedia.org/wiki/Luhn_algorithm"],
  "data_version": "2026.10.31-1",
  "warnings": [],
  "disclaimer": "Structural validation only (format, dates, check digits). A valid result does not mean the identifier is issued, active or belongs to anyone; no registry was consulted. Not legal or compliance advice."
}
```

### Confidence, honestly

- **high** — check-digit algorithm from a public specification (IBAN mod-97, Luhn for Emirates ID, mod-11 for Kuwait Civil ID, every python-stdnum module).
- **medium** — community-documented checksum with no official spec (Saudi ID Luhn), or pattern-only postal codes.
- **low** — structure only (UAE TRN, Saudi VAT, Qatar ID, Bahrain CPR, Egypt NID): a pass proves the shape, nothing more. `estimated_items[]` says exactly that.

### Connect

- **Apify (metered):** Standby URL + `/mcp`, header `Authorization: Bearer <your Apify token>`.
- **Self-hosted:** `claude mcp add idcheck --transport http https://idcheck.noahsarch.tech/mcp --header "X-API-Key: <key>"`
- **REST:** `POST https://idcheck.noahsarch.tech/v1/tools/<tool>` with a JSON body; OpenAPI at `/openapi.json`, docs at `/docs`.

### Built on

[python-stdnum](https://arthurdejong.org/python-stdnum/) (LGPL, 244 validators), [phonenumbers](https://github.com/daviddrysdale/python-phonenumbers)
(Google libphonenumber data), [schwifty](https://github.com/mdomke/schwifty) (IBAN/BIC with bank registries),
Unicode CLDR postal-code patterns, and our own GCC/MENA validators (sources in each result). All pure Python; audited for
network access — none at request time.

### Not legal or compliance advice

A structurally valid identifier is not a verified one. For KYC/AML, tax or sanctions decisions, confirm with the issuing
authority or an official lookup service.

***

### بالعربية

**عرّاف المعرّفات والصيغ** — خادم MCP وواجهة REST للتحقق البنيوي من المعرّفات حول العالم دون اتصال بأي سجل: IBAN وBIC،
أرقام الضريبة وضريبة القيمة المضافة، أرقام الهوية الوطنية، سجلات الشركات، أرقام الهواتف، الرموز البريدية و240+ رقماً معيارياً،
إضافةً إلى طبقة خليجية/عربية مُنتقاة: **الهوية الإماراتية، رقم التسجيل الضريبي الإماراتي، الهوية الوطنية/الإقامة السعودية،
ضريبة القيمة المضافة السعودية، البطاقة المدنية الكويتية، البطاقة القطرية، الرقم الشخصي البحريني، الرقم القومي المصري.**

كل إجابة تذكر ما تم فحصه، ومستوى الثقة، وسبب الرفض، والمصدر. شيفرة حتمية وبيانات مُرقّمة: لا ذكاء اصطناعي داخلها، لا استعلام
لأي سجل، ولا تسجيل للاستعلامات. التحقق بنيوي فقط وليس إثباتاً لصدور المعرّف أو ملكيته؛ ليس استشارة قانونية أو امتثالية.

# Changelog

This Actor's version history is a separate document: https://apify.com/thenightowl/id-format-oracle/changelog.md

# Actor input Schema

## Actor input object example

```json
{}
```

# Actor output Schema

## `mcpEndpoint` (type: `string`):

Point your MCP client here (Authorization: Bearer <Apify token>). 7 tools: validate_identifier, list_identifiers, detect_identifier, validate_iban, validate_bic, validate_phone, validate_postal_code.

## `readiness` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("thenightowl/id-format-oracle").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("thenightowl/id-format-oracle").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call thenightowl/id-format-oracle --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,thenightowl/id-format-oracle"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/X3U5oH1K4P8IOIKni/builds/gHJ9ibtExaqXDqzMo/openapi.json