Doctors API#

Search doctors#

GET /api/v1/doctors

Query parameters#

Parameter	Type	Required	Description
`country`	string	yes	Dataset code: `de`, `es`, `fr`, `gb`, `it`, `mx`, or `pt`. Case-insensitive.
`city`	string	no	Lowercase city slug such as `berlin`, `madrid`, `roma`, or `lisboa`.
`q`	string	no	Literal text match across names, city, primary type, and specialties; maximum 100 characters.
`whatsapp`	boolean	no	`true` selects records whose primary number appears WhatsApp-reachable.
`verified`	boolean	no	Select verified or unverified Doctosan listings.
`limit`	integer	no	Records per page, from 1 to 100. Default: 25.
`cursor`	string	no	Opaque `nextCursor` from the preceding response.

curl --get 'https://www.doctosan.com/api/v1/doctors' \
  --header "X-API-Key: $DOCTOSAN_API_KEY" \
  --data-urlencode 'country=pt' \
  --data-urlencode 'city=lisboa' \
  --data-urlencode 'q=cardiologia' \
  --data-urlencode 'verified=true'

Doctor object#

Field	Type	Meaning
`id`	string	Stable Doctosan place identifier.
`name`, `legalName`	string or null	Published display and legal names.
`address`	object	`street`, `city`, `state`, `postalCode`, and two-letter `country`.
`location`	object or null	`latitude` and `longitude`.
`phone`, `phoneType`	string or null	Primary normalized number and `mobile`, `landline`, or `other`.
`additionalPhones`	array	Additional normalized phone records.
`email`	string or null	Published practice email.
`website`, `googleMapsUrl`	string or null	Validated public HTTP(S) URLs.
`primaryType`, `specialties`	string / array	Published category and subtype labels.
`rating`, `reviewCount`	number or null	Published Google rating signals.
`whatsappEligible`	boolean	Technical reachability signal; never consent.
`verified`	boolean	Whether Doctosan has verified the listing.
`workingHours`	object or null	Published source day labels mapped to time ranges.
`profileUrl`	string	Canonical public Doctosan profile.

Fields with no published value remain null or an empty array; clients should not invent data from neighboring fields.

Get one doctor#

GET /api/v1/doctors/{doctorId}

URL-encode the id received from a search response:

const url = `https://www.doctosan.com/api/v1/doctors/${encodeURIComponent(doctor.id)}`
const response = await fetch(url, {
  headers: { 'X-API-Key': process.env.DOCTOSAN_API_KEY },
})
const { doctor } = await response.json()

The endpoint returns 404 when the id is unknown, suppressed, closed, or no longer published.

You may also pass the complete canonical https://www.doctosan.com profile URL through encodeURIComponent as doctorId. Translated profile URLs resolve to the same record by country, city and profile slug. Other hosts, credentials, query strings, fragments and non-profile paths are rejected without fetching the supplied URL. The path value is limited to 2,048 characters.