List Providers¶

Lists providers, optionally filtered by clinic, speciality or status.

Endpoint¶

GET /v2/providers

Query Parameters¶

Parameter	Type	Required	Description
`page`	integer	Yes	1-based page number. Defaults to `1`.
`page_size`	integer	Yes	Results per page. Defaults to `25`.
`clinic_id`	string	No	The clinic this record belongs to.
`speciality`	string	No	The record's primary speciality.
`status`	string	No	`ONBOARDING` until the record is published, then `ACTIVE`; `INACTIVE` once deleted.

Request¶

curl --location '{base_url}/v2/providers?page=1&page_size=25' \
  --header 'Authorization: Bearer JWT_TOKEN'

Response¶

Success Response¶

Code: 200 OK

{
  "items": [
    {
      "id": "2094",
      "onboarding_provider_id": "d27a6b10-9f34-4e82-b5c1-7a03e8946fd2",
      "user_id": "2094",
      "first_name": "Morgan",
      "middle_name": null,
      "last_name": "Delgado",
      "email": "m.delgado@example.com",
      "mobile": "+1-555-0155",
      "npi": "1740398215",
      "license": "PT-30914",
      "speciality": "PHYSICAL_THERAPY",
      "sub_specialities": [],
      "qualifications": [
        "DPT"
      ],
      "external_reference_id": "provider-4471",
      "patient_scoped": false,
      "photo_url": null,
      "signature_url": null,
      "status": "ACTIVE",
      "online_booking_enabled": true,
      "clinics": [
        {
          "clinic_id": "5831",
          "onboarding_clinic_id": "b41f7c92-5e08-4a13-8d6f-2c9147ab3e5d",
          "status": "ACTIVE",
          "online_booking_enabled": true,
          "hours": [
            {
              "days_of_week": [
                "MONDAY",
                "TUESDAY"
              ],
              "start_time": "08:00",
              "end_time": "17:00"
            }
          ]
        }
      ],
      "home_health": {
        "enabled": true,
        "state_code": "OR",
        "address": {
          "line1": "482 Willow Creek Rd",
          "line2": null,
          "city": "Fairview",
          "state": "OR",
          "postal_code": "97024",
          "country": "US"
        },
        "location": {
          "lat": 45.5231,
          "lng": -122.6765
        },
        "transport_mode": "CAR",
        "max_drive_seconds": 2700,
        "max_visits_per_week": 12,
        "max_allowed_visits_per_slot": 2,
        "target_hours_weekly": 30,
        "online_booking": true,
        "pet_comfort": true,
        "stair_comfort": true,
        "accepting_new_patients": true,
        "schedules": [
          {
            "effective_start_date": "2026-09-01",
            "effective_end_date": null,
            "entries": [
              {
                "days_of_week": [
                  "MONDAY",
                  "TUESDAY"
                ],
                "start_time": "08:00",
                "end_time": "17:00",
                "address": {
                  "line1": "482 Willow Creek Rd",
                  "line2": null,
                  "city": "Fairview",
                  "state": "OR",
                  "postal_code": "97024",
                  "country": "US"
                },
                "location": {
                  "lat": 45.5231,
                  "lng": -122.6765
                }
              }
            ]
          }
        ],
        "scheduling_overrides": {
          "2026-09-17": {
            "ranges": []
          },
          "2026-09-20": {
            "ranges": [
              {
                "start_time": "10:00",
                "end_time": "12:00"
              }
            ]
          }
        }
      },
      "created_at": "2026-08-27T14:30:00Z",
      "updated_at": "2026-08-27T14:30:00Z"
    }
  ],
  "page": 1,
  "page_size": 25,
  "total": 1,
  "total_pages": 1
}

Response Fields¶

Field	Type	Description
`items`	array of object	The page of results. See Items.
`page`	integer	1-based page number.
`page_size`	integer	Results per page.
`total`	integer	Total results matching the query.
`total_pages`	integer	Total pages available.

Items¶

Field	Type	Description
`id`	string or null	The provider id. `null` while `status` is `ONBOARDING`..
`onboarding_provider_id`	string or null	The provider's onboarding-record UUID.
`user_id`	string or null	The provider's user id. Same value as the provider `id`; both are returned rather than leaving that implicit.
`first_name`	string or null
`middle_name`	string or null
`last_name`	string or null
`email`	string or null
`mobile`	string or null
`npi`	string or null
`license`	string or null
`speciality`	string or null	The record's primary speciality.
`sub_specialities`	array of string
`qualifications`	array of string
`external_reference_id`	string or null	Your own identifier for this provider. Stored only — it has no effect on Spry behaviour.
`patient_scoped`	boolean	When true, restricts the provider to only their own assigned patients (HIPAA minimum-necessary). When false (default), the provider can access all patients in the organisation.
`photo_url`	string or null	A fetchable URL. It may be a time-limited signed URL, so fetch it rather than storing it. Read-only — set it with Upload Provider Photo.
`signature_url`	string or null	A fetchable URL. Treat it as time-limited and fetch it rather than storing it. In environments where signing is unavailable the raw stored value is returned, which isn't fetchable.
`status`	string or null	`ONBOARDING` until the record is published, then `ACTIVE`; `INACTIVE` once deleted.
`online_booking_enabled`	boolean or null	Whether this record is bookable through online booking.
`clinics`	array of object	See Clinics.
`home_health`	object or null	Home-visit settings for this provider. `null` when the provider has no home-visit configuration. See Home Health.
`created_at`	string (date-time) or null
`updated_at`	string (date-time) or null

