Nummeropslag API

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 straight into Claude and other AI agents.

🌐 Service: nummeropslag.dk · 🔑 Get a key: /api-noegle · 📖 API reference: Redoc · 🧪 Live sandbox: /api-reference · 🤖 MCP

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.json.

Quick start

server.ts

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/:

Language	File	Run
Bash / curl	`examples/curl.sh`	`./curl.sh 33633363`
Python (stdlib)	`examples/python_client.py`	`python3 python_client.py 33633363`
Node.js 18+	`examples/node_client.js`	`node node_client.js 33633363`
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`
Dify	Installable tool plugin for Workflows, Chatflows and Agents	`integrations/dify`
Langflow	Custom component with Tool Mode support	`integrations/langflow`
Flowise	Ready-to-paste Custom Tool functions and schemas	`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/ 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, 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:

Terminal

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)

Terminal

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):

config.json

{
  "mcpServers": {
    "nummeropslag": {
      "command": "nummeropslag-mcp",
      "env": { "NUMMEROPSLAG_API_KEY": "npk_your_key_here" }
    }
  }
}

Run from source instead (no PyPI)

Terminal

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:

config.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 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) — copy and adapt them freely. The Nummeropslag API service itself and its data are proprietary; use is governed by the terms at nummeropslag.dk.