# Quickstart

Two calls: search for a short list, then open the evidence for the doctors you are seriously considering. The MCP server and the HTTP API have the same tools and return the same JSON. This is the New Zealand service; the United States has its own at [/us/docs/](/us/docs/). One MCP address serves both countries.

No sign-up. Short lists are free; full evidence has a daily allowance.

## 1. Connect

| | Address |
|---|---|
| MCP (Streamable HTTP), every country: pass `country: "NZ"` | `https://api.findadoctor.si/mcp` |
| MCP (Streamable HTTP), New Zealand only | `https://api-nz.findadoctor.si/mcp` |
| HTTP API | `https://api-nz.findadoctor.si/api/v1/…` (GET, JSON) |
| OpenAPI 3.1 (parameters and response fields) | [https://api-nz.findadoctor.si/openapi.json](https://api-nz.findadoctor.si/openapi.json) |
| MCP server card | [https://api-nz.findadoctor.si/mcp/server-card](https://api-nz.findadoctor.si/mcp/server-card) |
| Guide for agents | [https://api-nz.findadoctor.si/llms.txt](https://api-nz.findadoctor.si/llms.txt) |

MCP clients that support remote servers connect to either MCP URL above. No sign-in or key is needed. An optional account key (by invitation), sent as Authorization: Bearer, raises the daily allowance.

**With the address for every country, decide the country first**: where the person wants to see a doctor, from the place they mention or what you know about where they live. If nothing settles it (no place given, or a place name used in more than one country, such as Hamilton, with no other clue), ask the person before searching; do not guess, and do not search every country. Pass `country: "NZ"` to `search_doctors`, `list_specialties` and `about_database` (left out, they use the United States, for clients that connected before New Zealand was added). `get_doctor` reads the country from the `nz_` id. `search_gp_practices` and `public_waitlist` are New Zealand only and need no `country`. The New Zealand-only address needs no `country` at all, and neither does the HTTP API below (it is New Zealand only; sending `country` is an error).

**In Claude** (Free, Pro, Max, Team and Enterprise; the Free plan allows one custom connector): Customize → Connectors → + Add → Add custom connector, enter a name and the MCP URL, and Continue. Under Authentication choose No sign in (or add an account key under Request headers as Authorization: Bearer), then Add. On Team and Enterprise an Owner adds it first under Organization settings → Connectors, and members then Connect it. Turn it on in a chat with + → Connectors. [Claude's guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

**In ChatGPT**, where your plan and workspace allow custom MCP servers: Plugins → + → Add custom MCP server, enter a name and the MCP URL, set authentication, then Create as a plugin and install it; in a chat, type @ and pick it. Choose no authentication. [OpenAI's guide](https://developers.openai.com/plugins/deploy/connect-chatgpt).

**In Claude Code, Codex CLI, Gemini CLI and other MCP clients**: add a remote (Streamable HTTP) MCP server with the URL above.

## 2. Search

Give at least one of `need`, `specialty`, `place` or `name`. `need` is a condition, procedure or focus in plain English; `place` is a New Zealand city, suburb, or region or Health NZ district.

```text
GET https://api-nz.findadoctor.si/api/v1/search?need=hip%20replacement&place=Christchurch
```

Each result has `doctor_id`, name, specialties, vocational scope, cities, sectors (`private`, `public`), `specialist_since` (the year the Medical Council first registered them as a specialist in New Zealand, when known), `recognition` (a New Zealand honour or a University of Auckland academic title, when there is one), `match_basis` (with a need: `stated_focus`, `services_listed`, `shared_service_listed`, `specialty`, `specialty_for_symptom`, `profile_text` or `partial`; `shared_service_listed` means only a hospital department or large group page the doctor is linked to lists it, so they may not do it themselves; `specialty_for_symptom` means the need is a symptom few doctors list, such as back pain or dizziness, and the doctor's specialty usually sees it), `place_match` (with a place: `city_or_address`; `city_in_region` when you gave a region or Health NZ district and the doctor's town is in it; `address_contains`, maybe a street name; or `region_page_only`, often a doctor visiting from elsewhere), `detail_has` (what `get_doctor` adds for this doctor) and, when there are any, `warnings` (for example not practising on the Medical Council register). Doctors who are only on the Medical Council register, with no Healthpoint listing, have `listing: "medical_council_register_only"`: their name, specialty and registration dates are known, but no clinic, phone, fees or focus areas, so search the web for where they practise. When a Healthpoint listing we could not match to the register and a register-only entry share a first and last name, both carry `possibly_same_person_as` (the other entry's `doctor_id`): they may be one doctor, so do not present them as two.

A trimmed example (the doctors' names and ids are made up; `…` marks shortened text):

```json
{
  "provider": { "name": "FindADoctor.si New Zealand", "url": "https://findadoctor.si/nz/", "data_version": "nz-public-2026-10-15.5" },
  "before_answering": "This is the free short list: who the doctors are, not the evidence. Before recommending anyone, call get_doctor …",
  "total_matches": 26,
  "offset": 0,
  "results": [
    {
      "rank": 1,
      "doctor_id": "nz_4k9m2x7qph3t",
      "name": "Dr Example Doctor",
      "kind": "Specialist",
      "specialties": ["Orthopaedics"],
      "vocational_scope": "Orthopaedic Surgery",
      "cities": ["Christchurch", "Timaru"],
      "sectors": ["private"],
      "match_basis": "stated_focus",
      "detail_has": ["7 focus areas they list", "clinic phone numbers and addresses", "Medical Council register entry"]
    }
  ],
  "next_step": "Call get_doctor with doctor_ids (up to 10 at once) for the doctors you are considering. …",
  "note": "Confirm phone numbers, fees, insurer status and availability with the clinic before booking. Not medical advice; in an emergency call 111."
}
```

Results are ranked first by how directly the doctor's own listing matches the need: doctors who list all its words, then (for a symptom) `specialty_for_symptom`, then doctors who list some of the words, then words only in profile text. Within each, results are ranked by `place_match`; with `experienced_first=true`, by `specialist_since` (earliest first) after that. Doctors only on the register come after all listed doctors. Not by quality or outcomes: years as a specialist are seniority, not skill. `need_note` names the specialties added for a symptom (a grouping by common sense, not a diagnosis), or says that no doctor lists all the words. When you search a town or suburb, `place_note` says how many more doctors match with the wider region as the place (in another town of the region, or only on Healthpoint's region page, often public-hospital doctors whose page names only the hospital) and which place to search to include them. With `specialty`, `specialty_read_as` lists the specialty names searched, and `specialty_note` explains when a child-specific wording was searched as the general specialty with `child=true`. Up to 10 results per search; paging stops at 30. Narrow the need or the place instead of paging.

## 3. Open the evidence

```text
GET https://api-nz.findadoctor.si/api/v1/doctors?ids=nz_4k9m2x7qph3t,nz_8w2c5n1kd7ra
```

Up to 10 doctor ids per call. Without an account, each network address can open 5 different doctors' evidence a day; with an account key (by invitation), 100. Opening the same doctor again the same day is free. Doctors that do not fit in one reply come back under `not_returned_yet`, already counted, so ask again for them at no extra cost.

Each doctor can have: specialties, title and qualifications; focus areas and subspecialties they list; languages; whether their services see children; every private and public service with clinic addresses, phone numbers and websites, the procedures and conditions the service lists, fee categories, ages, hours and how to get referred; whether a service or the doctor's own page says Southern Cross Affiliated Provider or nib First Choice; the Medical Council register entry (status, scope of practice, conditions, practising certificate dates); and source links with read dates. The doctor's own profile text is not reproduced: give the person the Healthpoint link (`sources.healthpoint`).

> Phone numbers, fees and insurer status change. Tell the person to confirm them with the clinic, and cover with their insurer (often prior approval), before booking.

Each doctor can also have `experience`: every vocational scope with the date it was granted and years since, years as a specialist in New Zealand (provisional scopes not counted), earliest registration date on the register entry, primary medical degree year, New Zealand honours (with the list and citation), University of Auckland academic title and hospital appointments, and an approximate count of papers with a New Zealand affiliation in Europe PMC (with a link to the list). Seniority signals, not a measure of quality.

## 4. General practices

`search_doctors` is for specialists: general practitioners are left out unless you ask for the specialty General Practice. To find a GP, search practices instead:

```text
GET https://api-nz.findadoctor.si/api/v1/gp-practices?place=Hamilton&enrolling=yes&age=34
```

Each practice has `enrolling` (`yes`, `restricted`, `no`, `does not apply` for urgent care, or `unknown`), its own note on who it takes, locations with phone numbers, the first fee table on the page, usually for enrolled patients (or with `age`, just the row for that age), online booking, hours and the GPs listed there. Each result's `kind` says what sort of practice it is (for example nurse-led, online, or a student health clinic). `kind=urgent_care` finds accident and urgent medical care and after-hours clinics. Practices are not doctors: searching them does not count toward the daily doctor allowance. Enrolment and fees change often, so tell the person to phone the practice.

## 5. Public waiting lists

```text
GET https://api-nz.findadoctor.si/api/v1/waitlist?specialty=Orthopaedic&district=Canterbury
```

Health NZ figures by district and specialty, for the latest month and the same month a year earlier: people waiting for a first specialist assessment and for planned treatment, and the share waiting over 120 days. Useful when the person is weighing public against private care. Health NZ names some specialties differently in the two lists (for example Orthopaedics for a first assessment and Orthopaedic Surgery for treatment); asking for either returns both.

## Tools

| MCP tool | HTTP | What it does |
|---|---|---|
| `search_doctors` | `GET /api/v1/search` | Free short list for a need, specialty, place or name. |
| `get_doctor` | `GET /api/v1/doctors?ids=…` or `/api/v1/doctors/{doctor_id}` | Evidence for up to 10 doctors. Counted per day. |
| `search_gp_practices` | `GET /api/v1/gp-practices` | General practices (or urgent care) by place: taking new patients or not, fees by age, GPs listed. Not counted. |
| `list_specialties` | `GET /api/v1/specialties` | Specialty names used here (Healthpoint categories) with doctor counts. |
| `public_waitlist` | `GET /api/v1/waitlist` | Health NZ public waiting lists by district and specialty. |
| `about_database` | `GET /api/v1/about` | Sources, read dates, coverage counts and known gaps. |

### search_doctors parameters

| Parameter | Meaning |
|---|---|
| `need` | Condition, procedure or focus in plain English, e.g. `ACL reconstruction`, `endometriosis`, `cataract surgery`. Matched against the focus areas doctors list, then the procedures their services list, their specialty, and their own profile text and hospital web page (used for matching only, not shown). |
| `specialty` | A specialty name from `list_specialties`, a word from one, or a plain word, e.g. `orthopaedic`, `ENT`, `eye`, `skin`. Matched word by word (endings may differ, so `cardiologist` finds Cardiology; not fragments inside words); the reply's `specialty_read_as` lists the names searched. |
| `place` | A New Zealand city, suburb, or region or Health NZ district, e.g. `Christchurch`, `North Shore`, `Hawke's Bay`, `Capital and Coast` (the district names `public_waitlist` uses work). Macrons are optional (`Whangarei` finds Whangārei). |
| `name` | The doctor's name or part of it, to check a named doctor. Titles such as Dr or Prof are ignored and word order does not matter (`Dr Jane Smith` finds Jane Mary Smith); exact names come first. |
| `sector` | `any` (default), `private` (the doctor lists a private service) or `public` (a Health NZ service). |
| `child` | `true` when the patient is a child: among doctors in the same place who match the need equally well, those in paediatrics or who list children in their focus come first, then those whose services say they see children; doctors whose services list only adult ages are left out. Most listings do not say, so those doctors stay in. |
| `language` | A language other than English that the doctor or a small clinic lists, e.g. `Mandarin`, `Hindi`, `Samoan`. |
| `gender` | `female` or `male`. Only when the person asks. Gender is recorded for only a small share of doctors (when their Healthpoint page states it); the others are left out, and `gender_note` says how many. |
| `southern_cross_affiliated` | `true` keeps doctors whose own Healthpoint page or at least one of whose service pages says Southern Cross Affiliated Provider. Cover still depends on the policy. |
| `experienced_first` | `true` puts doctors who have been specialists longest first, among doctors who match the need and place equally well. Only when the person asks for an experienced or senior doctor. |
| `limit`, `offset` | Up to 10 results per page; paging stops at 30 results. |

### get_doctor parameters

| Parameter | Meaning |
|---|---|
| `doctor_ids` | Up to 10 `doctor_id`s from search results (HTTP: `ids`, comma-separated). |
| `doctor_id` | One `doctor_id`. |

A doctor keeps the same `doctor_id` when the database is rebuilt, including when a doctor who was only on the Medical Council register is later found on Healthpoint. If an id does change, the old id still returns the doctor, and the reply's `id_changed` gives the current id to use from then on.

### search_gp_practices parameters

| Parameter | Meaning |
|---|---|
| `place` | A New Zealand city, suburb or region, as for `search_doctors`. |
| `name` | Part of the practice's name. Give `place` or `name`. |
| `enrolling` | `any` (default), `yes` (taking new enrolments) or `yes_or_restricted` (also practices taking only some people). |
| `age` | The person's age (0 to 120): each practice shows only the fee row for that age. |
| `language` | A language other than English the practice lists. |
| `kind` | `gp` (default: general practices), `urgent_care` (accident and urgent medical care, after hours) or `any`. |
| `limit`, `offset` | Up to 10 practices per page. |

### public_waitlist parameters

| Parameter | Meaning |
|---|---|
| `specialty` | e.g. `Orthopaedic`, `ENT`, `General Surgery`, `eye`. An exact name is matched first, then names that contain each word, then the same without words like "surgery" and with common plain words mapped (eye → Ophthalmology, heart surgery → Cardiothoracic, cardiologist → Cardiology, internal medicine → General Medicine), then part of a name; both of Health NZ's names for the same specialty are returned. |
| `district` | Health NZ district, e.g. `Auckland`, `Canterbury`, `Capital and Coast`. Part of a name also matches, so `Canterbury` includes South Canterbury. A city or region is read as its district (`Wellington` → Capital and Coast, `Dunedin` → Southern) and the reply's `district_read_as` says so. Macrons are optional. |

## Errors

| Status | Meaning | What to do |
|---|---|---|
| 400 | A parameter is missing or invalid | The message names what to change. |
| 401 | The account key is not valid | Send a valid key, or none. |
| 403 | A web page on another site asked for doctor details from a visitor's browser (`cross_site`) | Call from your agent or server, not from another site's page. |
| 404 | No doctor with that id | Use a `doctor_id` from a search. |
| 429 | Rate limit or daily doctor allowance used up | Tell the person; the message says when it resets. |
| 503 | Busy or starting | Retry shortly. |

Limits per connection: [Limits](/nz/docs/limits/). What the data holds and where it comes from: [Data](/nz/docs/data/).

---

Web page: https://findadoctor.si/nz/docs/ · FindADoctor.si New Zealand · data version nz-public-2026-10-15.5 · Not medical advice; in an emergency, call 111.