Content
# Nummeropslag API
Public **Partner API** + **MCP server** for Danish phone-number lookup, caller-ID and spam/trust signals.
<!-- mcp-name: io.github.andrey-tut/nummeropslag -->
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" }
}
}
}
```
<details><summary>Run from source instead (no PyPI)</summary>
```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.
</details>
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).