Clinics¶

Field	Type	Description
`clinic_id`	string or null	The clinic this record belongs to.
`onboarding_clinic_id`	string or null	The clinic's onboarding-record UUID. Always present for clinics created through onboarding, and the only way to address one before it's published.
`status`	string or null	`ONBOARDING` until the record is published, then `ACTIVE`; `INACTIVE` once deleted.
`online_booking_enabled`	boolean or null	Whether this record is bookable through online booking.
`hours`	array of object	Working hours, as one entry per distinct daily pattern. See Hours.

Hours¶

Field	Type	Description
`days_of_week`	array of string	Any of `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`, `SUNDAY`.
`start_time`	string	Clock time, 24-hour `HH:MM`.
`end_time`	string	Clock time, 24-hour `HH:MM`.

Home Health¶

Field	Type	Description
`enabled`	boolean	Whether home visits are enabled for this provider.
`state_code`	string or null	Two-letter state the provider is licensed to visit in.
`address`	object or null	See Address.
`location`	object or null	Geographic point the visit window is anchored to. See Location.
`transport_mode`	string or null	How the provider travels between visits. One of `CAR`, `BIKE`, `WALK`, `TRANSIT`.
`max_drive_seconds`	integer or null	Longest drive the provider will accept between consecutive visits, in seconds.
`max_visits_per_week`	integer or null	Cap on home visits per week.
`max_allowed_visits_per_slot`	integer or null	Cap on home visits per schedule slot.
`target_hours_weekly`	integer or null	Target hours of home visits per week. Defaults to `30`.
`online_booking`	boolean or null	Engagement-level booking, distinct from the provider's own `online_booking_enabled` and each clinic's. Defaults to `true`.
`pet_comfort`	boolean	Whether the provider will visit homes with pets.
`stair_comfort`	boolean	Whether the provider will visit homes requiring stairs.
`accepting_new_patients`	boolean or null	Whether this provider is accepting new home-health patients. Defaults to `true`.
`schedules`	array of object	Independent home-visit availability periods, each with its own weekly `entries[]`. Periods must not overlap, and at most one may be open-ended. See Schedules.
`scheduling_overrides`	object	Per-date exceptions to the weekly schedule, keyed `YYYY-MM-DD`. A key's presence is what marks a day off from no override — empty `ranges` (absent entirely on read) means no visits that day, and a populated `ranges[]`, each a `{start_time, end_time}` window with an optional `address`/`location` to anchor it away from the provider's home base, replaces the weekly pattern for that date. Every date must fall inside one of `schedules[]`'s periods, and past dates are rejected. On write, an explicit `null` clears a key and restores the weekly pattern; an omitted key is left alone.

Address¶

Field	Type	Description
`line1`	string or null
`line2`	string or null
`city`	string or null
`state`	string or null
`postal_code`	string or null
`country`	string or null

Location¶

Field	Type	Description
`lat`	number	Latitude, decimal degrees.
`lng`	number	Longitude, decimal degrees.

Schedules¶

Field	Type	Description
`effective_start_date`	string (date)	When this period takes effect. `YYYY-MM-DD`.
`effective_end_date`	string (date) or null	When this period stops applying. `null` for open-ended — periods must not overlap, and at most one may be open-ended. `YYYY-MM-DD`.
`entries`	array of object	Weekly home-visit windows for this period. Reuses the same `days_of_week`/`start_time`/`end_time` shape as clinic and provider-clinic hours, extended with an optional `address` and `location` to anchor a window somewhere other than the provider's home base. Note the raw onboarding bridge spells these its own way (`Monday`, `zip`); this contract normalises them to `MONDAY` and `postal_code` — the same normalisation applies to `scheduling_overrides` ranges. See Entries.

Entries¶

Field	Type	Description
`days_of_week`	array of string	Any of `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`, `SUNDAY`.
`start_time`	string	Clock time, 24-hour `HH:MM`.
`end_time`	string	Clock time, 24-hour `HH:MM`.
`address`	object	See Address.
`location`	object	Geographic point the visit window is anchored to. See Location.

Error Response¶

Code: 400 Bad Request

{
  "code": "bad_request",
  "message": "Validation failed",
  "errors": [
    {
      "field": "patient_id",
      "message": "must be a string"
    }
  ]
}

Every error has the same shape — a machine-readable code, a message, and an errors[] array that's empty when there's nothing field-specific to report. The HTTP status is authoritative.

Status	`code`	Meaning
`400 Bad Request`	`bad_request`	The request body or parameters failed validation. `errors[]` names the offending fields.
`401 Unauthorized`	`unauthorized`	The access token is missing, malformed or expired.
`403 Forbidden`	`forbidden`	The request references a resource outside the token's organisation or clinic scope.
`404 Not Found`	`not_found`	No such resource, or it's outside your scope.
`429 Too Many Requests`	`rate_limited`	Rate limit exceeded. Back off and retry.
`500 Internal Server Error`	`internal_error`	Unexpected server error.
`502 Bad Gateway`	`upstream_error`	Upstream service failed or timed out.

Notes¶

A scheduling_overrides day off is a listed date with empty ranges (absent entirely on read) — distinct from a day of the week with no matching schedules[].entries[] window, which is simply outside the weekly pattern.