# Find doctors and specialists in the Greater Toronto Area — v1 API reference

---

# List doctors

`GET https://www.finddoc.ca/api/v1/doctors`

Return doctors filtered by specialty, languages, gender, and years of practice. Each item embeds the doctor's primary `clinic` and a `dataFreshness` marker.

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| specialties | string | No | Comma-separated specialties to match, e.g. `Cardiology,Pediatrics`. A doctor matches if they hold any of them. |
| specialty | string | No | Single specialty to match, e.g. `Family Medicine`. Singular and exact. Kept for compatibility — `specialties` wins when both are sent. |
| accepting | boolean | No | When true, only return rows currently accepting new patients. |
| gender | string | No | One of "male", "female", or "non-binary". |
| languages | string | No | Comma-separated list of languages spoken, e.g. `English,French`. |
| minYears | integer | No | Minimum years of practice for the doctor. |
| maxYears | integer | No | Maximum years of practice for the doctor. |
| evening | boolean | No | Only include clinics with evening hours (after 5 PM). |
| weekend | boolean | No | Only include clinics open on Saturday or Sunday. |
| wheelchair | boolean | No | Only include wheelchair-accessible clinics. |
| virtualVisits | boolean | No | Only include clinics offering virtual visits. |
| nearTTC | boolean | No | Only include clinics near a TTC subway station. |
| limit | integer | No | Page size. Defaults to 25, maximum 100. |
| offset | integer | No | Zero-based offset for pagination. Defaults to 0. |

## Example request

```bash
curl https://www.finddoc.ca/api/v1/doctors \
  -G \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "specialty=Family Medicine" \
  -d accepting=true \
  -d languages=French \
  -d limit=10
```

## Example response (200 OK)

```json
{
  "doctors": [
    {
      "id": "doctor_5h7m2k",
      "cpsoNumber": "90123",
      "name": "Dr. Amelie Tremblay",
      "gender": "female",
      "yearsOfPractice": 12,
      "specialties": ["Family Medicine"],
      "languages": ["English", "French"],
      "clinic": {
        "id": 92a39274-7f56-4d18-a93d-ba498508249e,
        "name": "Riverdale Family Health",
        "address": "123 Queen St E, Toronto, ON",
        "lat": 43.659,
        "lng": -79.358,
        "phone": "+1 416-555-0142",
        "acceptingNewPatients": true
      },
      "dataFreshness": "fresh",
      "syncedAt": "2026-05-01T09:30:00Z"
    }
  ],
  "total": 318,
  "count": 1
}
```

---

# Search doctors

`GET https://www.finddoc.ca/api/v1/doctors/search`

Free-text search across doctor names and CPSO numbers. Returns the same `{ doctors, total, count }` envelope as `/doctors`, and every list filter composes with the `q` query.

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| q | string | Yes | Search query, at least 2 characters. Matched against the doctor's name (case-insensitive) or an exact CPSO number. Returns `400 missing_param` if omitted or shorter than 2 characters. All `/doctors` filters below compose with `q` (AND). |
| specialties | string | No | Comma-separated specialties to match, e.g. `Cardiology,Pediatrics`. A doctor matches if they hold any of them. |
| specialty | string | No | Single specialty to match, e.g. `Family Medicine`. Singular and exact. Kept for compatibility — `specialties` wins when both are sent. |
| accepting | boolean | No | When true, only return rows currently accepting new patients. |
| gender | string | No | One of "male", "female", or "non-binary". |
| languages | string | No | Comma-separated list of languages spoken, e.g. `English,French`. |
| minYears | integer | No | Minimum years of practice for the doctor. |
| maxYears | integer | No | Maximum years of practice for the doctor. |
| evening | boolean | No | Only include clinics with evening hours (after 5 PM). |
| weekend | boolean | No | Only include clinics open on Saturday or Sunday. |
| wheelchair | boolean | No | Only include wheelchair-accessible clinics. |
| virtualVisits | boolean | No | Only include clinics offering virtual visits. |
| nearTTC | boolean | No | Only include clinics near a TTC subway station. |
| limit | integer | No | Page size. Defaults to 25, maximum 100. |
| offset | integer | No | Zero-based offset for pagination. Defaults to 0. |

