> ## Documentation Index > Fetch the complete documentation index at: https://docs.haau3.com/llms.txt > Use this file to discover all available pages before exploring further. # Search provider locations > Returns the matching slots grouped by provider location: each item in `providerLocations` is one provider at one location, or a location with no provider, with its total slot count and soonest availability, paginated by provider location. Its opaque `key` drills down to its individual slots via `GET /v1/scheduling/slots?providerLocationKey=`. Same filters as `/slots`. Requires a valid API key. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/scheduling/provider-locations openapi: 3.1.0 info: title: haau3 Platform API version: 1.0.0-preview.4 description: >- The haau3 platform API is in preview: it may change as we build, usually to add features or improve performance. Endpoints require an API key, sent as `Authorization: Bearer `. Requests without a valid key return 401. Create a key in the dashboard at https://platform.haau3.com; a new organization starts on the free Developer plan. From 2026-11-01 a request past one of its plan's limits (requests a minute on every plan, requests a month on Developer) returns 429 with `Retry-After`. Every error under `/v1/fhir` is a FHIR `OperationOutcome` and every other error an RFC 9457 problem; https://docs.haau3.com/errors lists every status, whether to retry it, and what a method a path does not take answers. servers: - url: https://api.haau3.com description: Production security: - bearerAuth: [] tags: - name: Scheduling description: 'Provider availability (SMART Scheduling Links): slots and publishers.' - name: FHIR base description: >- What the FHIR R4 base at `/v1/fhir/r4` answers for every service on it: the `CapabilityStatement` that lists them all, and batch Bundles that carry several requests to any of them in one round trip. - name: Terminology description: >- FHIR terminology operations over the code systems listed in TerminologyCapabilities. Some are resolved from their own source when you ask; others are held here at a named release, which that resource also names. - name: Provider directory description: >- CMS's National Provider Directory as FHIR R4: practitioners and their roles, organizations, payers and insurance networks, network membership, healthcare services, locations and endpoints. Every parameter the service serves is declared here, and any other is refused by name rather than ignored. - name: Questionnaires description: >- FHIR Questionnaire, served as its source publishes it. This service holds copies of a curated set and reaches any other questionnaire its source publishes by canonical URL, as well as forms published at their own address under places this service is set up to reach. Read one by id, and build the QuestionnaireResponse in your own application. - name: Plan Benefits description: >- FHIR InsurancePlan: what a Medicare Advantage or ACA Marketplace plan covers and what a member pays, read from the files CMS publishes. Every plan names the CMS release it was read from. Read a plan by its id, or search by identifier, name, state or county, and check whether the CMS National Provider Directory lists providers in a plan's network. - name: MedList description: >- One reconciled medication list from one patient's FHIR medication records, as US Core MedicationRequests with a Provenance for each. This operation receives patient data, so send it only under an executed agreement. paths: /v1/scheduling/provider-locations: get: tags: - Scheduling summary: Search provider locations description: >- Returns the matching slots grouped by provider location: each item in `providerLocations` is one provider at one location, or a location with no provider, with its total slot count and soonest availability, paginated by provider location. Its opaque `key` drills down to its individual slots via `GET /v1/scheduling/slots?providerLocationKey=`. Same filters as `/slots`. Requires a valid API key. operationId: searchProviderLocations parameters: - name: status in: query required: false description: Slot availability state to return. Defaults to `free`. schema: default: free type: string enum: - free - busy - busy-unavailable - busy-tentative - name: publisher in: query required: false description: >- Filter to a single publisher (source) by slug, such as `zocdoc` or `defacto`. See `GET /v1/scheduling/publishers` for the available slugs. schema: type: string minLength: 1 example: haau3 - name: serviceTypeCode in: query required: false description: >- Filter by service type code (as published by the source). A slot matches when any of its `serviceTypes` carries the code. A comma-separated list (up to 100) matches a slot carrying any of them. schema: type: string minLength: 1 - name: npi in: query required: false description: >- Filter by the provider's National Provider Identifier: a clinician's, or an organization's when a healthcare service is the provider. Ten digits; a comma-separated list (up to 100) matches a slot whose provider carries any of them. Matched as the publisher sent it, in either NPI identifier system, across every publisher. schema: type: string minLength: 1 - name: specialty in: query required: false description: >- Filter by specialty: a slot matches when its provider's `specialties` or its schedule's `specialties` carry the code. Send `code` to match it in any code system, or `system|code` to match it in that system only. Codes are each publisher's own and are not translated between code systems, so one code finds the publishers that use it; `GET /v1/scheduling/specialties` lists them. A specialty sent as text only cannot be matched. A comma-separated list (up to 100) matches any of them. schema: type: string minLength: 1 - name: appointmentType in: query required: false description: Filter by appointment type. schema: type: string minLength: 1 - name: acceptingPatients in: query required: false description: >- Filter to slots accepting patients of this kind (HL7 `accepting-patients` CodeSystem: `newpt` | `existptonly` | `existptfam`). Slots marked `nopt` (not accepting patients) are never served, so `nopt` is not a valid filter value. Lenient: a slot that does not declare an accepting-patients code matches any value (absence never hides a slot); a slot that declares one must equal the requested value. schema: type: string enum: - newpt - existptonly - existptfam - name: isVirtual in: query required: false description: Filter to virtual (`true`) or in-person (`false`) slots. schema: type: boolean - name: city in: query required: false description: Filter by the location's city. schema: type: string minLength: 1 - name: state in: query required: false description: Filter by the location's state. schema: type: string minLength: 1 - name: startAfter in: query required: false description: >- Only slots starting at or after this instant: ISO 8601 with seconds and an offset, such as `2026-07-06T13:00:00-04:00` or `2026-07-06T17:00:00Z`. A value without seconds is refused. When absent, slots start from now unless `includePast=true`. schema: type: string format: date-time - name: startBefore in: query required: false description: >- Only slots starting at or before this instant: ISO 8601 with seconds and an offset, such as `2026-07-06T13:00:00-04:00` or `2026-07-06T17:00:00Z`. A value without seconds is refused. schema: type: string format: date-time - name: includePast in: query required: false description: >- Include slots that started before now. Defaults to `false`: with no `startAfter`, results start from now. An explicit `startAfter` applies as given either way. schema: default: false type: boolean - name: limit in: query required: false description: >- Page size: the number of provider locations, from 1 to 100. Defaults to 25. schema: default: 25 type: integer minimum: 1 maximum: 100 example: 1 - name: offset in: query required: false description: Number of provider locations to skip for pagination. Defaults to 0. schema: default: 0 type: integer minimum: 0 maximum: 9007199254740991 - $ref: '#/components/parameters/XRequestId' responses: '200': description: >- The matching provider locations, and their total number before paging. content: application/json: schema: $ref: '#/components/schemas/SearchProviderLocationsResponse' examples: Provider locations with slots from one publisher: summary: Provider locations with slots from one publisher value: total: 5 providerLocations: - key: >- haau3|loc:idr|https://haau3.com/synthetic/location|loc-haau3-telehealth|prov:idr|https://haau3.com/synthetic/practitioner|prac-haau3-psych publisher: haau3 provider: id: prac-haau3-psych identifier: - value: prac-haau3-psych system: https://haau3.com/synthetic/practitioner type: practitioner-role name: Dr. Sarah Whitefeather specialty: Psychiatry Physician specialties: - system: http://nucc.org/provider-taxonomy code: 2084P0800X display: Psychiatry Physician location: id: loc-haau3-telehealth identifier: - value: loc-haau3-telehealth system: https://haau3.com/synthetic/location name: haau3 Telehealth phone: - +1-617-555-0199 website: - https://haau3.com/telehealth physicalType: system: >- http://terminology.hl7.org/CodeSystem/location-physical-type code: vi serviceTypes: - system: http://terminology.hl7.org/CodeSystem/service-type code: '124' display: General Practice specialties: [] bookingMethod: online isVirtual: true acceptingPatients: newpt nextAvailableStart: '2026-10-18T21:00:00.000Z' totalSlots: 155 headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' '400': description: >- A query parameter is not valid, is not one this endpoint takes, or was sent more than once. The problem's `issues` names each one and says why. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' '401': $ref: '#/components/responses/ProblemUnauthorized' '406': $ref: '#/components/responses/ProblemNotAcceptable' '429': $ref: '#/components/responses/ProblemTooManyRequests' '500': $ref: '#/components/responses/ProblemServerError' '503': description: >- The scheduling service is unavailable, or its database did not answer in time. Send the request again after `Retry-After`. It is also the answer when the API key could not be checked just now, with `Retry-After`. headers: Retry-After: description: How many seconds to wait before sending the request again. schema: type: integer minimum: 0 X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' x-codeSamples: - lang: bash label: cURL source: > curl "https://api.haau3.com/v1/scheduling/provider-locations?publisher=haau3&limit=1" \ -H "Authorization: Bearer $HAAU3_API_KEY" - lang: typescript label: TypeScript source: > import { Haau3 } from "@haau3/sdk"; const haau3 = new Haau3(); // reads HAAU3_API_KEY const found = await haau3.searchProviderLocations({ publisher: "haau3", limit: 1 }); console.log(found.total); - lang: python label: Python source: | from haau3 import Haau3 client = Haau3() # reads HAAU3_API_KEY found = client.search_provider_locations(publisher="haau3", limit=1) print(found["total"]) - lang: go label: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\n\t\"github.com/haau3/haau3-go\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := haau3.NewClient() // reads HAAU3_API_KEY\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tfound, err := client.SearchProviderLocations(ctx, haau3.SearchProviderLocationsParams{Publisher: new(\"haau3\"), Limit: new(1)})\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tfmt.Println(found.Total)\n}\n" components: parameters: XRequestId: name: X-Request-Id in: header required: false schema: type: string format: uuid description: >- An id of your own for this request, as a UUID. It comes back in the `X-Correlation-Id` header and is kept with haau3's record of the request. Any value that is not a UUID is ignored. See https://docs.haau3.com/errors#request-ids. schemas: SearchProviderLocationsResponse: type: object properties: providerLocations: type: array items: $ref: '#/components/schemas/SchedulingProviderLocation' total: type: integer minimum: 0 maximum: 9007199254740991 required: - providerLocations - total additionalProperties: false Problem: type: object properties: type: type: string format: uri description: >- What kind of problem this is: an anchor on https://docs.haau3.com/errors. examples: - https://docs.haau3.com/errors#invalid-request title: type: string description: A short summary, the same for every occurrence of the type. status: type: integer description: The HTTP status code of this response. detail: type: string description: What went wrong this time, and how to correct it. instance: type: string format: uri description: >- This request's id as `urn:uuid:`, the same id as the `X-Request-Id` header. examples: - urn:uuid:0b6f2d4e-8c1a-4e3b-9f5d-2a7c6e1b4d90 issues: type: array description: 'On a 400: one entry per parameter that is not valid.' items: $ref: '#/components/schemas/ProblemIssue' required: - type - title - status - detail - instance SchedulingProviderLocation: type: object properties: key: type: string publisher: type: string provider: type: object properties: id: type: string identifier: maxItems: 100 type: array items: type: object properties: system: type: string value: type: string required: - value additionalProperties: false type: type: string enum: - practitioner - practitioner-role - healthcare-service name: type: string specialty: type: string specialties: maxItems: 100 type: array items: type: object properties: system: type: string code: type: string display: type: string additionalProperties: false npi: type: string additionalProperties: false location: type: object properties: id: type: string identifier: maxItems: 100 type: array items: type: object properties: system: type: string value: type: string required: - value additionalProperties: false name: type: string phone: maxItems: 100 type: array items: type: string website: maxItems: 100 type: array items: type: string addressLine: maxItems: 100 type: array items: type: string city: type: string state: type: string postalCode: type: string physicalType: type: object properties: system: type: string code: type: string required: - code additionalProperties: false description: type: string position: type: object properties: latitude: type: number longitude: type: number required: - latitude - longitude additionalProperties: false additionalProperties: false serviceTypes: type: array items: type: object properties: system: type: string code: type: string display: type: string additionalProperties: false specialties: type: array items: type: object properties: system: type: string code: type: string display: type: string additionalProperties: false bookingMethod: type: string enum: - online - phone - contact isVirtual: type: boolean acceptingPatients: type: string enum: - nopt - newpt - existptonly - existptfam nextAvailableStart: type: string format: date-time totalSlots: type: integer minimum: 0 maximum: 9007199254740991 required: - key - publisher - serviceTypes - specialties - bookingMethod - totalSlots additionalProperties: false ProblemIssue: type: object properties: path: type: array description: The parameter, or the field within it, that is not valid. items: type: - string - integer message: type: string description: Why it is not valid. required: - path - message headers: XRequestId: description: >- The id haau3 gave this request, a UUID, on every response. Quote it in a question about the response. A problem carries the same id as its `instance`. schema: type: string format: uuid XCorrelationId: description: The `X-Request-Id` you sent, when it was a UUID. schema: type: string format: uuid responses: ProblemUnauthorized: description: Missing or invalid API key. headers: WWW-Authenticate: description: >- The scheme to authenticate with: `Bearer realm="api.haau3.com"`, with `error="invalid_token"` when a key was sent and not recognised. schema: type: string X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' ProblemNotAcceptable: description: The request's `Accept` header admits no JSON. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' ProblemTooManyRequests: description: >- A limit of the organization's plan was reached: its requests a minute, or the Developer plan's requests a month. Send the request again after `Retry-After`, which for the monthly limit runs to the 1st of the next month (UTC). headers: Retry-After: description: How many seconds to wait before sending the request again. schema: type: integer minimum: 0 X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' ProblemServerError: description: The server failed to process this request. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your platform API key (`haau3_sk_…`), sent as `Authorization: Bearer `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.