Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Findadoctor Si Search API
x-refined-note:
- x-llms-txt differs across the merged source definitions and was not carried
version: '1.0'
description: 'Operations tagged Search across 3 of this provider''s published API definitions: findadoctor-si-fr-openapi.json, findadoctor-si-nz-openapi.json, findadoctor-si-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api-fr.findadoctor.si
- url: https://api-nz.findadoctor.si
- url: https://api.findadoctor.si
security:
- {}
- accountKey: []
tags:
- name: Search
paths:
/api/v1/search:
get:
operationId: searchDoctors
summary: Free short list of doctors in France for a need
description: 'Free short list of doctors in France for a need; use it first whenever the person needs a doctor, specialist or GP in France. Give at least one of need, specialty, place, name or hospital_finess. need = condition, procedure or focus, in French or English (e.g. ''endométriose'', ''prothèse genou'', ''knee replacement'', ''cataract''; common English words are also searched in French); matched against the expertise and procedures doctors state, their official competences and university diplomas, hospital departments and roles, and specialty. specialty = French or English (e.g. ''cardiologie'', ''dermatology'', ''pédiatre'', ''ORL'', ''GP'', ''généraliste''). place = city (''Lyon'', ''Paris'' includes all arrondissements), postcode (''75015''), arrondissement (''Paris 15'', ''Lyon 3e''), département number (''69'', ''2A'') or a practice or hospital name; a text match on practice addresses, not a distance search. Each result: doctor_id, name, gender, specialties (French, as registered), specialties_en, places (up to 3 practices, the ones matching place first), fee_sectors (Ameli category: Secteur 1 = standard fees; Secteur 2 = may charge extra; Non conventionné = not contracted, little reimbursed), optam (agreed to limit extra fees), match_basis (with a need: stated_expertise, official_competence, hospital_department_or_training, several_fields, specialty, specialty_usually_treats, partial), register (rpps, ameli_only = only in the Assurance Maladie directory, website_only = not matched to the official registers), warnings (e.g. barred from practising) and detail_has (what get_doctor adds). With a need, results are ranked by how directly the doctor''s own data matches it: all its words in the expertise or procedures the doctor states, then in official competences or university diplomas, then in hospital department, role or training, then spread over several fields, then in the specialty name; then, when the need is a condition few doctors list, doctors in the specialty that usually treats it (specialty_usually_treats); then doctors matching only some of the words. Without a need, doctors with more data (stated expertise, official competences, profile pages) come first, then in a fixed shuffled order. Not ranked by quality, outcomes, fees or industry links. Then call get_doctor with the doctor_ids you are considering. Up to 10 results per search and paging stops at 30: narrow the need or the place instead of paging.'
parameters:
- name: need
in: query
required: false
description: Condition, procedure or focus, in French or English.
schema:
type: string
maxLength: 200
- name: specialty
in: query
required: false
description: Specialty in French or English, e.g. 'cardiologie', 'dermatology', 'ORL', 'GP' (see list_specialties).
schema:
type: string
maxLength: 200
- name: place
in: query
required: false
description: City, postcode, arrondissement ('Paris 15'), département number ('69', '2A') or a practice or hospital name.
schema:
type: string
maxLength: 200
- name: name
in: query
required: false
description: Doctor's name or part of it, to check a named doctor.
schema:
type: string
maxLength: 200
- name: gender
in: query
required: false
description: Only when the person asks. From the register's civil title (Madame/Monsieur); recorded for almost all doctors.
schema:
type: string
enum:
- female
- male
- name: language
in: query
required: false
description: Language other than French, e.g. 'English', 'Arabic', 'anglais'. Only known for doctors with a Maiia or hospital profile (about 1,800 list one); many others speak it too.
schema:
type: string
maxLength: 200
- name: fee_sector
in: query
required: false
description: 'Assurance Maladie fee category. secteur_1 = standard fees, no extra charges; secteur_1_or_optam = standard fees or agreed limits on extra fees; secteur_2 = may charge extra. Kept if ANY of the doctor''s practices has it (it can differ by practice): check each practice in get_doctor. Most hospital-only doctors have no category. Default any.'
schema:
type: string
enum:
- any
- secteur_1
- secteur_1_or_optam
- secteur_2
- name: online_booking
in: query
required: false
description: True keeps doctors whose Maiia or hospital page shows online booking (Doctolib is not covered).
schema:
type: boolean
- name: teleconsultation
in: query
required: false
description: True keeps doctors offering video consultations on Maiia.
schema:
type: boolean
- name: hospital_finess
in: query
required: false
description: 'Keep doctors whose register address is this hospital site (FINESS number from hospital_procedure_volumes): mostly salaried hospital doctors.'
schema:
type: string
maxLength: 200
- name: limit
in: query
required: false
description: Default 10.
schema:
type: integer
minimum: 1
maximum: 10
- name: offset
in: query
required: false
description: 'For paging (at most 20, so 30 results in all: narrow the search instead).'
schema:
type: integer
minimum: 0
maximum: 20
responses:
'200':
description: JSON result (same as the MCP tool's result)
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResult'
example:
before_you_answer: 'Reply in the language of the user''s own message (if they wrote in English, answer in English), not in French just because the data is French: translate it. This is the free short list: who the doctors are, not the evidence. ...'
provider:
name: FindADoctor.si France
url: https://findadoctor.si/fr/
data_version: fr-public-2026-10-16.3
count: 1
more: false
offset: 0
doctors:
- doctor_id: fr_4k9m2x7qph3t
name: Dr Exemple Chirurgien
gender: male
specialties:
- Chirurgie orthopédique et traumatologie
specialties_en:
- Orthopaedic surgery
places:
- Cabinet Exemple, 1 rue de l'Exemple, 69000 Lyon
fee_sectors:
- Secteur 2
optam: true
match_basis: stated_expertise
register: rpps
detail_has:
- stated expertise
- official register entry
- fee category per practice
'400':
description: 'bad arguments, or the search was too broad (too_slow): the message says what to change'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: 'the Authorization header was sent but is invalid or expired (invalid_token): send no header or a valid account key'
headers:
WWW-Authenticate:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: rate_limited (too many requests) or daily_limit (daily doctor limit reached); the message says when it resets
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
Retry-After:
description: seconds to wait
schema:
type: integer
'500':
description: internal error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: 'busy or starting (busy, unavailable): retry after Retry-After'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
Retry-After:
description: seconds to wait
schema:
type: integer
tags:
- Search
servers:
- url: https://api-fr.findadoctor.si
components:
schemas:
SearchResult:
type: object
properties:
before_you_answer:
type: string
provider:
$ref: '#/components/schemas/Provider'
count:
type: integer
more:
type: boolean
description: more results after this page (paging stops at 30)
offset:
type: integer
doctors:
type: array
items:
$ref: '#/components/schemas/SearchItem'
need_note:
type: string
description: 'with a need: no doctor lists all its words, or which specialties were added as specialty_usually_treats'
specialty_from_need:
type: string
description: need was only a specialty name, so it was searched as specialty
place_from_need:
type: string
description: a city in need was read as the place
place_note:
type: string
description: how the place was read (city in several départements, or a practice name)
filter_note:
type: string
description: language, online booking and video filters only know doctors with a profile page
hospital:
type: object
description: 'with hospital_finess: the hospital site (or the sites of a legal entity)'
hospital_warning:
type: string
hospital_note:
type: string
next_step:
type: string
Provider:
type: object
properties:
name:
type: string
url:
type: string
data_version:
type: string
description: who publishes this data and which build
SearchItem:
type: object
properties:
doctor_id:
type: string
pattern: ^fr_[0-9a-z]{12}$
description: use with get_doctor
name:
type: string
gender:
type: string
enum:
- female
- male
specialties:
type: array
items:
type: string
description: French, as registered (RPPS, Ameli) or on the profile page
specialties_en:
type: array
items:
type: string
places:
type: array
items:
type: string
description: 'practice: name, address, postcode and city (up to 3; the ones matching place first)'
fee_sectors:
type: array
items:
type: string
description: 'Ameli fee category of the doctor''s practices: Secteur 1 (standard fees), Secteur 2 (may charge extra), Non conventionné'
optam:
type: boolean
description: signed up to OPTAM at some practice (agreed to limit extra fees)
match_basis:
type: string
enum:
- stated_expertise
- official_competence
- hospital_department_or_training
- several_fields
- specialty
- specialty_usually_treats
- partial
description: 'with a need: where the doctor''s own data matches it'
register:
type: string
enum:
- rpps
- ameli_only
- website_only
description: rpps = in the official register; ameli_only = only in the Assurance Maladie directory; website_only = not matched to the official registers
warnings:
type: array
items:
type: string
detail_has:
type: array
items:
type: string
description: what get_doctor adds for this doctor
Error:
type: object
properties:
error:
type: string
description: bad_args, too_slow, daily_limit, rate_limited, busy, unavailable, sign_in_required, invalid_token, cross_site, not_found, internal
message:
type: string
description: what to change or when to retry
SearchResult_2:
type: object
properties:
provider:
$ref: '#/components/schemas/Provider'
before_answering:
type: string
total_matches:
type: integer
offset:
type: integer
results:
type: array
items:
$ref: '#/components/schemas/SearchItem_2'
next_step:
type: string
note:
type: string
specialty_read_as:
type: array
items:
type: string
description: 'with specialty: the specialty names searched'
specialty_note:
type: string
place_note:
type: string
description: 'with a town or suburb: how many more doctors match with the wider region as the place (another town of the region, or only on its Healthpoint page), and the place to search to include them'
need_note:
type: string
description: 'with a need: when it is a symptom, which specialties were added (specialty_for_symptom); or that no doctor lists all its words'
gender_note:
type: string
description: 'with gender: how many doctors were left out because no gender is recorded'
gp_note:
type: string
description: 'the search is about general practice: use search_gp_practices for practices'
experienced_first_note:
type: string
listing_note:
type: string
description: some results have no clinic listing (medical_council_register_only)
SearchItem_2:
type: object
properties:
rank:
type: integer
doctor_id:
type: string
pattern: ^nz_[0-9a-z]{12}$
description: use with get_doctor
name:
type: string
kind:
type: string
description: Healthpoint's label for the person
specialties:
type: array
items:
type: string
vocational_scope:
type: string
cities:
type: array
items:
type: string
sectors:
type: array
items:
type: string
enum:
- private
- public
match_basis:
type: string
enum:
- stated_focus
- services_listed
- shared_service_listed
- specialty
- specialty_for_symptom
- profile_text
- partial
description: 'with a need: how directly the doctor''s own listing matches it (shared_service_listed = only a hospital department or large group page they are linked to lists it; specialty_for_symptom = the need is a symptom few doctors list and their specialty usually sees it)'
place_match:
type: string
enum:
- city_or_address
- city_in_region
- address_contains
- region_page_only
description: 'with a place: city or address part; a town inside the region you gave; inside an address (maybe a street name); or only on Healthpoint''s region page (often visiting from elsewhere)'
specialist_since:
type: integer
description: year first on the New Zealand specialist (vocational) register
recognition:
type: array
items:
type: string
description: New Zealand honours (e.g. 'MNZM, 2019 New Year Honours') or a University of Auckland title
listing:
type: string
enum:
- medical_council_register_only
description: medical_council_register_only = on the register but no clinic listing here
warnings:
type: array
items:
type: string
detail_has:
type: array
items:
type: string
description: what get_doctor adds for this doctor
SearchResult_3:
type: object
properties:
provider:
$ref: '#/components/schemas/Provider_2'
before_answering:
type: string
description: read this before answering the person
interpreted:
type: object
properties:
condition_mesh:
type: array
items:
type: object
properties:
mesh_ui:
type: string
name:
type: string
match:
type: string
description: standard medical terms (MeSH) the condition was read as
volume_from_procedure_groups:
type: array
items:
type: string
location:
type: object
properties:
state:
type: string
city:
type: string
near_zip3_areas:
type: array
items:
type: string
description: 'near_zip without within_miles: whole 3-digit ZIP areas'
center:
type: array
items:
type: string
description: 'within_miles: the place the distance is measured from'
within_miles:
type: number
zip_codes_in_area:
type: integer
note:
type: string
description: state/city/near_zip3_areas without within_miles; center/within_miles/zip_codes_in_area with it
specialties:
type: array
items:
type: string
description: specialties searched
specialties_note:
type: string
patient:
type: string
medicare_patient:
type: string
narrower_terms_included:
type: integer
description: how many narrower MeSH terms were searched too
broader_terms_included:
type: array
items:
type: string
description: broader MeSH terms also searched
specialty_fit_basis:
type: string
patient_mix_categories:
type: array
items:
type: string
prescribing_categories:
type: array
items:
type: string
language:
type:
- string
- object
specialty_fit:
type: array
items:
type: object
properties:
specialty_id:
type: string
share_of_doctors_with_this_focus_pct:
type: integer
left_out:
type: string
description: how the request was read; check it matches what the person asked. Other keys may appear
total_matches:
type: integer
offset:
type: integer
results:
type: array
items:
$ref: '#/components/schemas/DoctorListing'
warnings:
type: array
items:
type: string
next_step:
type: string
required:
- results
Provider_2:
type: object
properties:
name:
type: string
url:
type: string
data_version:
type: string
description: database version, e.g. public-2026-10-12.2
DoctorListing:
type: object
properties:
rank:
type: integer
doctor_id:
type: string
pattern: ^dr_[0-9a-z]{12}$
description: use with get_doctor
name:
type: string
degree:
type: string
description: e.g. MD, DO
npi:
type: string
description: 10-digit NPI
specialty:
type: string
specialty_source:
type: string
hospital_website_specialties:
type: array
items:
type: object
properties:
site:
type: string
specialties:
type: array
items:
type: string
description: departments listed on the doctor's hospital website (up to 2 sites)
listed_on_childrens_hospital_website:
type: boolean
city:
type: string
state:
type: string
distance_miles:
type: number
description: from the searched place, when searching near a place
match_basis:
type: string
enum:
- direct_evidence
- specialty_fit
- other
description: why this doctor matched a condition or procedure
procedure_volume_2024:
type: string
description: 'present when the need maps to a procedure group and this doctor has no published Medicare count for it: either CMS hid a count under 11 patients, or the doctor has no 2024 Medicare fee-for-service record. Unknown, not zero.'
warnings:
type: array
items:
type: string
description: e.g. excluded from federal programs, opted out of Medicare
detail_has:
type: array
items:
type: string
description: which kinds of evidence get_doctor will show for this doctor (not the evidence itself), e.g. listed_focus_areas, procedure_volume_for_this_need, phone, languages
required:
- rank
- doctor_id
- name
Error_2:
type: object
properties:
error:
type: string
enum:
- bad_args
- too_slow
- daily_limit
- rate_limited
- busy
- unavailable
- cross_site
- not_found
- internal
- sign_in_required
- invalid_token
description: machine-readable kind
message:
type: string
description: what happened and what to do next
required:
- error
- message
securitySchemes:
accountKey:
type: http
scheme: bearer
description: Optional account key (dk_...); accounts are by invitation during the trial.
x-refined-from:
- findadoctor-si-fr-openapi.json
- findadoctor-si-nz-openapi.json
- findadoctor-si-openapi.json