# Nummeropslag API ![API](https://img.shields.io/badge/API-REST-009688) ![OpenAPI](https://img.shields.io/badge/OpenAPI-3.1-6BA539?logo=openapiinitiative&logoColor=white) ![Auth](https://img.shields.io/badge/auth-API%20key-blue) ![Region](https://img.shields.io/badge/region-Denmark%20%F0%9F%87%A9%F0%9F%87%B0-C8102E) ![Examples](https://img.shields.io/badge/examples-curl%20%C2%B7%20python%20%C2%B7%20node%20%C2%B7%20php-lightgrey) ![MCP](https://img.shields.io/badge/MCP-server-7C4DFF?logo=anthropic&logoColor=white) ![License](https://img.shields.io/badge/examples%20license-MIT-green) Public **Partner API** + **MCP server** for Danish phone-number lookup, caller-ID and spam/trust signals. Identify who is calling from a Danish number: company from the official **CVR** register, **telecom operator**, number type, and a **spam/trust verdict** based on anonymous user reports. Powered by official open data β€” not scraping. Use it from any HTTP client, or plug the **[MCP server](#mcp-server-ai-agents-)** straight into Claude and other AI agents. > 🌐 Service: **[nummeropslag.dk](https://nummeropslag.dk)** Β· πŸ”‘ Get a key: **[/api-noegle](https://nummeropslag.dk/api-noegle)** Β· πŸ“– API reference: **[Redoc](https://andrey-tut.github.io/nummeropslag-api/)** Β· πŸ§ͺ Live sandbox: **[/api-reference](https://nummeropslag.dk/api-reference)** Β· πŸ€– [MCP](#mcp-server-ai-agents-) > > This repository contains **only public API docs, the OpenAPI spec, client examples and the MCP server**. The backend source is private. --- ## Authentication All endpoints require an API key, sent in the `X-API-Key` header: ```http X-API-Key: npk_your_key_here ``` Each key has a **plan**, a set of **scopes** (`lookup`, `spam`, `operator`) and a **request quota**. Check your key status any time via `GET /api/v1/partner/me`. Base URL: `https://nummeropslag.dk/api/v1` --- ## Endpoints | Method | Endpoint | Scope | Description | |---|---|---|---| | GET | `/partner/lookup/{e164}` | `lookup` | Full lookup β€” operator, CVR companies, spam/trust signals | | GET | `/partner/spam/{e164}` | `spam` | Compact spam/trust verdict only | | GET | `/partner/operator/{e164}` | `operator` | Telecom operator + number type | | GET | `/partner/search?q=` | `lookup` | Search companies by name (CVR) | | GET | `/partner/me` | β€” | Your key status: plan, scopes, quota/usage | `{e164}` accepts an 8-digit Danish number or full E.164 β€” e.g. `33633363` or `+4533633363`. Full machine-readable contract: [`openapi/openapi.yaml`](openapi/openapi.yaml) Β· [`openapi/openapi.json`](openapi/openapi.json). --- ## Quick start ```bash export NUMMEROPSLAG_API_KEY=npk_your_key_here curl -H "X-API-Key: $NUMMEROPSLAG_API_KEY" \ https://nummeropslag.dk/api/v1/partner/spam/33633363 ``` ## Client examples Ready-to-run, dependency-free clients in [`examples/`](examples/): | Language | File | Run | |---|---|---| | Bash / curl | [`examples/curl.sh`](examples/curl.sh) | `./curl.sh 33633363` | | Python (stdlib) | [`examples/python_client.py`](examples/python_client.py) | `python3 python_client.py 33633363` | | Node.js 18+ | [`examples/node_client.js`](examples/node_client.js) | `node node_client.js 33633363` | | PHP | [`examples/php_client.php`](examples/php_client.php) | `php php_client.php 33633363` | All read the key from the `NUMMEROPSLAG_API_KEY` environment variable. --- ## Workflow integrations Use Nummeropslag as native nodes and tools in popular automation and AI workflow builders: | Platform | Integration | Location | |---|---|---| | n8n | Community node with five operations and AI Tool support | [`integrations/n8n`](integrations/n8n) | | Dify | Installable tool plugin for Workflows, Chatflows and Agents | [`integrations/dify`](integrations/dify) | | Langflow | Custom component with Tool Mode support | [`integrations/langflow`](integrations/langflow) | | Flowise | Ready-to-paste Custom Tool functions and schemas | [`integrations/flowise`](integrations/flowise) | The integrations store the API key in each platform's credential/secret system and send queries only to `https://nummeropslag.dk`. --- ## MCP server (AI agents) πŸ€– Give your AI agent (Claude Desktop, Claude Code, or any **Model Context Protocol** client) direct access to Danish phone-number data. The server in [`mcp/`](mcp/) wraps the Partner API as MCP tools β€” same official data, same privacy rules (no names of private individuals). ### One-click desktop installation Download the latest `nummeropslag-mcp-*.mcpb` bundle from [GitHub Releases](https://github.com/andrey-tut/nummeropslag-api/releases), open it with a compatible desktop client, and enter your Nummeropslag API key when prompted. The bundle uses the managed `uv` runtime, so users do not need to install Python dependencies manually. The canonical registry identifier is `io.github.andrey-tut/nummeropslag`. ### Docker The same stdio server is published as a public OCI image: ```bash docker run --rm -i \ -e NUMMEROPSLAG_API_KEY=npk_your_key_here \ ghcr.io/andrey-tut/nummeropslag-mcp:latest ``` MCP calls are metered against a **separate MCP quota** (not your REST quota); the server sends `X-Client: mcp` automatically. **Tools** | Tool | Description | |---|---| | `lookup_number(number)` | Full record: company (CVR), operator, spam/trust, comments | | `check_spam(number)` | Compact spam/scam verdict (caller-ID style) | | `get_operator(number)` | Operator + number type only (cheapest) | | `search_businesses(query, limit)` | Find Danish companies by name (CVR) | | `api_status()` | Your key's scopes + quota usage | **Setup β€” via PyPI (recommended)** ```bash pip install nummeropslag-mcp # or: uvx nummeropslag-mcp export NUMMEROPSLAG_API_KEY=npk_your_key_here # https://nummeropslag.dk/api-noegle nummeropslag-mcp # stdio transport ``` **Add to Claude Desktop** (`claude_desktop_config.json`) **or Claude Code** (`.mcp.json`): ```json { "mcpServers": { "nummeropslag": { "command": "nummeropslag-mcp", "env": { "NUMMEROPSLAG_API_KEY": "npk_your_key_here" } } } } ```
Run from source instead (no PyPI) ```bash pip install "mcp[cli]" httpx python mcp/server.py ``` …and use `"command": "python", "args": ["/absolute/path/to/nummeropslag-api/mcp/server.py"]` in the config above.
Restart your client, then ask e.g. *"Is +45 70 10 20 30 spam?"* or *"Who owns 33 63 33 63?"*. --- ## Errors Errors use a consistent envelope: ```json { "error": { "code": "forbidden", "message": "…", "details": {} } } ``` Common codes: `unauthorized` (missing/invalid key), `forbidden` (scope not allowed), `rate_limited` (quota exceeded), `not_found`. ## Data & privacy - Core data: official **CVR** (companies + production units) and the Danish **number plan** (SDFI, CC0). - Spam verdicts use **k-anonymity** β€” a public "spam" label requires several independent reports. - **Names of private individuals are never exposed.** Contacts are never uploaded (GDPR-compliant). ## Privacy Policy The MCP server sends only the phone number or business query requested by the user to the first-party Nummeropslag API. It does not read conversations, files, contacts, or call logs. See the full [Nummeropslag privacy policy](https://nummeropslag.dk/privatlivspolitik) for data collection, use, retention, sharing, and contact information. ## License The client examples and OpenAPI spec in this repository are released under the **MIT License** (see [LICENSE](LICENSE)) β€” copy and adapt them freely. The Nummeropslag API service itself and its data are proprietary; use is governed by the terms at [nummeropslag.dk](https://nummeropslag.dk).