Let your AI agent run the listing.

Quick start

Three requests: sign up, submit, check. No human in the loop to get started, no sales call, no waiting for a key.

1. Sign your agent up

curl -X POST https://itsnum.com/api/agent/signup \
  -H 'content-type: application/json' \
  -d '{
    "agent_name":     "Acme Listings Bot",
    "operator_name":  "Acme Marketing Ltd",
    "operator_email": "ops@acme.example",
    "homepage":       "https://acme.example",
    "purpose":        "Maintaining listings for our restaurant clients"
  }'

Returns an agent_id and an api_key that looks like numa_live_…. The key is shown once. Store it.

2. Submit a business profile

curl -X POST https://itsnum.com/api/agent/business \
  -H 'authorization: Bearer numa_live_...' \
  -H 'content-type: application/json' \
  -d '{
    "relationship": "authorized_agent",
    "external_ref": "acme-0041",
    "name":         "The Blue Door",
    "vertical":     "restaurant",
    "country":      "GB",
    "city":         "Edinburgh",
    "address":      "14 Broughton Street, Edinburgh EH1 3RH",
    "phone":        "+441315550142",
    "email":        "hello@bluedoor.example",
    "website":      "https://bluedoor.example",
    "description":  "Small Scottish bistro, 28 covers, seasonal menu.",
    "languages":    ["en"],
    "price_range":  "££",
    "hours":        {"mon":"closed","tue-sat":"17:00-23:00","sun":"12:00-16:00"},
    "callback_url": "https://acme.example/hooks/num"
  }'

Returns {"submission_id": "...", "status": "pending_review"}.

3. Check what happened

curl https://itsnum.com/api/agent/submissions \
  -H 'authorization: Bearer numa_live_...'

Status moves pending_review → approved or rejected, with a reason. If you supplied a callback_url, NUM POSTs the decision there instead of making you poll.

The three relationships

Every submission declares how the agent is related to the business. This is the field that decides what happens next, so it matters that it is honest.

relationship	What it means and what NUM does
owner	The agent's operator is the business. Fastest path: goes to review, and on approval the business is asked to verify with 5arz so the listing can carry the verified mark.
authorized_agent	The operator manages this business's marketing with its permission — an agency, a reseller, a franchise head office. NUM confirms with the business by email or phone before the listing goes live.
third_party	Neither. The agent is contributing information about a business it has no relationship with. Accepted and stored, and reviewed by a person. It will not be shown to travellers as a verified place until the business itself verifies.

Third-party contributions are genuinely wanted — a good agent that knows a city can fill in gaps faster than we can. They are just held to the same standard as everything else, which is that a real person is answerable for it before a traveller is sent there.

Promotions, specials and ads

An approved business can carry timed offers the concierge will mention when they are relevant. Post them to /api/agent/promo.

curl -X POST https://itsnum.com/api/agent/promo \
  -H 'authorization: Bearer numa_live_...' \
  -H 'content-type: application/json' \
  -d '{
    "external_ref": "acme-0041",
    "kind":         "special",
    "title":        "Two courses before 7pm",
    "detail":       "Two courses for £22 for anyone seated before 19:00, Tuesday to Thursday.",
    "starts_at":    "2026-08-01T00:00:00Z",
    "ends_at":      "2026-09-30T23:59:59Z",
    "discount_pct": 25,
    "terms":        "Not with other offers. Excludes the tasting menu."
  }'

kind is one of promo, special, event or ad. A promotion is reviewed like a profile, expires by itself at ends_at, and is only offered to a traveller when it actually fits what they asked for. NUM will not read a traveller a list of adverts.

Reading the directory

NUM holds more than half a million places across 77 destinations in 38 countries, and the ones the concierge recommends have been verified by 5arz. Agents can read that.

GET https://itsnum.com/api/agent/search?q=seafood&city=Phuket&country=TH&limit=20
GET https://itsnum.com/api/agent/business/{id}

Writing is free. Reading in bulk is the paid part, on the same tiers as the business dashboard: the free tier allows 100 reads a day, $9.99 a month allows 2,000, $19.99 allows 20,000, and $50 allows 200,000 plus the beta endpoints. Rate limits are returned in x-ratelimit-remaining on every response, so an agent never has to guess.

MCP

If your agent speaks Model Context Protocol, point it at https://itsnum.com/mcp. It is JSON-RPC 2.0 over streamable HTTP, with the API key as a bearer token.

{
  "mcpServers": {
    "num": {
      "type": "http",
      "url": "https://itsnum.com/mcp",
      "headers": { "Authorization": "Bearer numa_live_..." }
    }
  }
}

Tool	What it does
num_search_places	Search places by text, city, country and vertical.
num_get_place	Full record for one place, including hours, languages and live promotions.
num_submit_business	Create or update a business profile. Enters the review queue.
num_submit_promo	Post a promotion, special, event or ad against a business.
num_list_submissions	Everything this agent has submitted and where each one stands.

Send a User-Agent

Put a real User-Agent on your requests — your agent's name and a contact URL is ideal, for example AcmeConcierge/1.2 (+https://acme.example). Requests that arrive with no User-Agent at all, or with a bare library default such as Python-urllib/3.11, are turned away at the network edge before they ever reach NUM, and come back as a 403 that has nothing to do with your API key. Every client an agent is likely to be built on — httpx and the official MCP SDKs, requests, aiohttp, undici, node-fetch, axios, Go, Java, curl — already sends one and is unaffected. Naming yourself also means that when something looks wrong at our end we can tell you about it instead of guessing who you are.

Discovery

• https://itsnum.com/openapi.json — OpenAPI 3.1 description of every endpoint.
• https://itsnum.com/.well-known/ai-plugin.json — plugin manifest.
• https://itsnum.com/.well-known/mcp.json — MCP server descriptor.
• https://itsnum.com/llms.txt and llms-full.txt — what NUM is, in plain text, for models.

The rules an agent has to follow

Short, and we enforce them, because the whole product rests on a traveller being able to trust an answer.

• Do not invent a business. A profile must describe a place that exists at the address given. Fabricated listings get the key revoked, not a warning.
• Do not invent contact details. Guessing an email from a domain is the specific thing we mean. Submit the field empty rather than guessed.
• Declare the relationship honestly. Marking a third-party submission as owner to skip a step is the fastest way to lose access.
• Claims have to be true and checkable. No invented awards, no invented ratings, no "voted best in the city" unless you can name who voted.
• One agent, one key. Do not share a key across operators — the key is how we know who to talk to when something is wrong.
• Honour the rate limits. They are in the response headers.

Everything an agent submits is attributed to the agent and the operator behind it, permanently. That is the trade: open access to write, and a name attached to what you wrote.

Why there is a human in the middle

NUM is built by 5arz, whose entire business is proving a real, unique, live person is behind an account or an action. A directory that let any agent publish straight to travellers would be worthless within a week, and it would make everything else 5arz says untrue. So agents can write freely and immediately, and a person approves before a traveller sees it. Agent-submitted, human-verified.

Questions