Org APImedicalcouncil.org.nz ↗
Search and retrieve registered doctor profiles from the Medical Council of New Zealand public register, including qualifications, specialty, and scope of practice.
What is the Org API?
The MCNZ Register API provides 3 endpoints for searching and retrieving doctor profiles from the Medical Council of New Zealand's public register. The search_doctors endpoint accepts filters for name, location, specialty, and registration status, returning up to 20 results per page. The get_doctor_details endpoint returns structured profile data including qualifications, scope of practice dates, and any conditions on registration.
curl -X GET 'https://api.parse.bot/scraper/1c6e1494-adcf-4bf9-938f-637c95443b45/search_doctors?area=general-practice&start=0&status=practising&keyword=Smith&location=auckland' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace medicalcouncil-org-nz-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: MCNZ Register of Doctors — search, filter, drill into profiles."""
from parse_apis.mcnz_register_of_doctors_api import MCNZ, RegistrationStatus, DoctorNotFound
client = MCNZ()
# Fetch register metadata to see available filter options.
metadata = client.registermetadatas.get()
print(f"Register updated: {metadata.last_updated}, locations: {len(metadata.locations)}")
# Search for practising doctors by keyword, capped at 5 results.
for doc in client.doctorsummaries.search(keyword="Smith", status=RegistrationStatus.PRACTISING, limit=5):
print(doc.name, doc.location, doc.practising_certificate_expiry)
# Drill into the first result's full profile via the summary→detail navigation.
summary = client.doctorsummaries.search(keyword="Smith", limit=1).first()
if summary:
profile = summary.details()
print(profile.name, profile.specialty, profile.practising_certificate_dates)
for qual in profile.qualifications:
print(qual.title, qual.details)
# Typed error handling: catch a not-found slug.
try:
client.doctors.get(slug="nonexistent-doctor-xyz")
except DoctorNotFound as exc:
print(f"Doctor not found: {exc.slug}")
print("exercised: registermetadatas.get / doctorsummaries.search / summary.details / doctors.get / DoctorNotFound")
Search the MCNZ public register of doctors. Supports filtering by keyword (name), location, area of medicine, and registration status. Returns up to 20 results per page. Pagination advances via the start parameter in multiples of 20. At least one filter should be provided to get meaningful results; calling with no filters returns all registered doctors.
| Param | Type | Description |
|---|---|---|
| area | string | Area of medicine slug from get_register_metadata areas_of_medicine (e.g. 'general-practice', 'emergency-medicine', 'anaesthesia'). |
| start | integer | Pagination offset in multiples of 20. |
| status | string | Registration status slug: 'practising', 'not-practising', 'inactive', 'suspended'. |
| keyword | string | Search by doctor name or keyword. |
| location | string | Location slug from get_register_metadata locations (e.g. 'auckland', 'christchurch', 'wellington'). |
{
"type": "object",
"fields": {
"count": "integer number of doctors returned in this page",
"start": "integer pagination offset used",
"doctors": "array of doctor summary objects",
"total_results": "integer total number of matching doctors"
},
"sample": {
"data": {
"count": 20,
"start": 0,
"doctors": [
{
"url": "https://www.mcnz.org.nz/registration/register-of-doctors/doctor/smith-abigail-mary/",
"name": "Smith, Abigail Mary",
"slug": "smith-abigail-mary",
"status": "Practising",
"location": "Auckland",
"specialty": "General Practice",
"practising_certificate_expiry": "31 May 2027"
}
],
"total_results": 203
},
"status": "success"
}
}About the Org API
What the API covers
The API exposes the Medical Council of New Zealand's public register of doctors across three endpoints. search_doctors accepts a keyword (name or free text), a location slug (e.g. auckland, christchurch), an area slug for specialty (e.g. general-practice, emergency-medicine), a status slug (e.g. practising, not-practising, inactive), and a start integer for paginating through results in multiples of 20. Each result in the doctors array includes the doctor's name, URL slug, location, specialty, status, and practising certificate expiry date.
Doctor detail profiles
get_doctor_details accepts a slug from search results and returns the full profile: name, status, location, specialty, conditions on registration, general_scope and provisional_scope award dates, and a qualifications array where each entry has a title and details field. This makes it straightforward to verify whether a practitioner holds a specific qualification or has conditions attached to their registration.
Filter values and register metadata
get_register_metadata takes no inputs and returns the canonical lists of valid filter slugs: locations, areas_of_medicine, and statuses, each as arrays of value/label pairs. It also returns a last_updated string indicating when the register was last refreshed. Always call this endpoint first when building a filter UI or constructing parameterised searches against search_doctors, since slug values can change as the council updates its taxonomy.
The Org API is a managed, monitored endpoint for medicalcouncil.org.nz — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when medicalcouncil.org.nz changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official medicalcouncil.org.nz API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Verify a doctor's current registration status and practising certificate expiry before a referral or appointment
- Build a practitioner directory filtered by specialty and location for a patient-facing healthcare platform
- Monitor for changes in registration conditions on a set of practitioner slugs over time
- Aggregate qualification data across a cohort of doctors for workforce research
- Cross-check a submitted CV's stated qualifications against the official MCNZ register
- Populate autocomplete search for NZ doctors by name using the keyword filter in search_doctors
- Audit whether practitioners in a clinic roster hold general or provisional scope of practice
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.