## Example request

```bash
curl https://www.finddoc.ca/api/v1/doctors/search \
  -G \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d q=Tremblay \
  -d accepting=true
```

## Example response (200 OK)

```json
{
  "doctors": [
    {
      "id": "doctor_5h7m2k",
      "cpsoNumber": "90123",
      "name": "Dr. Amelie Tremblay",
      "gender": "female",
      "yearsOfPractice": 12,
      "specialties": ["Family Medicine"],
      "languages": ["English", "French"],
      "clinic": {
        "id": 92a39274-7f56-4d18-a93d-ba498508249e,
        "name": "Riverdale Family Health",
        "address": "123 Queen St E, Toronto, ON",
        "lat": 43.659,
        "lng": -79.358,
        "phone": "+1 416-555-0142",
        "acceptingNewPatients": true
      },
      "dataFreshness": "fresh",
      "syncedAt": "2026-05-01T09:30:00Z"
    }
  ],
  "total": 3,
  "count": 1
}
```

---

# Get a doctor

`GET https://www.finddoc.ca/api/v1/doctors/85112`

Fetch a single doctor by CPSO number — the path segment `{cpso}` (e.g. `82621`). The detail record adds `bookingMethod`, `rating`, and the most recent `reviews` on top of the list shape. Unknown CPSO numbers return `404 not_found`.

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| cpso | string | Yes | CPSO number from the path segment. |

## Example request

```bash
curl https://www.finddoc.ca/api/v1/doctors/90123 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Example response (200 OK)

```json
{
  "doctor": {
    "id": "doctor_5h7m2k",
    "cpsoNumber": "90123",
    "name": "Dr. Amelie Tremblay",
    "gender": "female",
    "yearsOfPractice": 12,
    "languages": ["English", "French"],
    "specialties": ["Family Medicine"],
    "referralRequired": false,
    "bookingMethod": {
      "phone": "+1 416-555-0142",
      "online": "https://book.example.ca/tremblay",
      "referralOnly": false
    },
    "rating": {
      "positive": 48,
      "negative": 6,
      "reviewCount": 54
    },
    "reviews": [
      {
        "author": "Jordan P.",
        "rating": 5,
        "text": "Thorough and never rushed.",
        "date": "2026-04-18"
      }
    ],
    "clinic": {
      "id": 92a39274-7f56-4d18-a93d-ba498508249e,
      "name": "Riverdale Family Health",
      "address": "123 Queen St E, Toronto, ON",
      "lat": 43.659,
      "lng": -79.358,
      "phone": "+1 416-555-0142",
      "acceptingNewPatients": true
    },
    "syncedAt": "2026-05-01T09:30:00Z",
    "expiredAt": null,
    "dataFreshness": "fresh"
  }
}
```

---

# List doctor reviews

`GET https://www.finddoc.ca/api/v1/doctors/{cpso}/reviews`

Paginated reviews for a doctor, addressed by CPSO number in the path (e.g. `85112`), newest first. Unknown CPSO numbers return `404 not_found`.

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| cpso | string | Yes | CPSO number from the path segment. |
| limit | integer | No | Page size. Defaults to 25, maximum 100. |
| offset | integer | No | Zero-based offset for pagination. Defaults to 0. |

## Example request

```bash
curl https://www.finddoc.ca/api/v1/doctors/85112/reviews \
  -G \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d limit=10
```

## Example response (200 OK)

```json
{
  "doctorCpso": "90123",
  "reviews": [
    {
      "author": "Jordan P.",
      "rating": 5,
      "text": "Thorough and never rushed.",
      "date": "2026-04-18",
      "sourceUrl": "https://www.ratemds.com/doctor/dr-amelie-tremblay"
    }
  ],
  "total": 18,
  "count": 1
}
```

---

# Doctor summary

`GET https://www.finddoc.ca/api/v1/doctors/summary`

Directory-wide totals: the doctor count, how many are accepting new patients, a per-specialty breakdown, and a `dataFreshness` coverage rollup. Takes no query parameters.

## Example request

