Real places
for your agent.

Three requests: sign up, submit, check. Send Authorization: Bearer numa_live_... on every request after signup.

Fields in the Quickstart example

Supply a callback_url and NUM POSTs the decision there instead of making you poll. The full request is in the Quickstart.

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.

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

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."
  }'

NUM holds 2.7M+ places across 106 destinations in 39 countries. Agents can read that.

GET https://itsnum.com/api/agent/destinations
GET https://itsnum.com/api/agent/search?city=Phuket&area=Kata&q=seafood&limit=20
GET https://itsnum.com/api/agent/business/{id}?party_size=4&date=2026-10-02&time=19:30

A place NUM knows has closed is never a search result. Every response carries x-ratelimit-remaining, so an agent never has to guess.

Every place carries a booking block that says how that venue wants bookings to reach it, and a guidance sentence to follow as written. booking.method is one of:

booking.chosen_by_venue tells you whether the venue chose this route itself, or NUM derived it from the listing because nobody has asked the venue yet.

Point your agent at https://itsnum.com/mcp. It is JSON-RPC 2.0 over streamable HTTP, with the API key as a bearer token. The config is in the Quickstart.

Claude, ChatGPT and other clients that support MCP authorization do not need a key. Add https://itsnum.com/mcp as a connector, sign in to your NUM account when the window opens, and approve what the app may do.

OAuth 2.1 with PKCE and dynamic client registration. Metadata at /.well-known/oauth-protected-resource. The connection uses your account’s daily read quota. Access lasts one hour and renews on its own. End it from the app at any time.

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

One click: Add to Cursor · Install in VS Code · Claude Code:

claude mcp add --transport http num https://itsnum.com/mcp

Put a real User-Agent on your requests. Your agent’s name and a contact URL is ideal:

User-Agent: AcmeConcierge/1.2 (+https://acme.example)

Requests with no User-Agent at all, or a bare library default such as Python-urllib/3.11, are turned away at the network edge before they reach NUM. They come back as a 403 that has nothing to do with your API key.

Already send one, 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.

Short, and we enforce them, because the whole product rests on a traveler 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.
• Honor 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.

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 travelers 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 traveler sees it.

Real, mapped places across 106 destinations, live open-now status, booking links with the party size already filled in, and full concierge answers, over plain HTTPS or MCP. The key is shown once and emailed to you. NUM stores only a hash, and re-signing up with the same email rotates it.

curl -X POST https://app.itsnum.com/api/partner/mcp \
  -H "Content-Type: application/json" \
  -H "X-Partner-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
    "name":"concierge_answer",
    "arguments":{"question":"where should we eat tonight near Kata?","destination":"phuket"}}}'

booked:false Booking links are prefilled hand-offs. The response always says booked:false until a real reservation API stands behind it.

Table requests. Confirmed table requests live on a separate keyed surface, https://app.itsnum.com/api/concierge/mcp. request_table asks a venue to hold a table for a NUM member and always answers state:"requested" with booked:false. booking_status tells you what the venue decided.

The concierge surface needs an X-Partner-Key on every call. There is no anonymous path: a tool that can make a real restaurant’s phone ring should not share an access policy with one that reads opening hours. The directory surface is read-only: no bookings, no personal data, ever.

Indexes at /api/partner and /api/concierge. Usage at /api/partner/usage with your key header.

Place data © OpenStreetMap contributors (ODbL) and Google, checked by NUM. Attribution travels with every payload and must be displayed.