```bash
curl https://www.finddoc.ca/api/v1/doctors/summary \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Example response (200 OK)

```json
{
  "totalDoctors": 4821,
  "acceptingNewPatients": 1163,
  "bySpecialty": [
    {
      "specialty": "Family Medicine",
      "count": 2104
    }
  ],
  "dataFreshness": {
    "fresh": 4200,
    "stale": 540,
    "unknown": 81,
    "coveragePct": 98.3
  }
}
```

---

# List clinics

`GET https://www.finddoc.ca/api/v1/clinics`

Return clinics filtered by acceptance, languages, accessibility, and location. Results are sorted by distance when `lat` and `lng` are supplied, otherwise by name.

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| specialties | string | No | Comma-separated specialties to match, e.g. `Family Medicine,Pediatrics`. |
| accepting | boolean | No | When true, only return rows currently accepting new patients. |
| gender | string | No | One of "male", "female", or "non-binary". |
| languages | string | No | Comma-separated list of languages spoken, e.g. `English,French`. |
| minYears | integer | No | Minimum years of practice for the doctor. |
| maxYears | integer | No | Maximum years of practice for the doctor. |
| evening | boolean | No | Only include clinics with evening hours (after 5 PM). |
| weekend | boolean | No | Only include clinics open on Saturday or Sunday. |
| wheelchair | boolean | No | Only include wheelchair-accessible clinics. |
| virtualVisits | boolean | No | Only include clinics offering virtual visits. |
| nearTTC | boolean | No | Only include clinics near a TTC subway station. |
| lat | number | No | Latitude for distance sort. Must be paired with `lng`. |
| lng | number | No | Longitude for distance sort. Must be paired with `lat`. |
| limit | integer | No | Page size. Defaults to 25, maximum 100. |
| offset | integer | No | Zero-based offset for pagination. Defaults to 0. |

## Example request

```bash
curl https://www.finddoc.ca/api/v1/clinics \
  -G \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d accepting=true \
  -d languages=French \
  -d limit=10
```

## Example response (200 OK)

```json
{
  "clinics": [
    {
      "id": 92a39274-7f56-4d18-a93d-ba498508249e,
      "name": "Riverdale Family Health",
      "address": "123 Queen St E, Toronto, ON",
      "accepting": true,
      "languages": ["English", "French"],
      "specialties": ["Family Medicine"],
      "lat": 43.659,
      "lng": -79.358
    }
  ],
  "total": 42,
  "count": 1
}
```

---

# Get a clinic

`GET https://www.finddoc.ca/api/v1/clinics/{id}`

Fetch a single clinic by its internal id — the path segment `{id}` (e.g. `92a39274-7f56-4d18-a93d-ba498508249e`). The detail record includes hours, accessibility, and the clinic's doctors. Unknown ids return `404 not_found`.

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | Clinic id from the path segment. |

## Example request

```bash
curl https://www.finddoc.ca/api/v1/clinics/92a39274-7f56-4d18-a93d-ba498508249e \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Example response (200 OK)

```json
{
  "clinic": {
    "id": 92a39274-7f56-4d18-a93d-ba498508249e,
    "name": "Riverdale Family Health",
    "address": "123 Queen St E, Toronto, ON",
    "lat": 43.659,
    "lng": -79.358,
    "phone": "+1 416-555-0142",
    "acceptingNewPatients": true,
    "website": "https://riverdalehealth.example.ca",
    "type": "family-practice",
    "hours": {
      "weekday": "9:00-17:00",
      "evening": false,
      "weekend": false
    },
    "accessibility": {
      "wheelchair": true,
      "virtualVisits": true,
      "nearTTC": true
    },
    "doctors": [
      {
        "name": "Dr. Amelie Tremblay",
        "gender": "female",
        "yearsOfPractice": 12,
        "languages": ["English", "French"],
        "specialties": ["Family Medicine"]
      }
    ]
  }
}
```

---

# List clinic reviews

`GET https://www.finddoc.ca/api/v1/clinics/{id}/reviews`

Paginated reviews for a clinic, addressed by id in the path, with an `aggregate` block: the average rating, total count, and a per-dimension breakdown. A clinic with no reviews returns `avgRating: null` and zero counts. Unknown ids return `404 not_found`.

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | Clinic id from the path segment. |
| limit | integer | No | Page size. Defaults to 25, maximum 100. |
| offset | integer | No | Zero-based offset for pagination. Defaults to 0. |

## Example request

```bash
curl https://www.finddoc.ca/api/v1/clinics/92a39274-7f56-4d18-a93d-ba498508249e/reviews \
  -G \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d limit=10
```

## Example response (200 OK)

```json
{
  "clinicId": "92a39274-7f56-4d18-a93d-ba498508249e",
  "aggregate": {
    "avgRating": 4.3,
    "count": 27,
    "byDimension": [
      {
        "dimension": "wait_time",
        "avgRating": 3.9,
        "count": 21
      },
      {
        "dimension": "staff",
        "avgRating": 4.6,
        "count": 24
      }
    ]
  },
  "reviews": [
    {
      "author": "Priya S.",
      "rating": 5,
      "text": "Front desk was friendly and the wait was short.",
      "date": "2026-03-22"
    }
  ],
  "total": 27,
  "count": 1
}
```

---

# List specialists

`GET https://www.finddoc.ca/api/v1/specialists`

Return specialists for a given `specialty`. Filters mirror `/clinics`; the response uses the same shape so the same client can render both.

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| specialty | string | Yes | Single specialty to match, e.g. `Family Medicine`. Returns `400 missing_param` if omitted. |
| accepting | boolean | No | When true, only return rows currently accepting new patients. |
| gender | string | No | One of "male", "female", or "non-binary". |
| languages | string | No | Comma-separated list of languages spoken, e.g. `English,French`. |
| minYears | integer | No | Minimum years of practice for the doctor. |
| maxYears | integer | No | Maximum years of practice for the doctor. |
| evening | boolean | No | Only include clinics with evening hours (after 5 PM). |
| weekend | boolean | No | Only include clinics open on Saturday or Sunday. |
| wheelchair | boolean | No | Only include wheelchair-accessible clinics. |
| virtualVisits | boolean | No | Only include clinics offering virtual visits. |
| nearTTC | boolean | No | Only include clinics near a TTC subway station. |
| lat | number | No | Latitude for distance sort. Must be paired with `lng`. |
| lng | number | No | Longitude for distance sort. Must be paired with `lat`. |
| limit | integer | No | Page size. Defaults to 25, maximum 100. |
| offset | integer | No | Zero-based offset for pagination. Defaults to 0. |

## Example request

```bash
curl https://www.finddoc.ca/api/v1/specialists \
  -G \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "specialty=Family Medicine" \
  -d languages=French
```

## Example response (200 OK)

```json
{
  "clinics": [
    {
      "id": "specialist_3qm71v",
      "name": "Dr. Amelie Tremblay",
      "specialty": "Family Medicine",
      "languages": ["English", "French"],
      "accepting": true,
      "wait_weeks": 6
    }
  ],
  "total": 12,
  "count": 1
}
```

---

# List specialties

`GET https://www.finddoc.ca/api/v1/metadata/specialties`

Every specialty in the directory with its doctor count, sorted by count descending then name. Useful for building filter menus. Takes no query parameters.

## Example request

```bash
curl https://www.finddoc.ca/api/v1/metadata/specialties \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Example response (200 OK)

```json
{
  "specialties": [
    {
      "name": "Family Medicine",
      "doctorCount": 2104
    },
    {
      "name": "Pediatrics",
      "doctorCount": 389
    }
  ],
  "count": 2
}
```

---

# List languages

`GET https://www.finddoc.ca/api/v1/metadata/languages`

Every language spoken across the directory with its doctor count, sorted by count descending then name. Takes no query parameters.

## Example request

```bash
curl https://www.finddoc.ca/api/v1/metadata/languages \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Example response (200 OK)

```json
{
  "languages": [
    {
      "name": "English",
      "doctorCount": 4655
    },
    {
      "name": "French",
      "doctorCount": 612
    }
  ],
  "count": 2
}
```

---

## Get full access

Direct v1 API access is unlocked by a one-time payment — One Time Payment (Early Access) (5 CAD). Complete checkout at https://www.finddoc.ca/developers/checkout.