> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cail.health/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cail.health/_mcp/server.

# Search providers by free-text query

GET https://staging.cail.health/v1/search/text

Returns providers matching the supplied query, ranked by full-text relevance. Searches the provider name, address, postcode, and specialty. Results are restricted to the operator’s jurisdiction and the operator’s service scope. Each result carries operational signals (open hours, recent wait times) and a coarse data-quality tier so the network can be triaged without a second round-trip. Use the offset/limit parameters to step through large result sets; the response includes a `hasMore` flag and a running total.

Reference: https://docs.cail.health/api-references/api-reference/find-care/text

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: cail-api
  version: 1.0.0
paths:
  /v1/search/text:
    get:
      operationId: text
      summary: Search providers by free-text query
      description: >-
        Returns providers matching the supplied query, ranked by full-text
        relevance. Searches the provider name, address, postcode, and specialty.
        Results are restricted to the operator’s jurisdiction and the operator’s
        service scope. Each result carries operational signals (open hours,
        recent wait times) and a coarse data-quality tier so the network can be
        triaged without a second round-trip. Use the offset/limit parameters to
        step through large result sets; the response includes a `hasMore` flag
        and a running total.
      tags:
        - subpackage_findCare
      parameters:
        - name: query
          in: query
          description: >-
            Free-text query against provider name, address, postcode, and
            specialty.
          required: true
          schema:
            type: string
        - name: serviceTypeCode
          in: query
          description: Restrict results to providers offering this service type.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of results to return. Defaults to 10. Maximum 50.
          required: false
          schema:
            type: number
            format: double
        - name: offset
          in: query
          description: Zero-based offset into the result set. Defaults to 0.
          required: false
          schema:
            type: number
            format: double
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A page of providers matching the text query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TextSearchResponse'
servers:
  - url: https://staging.cail.health
    description: https://staging.cail.health
components:
  schemas:
    ProviderAddressInfo:
      type: object
      properties:
        line:
          type: array
          items:
            type: string
          description: Address lines as printed.
        city:
          type: string
          description: Town or city.
        district:
          type: string
          description: Administrative district.
        postalCode:
          type: string
          description: Postal code.
      required:
        - line
        - city
        - district
        - postalCode
      title: ProviderAddressInfo
    ProviderSearchResultPhone:
      type: object
      properties: {}
      description: Contact phone number for the provider location, if published.
      title: ProviderSearchResultPhone
    ProviderSearchResultWebsite:
      type: object
      properties: {}
      description: Public website for the provider location, if published.
      title: ProviderSearchResultWebsite
    ProviderCoordinatesInfo:
      type: object
      properties:
        latitude:
          type: number
          format: double
          description: WGS84 latitude.
        longitude:
          type: number
          format: double
          description: WGS84 longitude.
      required:
        - latitude
        - longitude
      title: ProviderCoordinatesInfo
    ProviderSearchResultDistanceMetres:
      type: object
      properties: {}
      description: >-
        Great-circle distance from the search origin in metres. Always populated
        for proximity search.
      title: ProviderSearchResultDistanceMetres
    ProviderSearchResultIsOpenNow:
      type: object
      properties: {}
      description: >-
        True when the location is open right now. Null when hours data is
        unavailable.
      title: ProviderSearchResultIsOpenNow
    ProviderWaitTimeInfoMedianMinutes:
      type: object
      properties: {}
      description: >-
        Median wait time in minutes across recent reports. Null when no reports
        are available.
      title: ProviderWaitTimeInfoMedianMinutes
    ProviderWaitTimeInfoNewestReportAt:
      type: object
      properties: {}
      description: ISO 8601 timestamp of the most recent contributing report.
      title: ProviderWaitTimeInfoNewestReportAt
    ProviderWaitTimeInfo:
      type: object
      properties:
        medianMinutes:
          oneOf:
            - $ref: '#/components/schemas/ProviderWaitTimeInfoMedianMinutes'
            - type: 'null'
          description: >-
            Median wait time in minutes across recent reports. Null when no
            reports are available.
        reportCount:
          type: number
          format: double
          description: Number of reports backing the median.
        isStale:
          type: boolean
          description: >-
            True when the most recent report is older than the freshness window.
            Stale data SHOULD be rendered with a "last updated" hint.
        newestReportAt:
          oneOf:
            - $ref: '#/components/schemas/ProviderWaitTimeInfoNewestReportAt'
            - type: 'null'
          description: ISO 8601 timestamp of the most recent contributing report.
      required:
        - medianMinutes
        - reportCount
        - isStale
        - newestReportAt
      title: ProviderWaitTimeInfo
    ProviderSearchResultAvailabilityStatus:
      type: string
      enum:
        - open_now
        - opens_later
        - closed_today
        - unknown_hours
      description: Synthesised availability, derived from open hours and schedule data.
      title: ProviderSearchResultAvailabilityStatus
    ProviderSearchResultAction:
      oneOf:
        - type: object
          properties:
            kind:
              type: string
              enum:
                - call
              description: 'Discriminator value: call'
            phone:
              type: string
              description: E.164 or locally-formatted phone number to call.
          required:
            - kind
            - phone
          description: call variant
        - type: object
          properties:
            kind:
              type: string
              enum:
                - visit_website
              description: 'Discriminator value: visit_website'
            url:
              type: string
              description: Absolute URL to open as the primary engagement action.
          required:
            - kind
            - url
          description: visit_website variant
        - type: object
          properties:
            kind:
              type: string
              enum:
                - navigate
              description: 'Discriminator value: navigate'
          required:
            - kind
          description: navigate variant
        - type: object
          properties:
            kind:
              type: string
              enum:
                - none
              description: 'Discriminator value: none'
          required:
            - kind
          description: none variant
      discriminator:
        propertyName: kind
      description: >-
        Recommended primary engagement action. Single-valued by precedence (call
        > visit_website > navigate > none).
      title: ProviderSearchResultAction
    ProviderConfidenceInfoLevel:
      type: string
      enum:
        - high
        - medium
        - low
        - unknown
      description: >-
        Coarse data-quality tier. Render this prominently when guiding member
        decisions.
      title: ProviderConfidenceInfoLevel
    ProviderConfidenceInfo:
      type: object
      properties:
        level:
          $ref: '#/components/schemas/ProviderConfidenceInfoLevel'
          description: >-
            Coarse data-quality tier. Render this prominently when guiding
            member decisions.
        reasonCodes:
          type: array
          items:
            type: string
          description: >-
            Machine-readable reason codes explaining the confidence level.
            Sorted and deduplicated. Stable for analytics.
      required:
        - level
        - reasonCodes
      title: ProviderConfidenceInfo
    ProviderSearchResult:
      type: object
      properties:
        providerId:
          type: string
          description: Stable provider identifier.
        name:
          type: string
          description: Display name for the provider.
        address:
          $ref: '#/components/schemas/ProviderAddressInfo'
        phone:
          oneOf:
            - $ref: '#/components/schemas/ProviderSearchResultPhone'
            - type: 'null'
          description: Contact phone number for the provider location, if published.
        website:
          oneOf:
            - $ref: '#/components/schemas/ProviderSearchResultWebsite'
            - type: 'null'
          description: Public website for the provider location, if published.
        coordinates:
          $ref: '#/components/schemas/ProviderCoordinatesInfo'
        distanceMetres:
          oneOf:
            - $ref: '#/components/schemas/ProviderSearchResultDistanceMetres'
            - type: 'null'
          description: >-
            Great-circle distance from the search origin in metres. Always
            populated for proximity search.
        serviceTypes:
          type: array
          items:
            type: string
          description: Service-type codes offered at this location.
        isOpenNow:
          oneOf:
            - $ref: '#/components/schemas/ProviderSearchResultIsOpenNow'
            - type: 'null'
          description: >-
            True when the location is open right now. Null when hours data is
            unavailable.
        waitTime:
          oneOf:
            - $ref: '#/components/schemas/ProviderWaitTimeInfo'
            - type: 'null'
          description: >-
            Wait-time data for the location. Null when no recent reports are
            available.
        availabilityStatus:
          $ref: '#/components/schemas/ProviderSearchResultAvailabilityStatus'
          description: Synthesised availability, derived from open hours and schedule data.
        routingReasonCodes:
          type: array
          items:
            type: string
          description: Operational reason codes describing why this result is actionable.
        action:
          $ref: '#/components/schemas/ProviderSearchResultAction'
          description: >-
            Recommended primary engagement action. Single-valued by precedence
            (call > visit_website > navigate > none).
        confidence:
          $ref: '#/components/schemas/ProviderConfidenceInfo'
      required:
        - providerId
        - name
        - address
        - phone
        - website
        - coordinates
        - distanceMetres
        - serviceTypes
        - isOpenNow
        - availabilityStatus
        - routingReasonCodes
        - action
        - confidence
      title: ProviderSearchResult
    OffsetPageInfo:
      type: object
      properties:
        total:
          type: number
          format: double
          description: Total number of items across all pages.
        limit:
          type: number
          format: double
          description: Echoes the requested page size for client convenience.
        offset:
          type: number
          format: double
          description: Echoes the requested zero-based offset.
        hasMore:
          type: boolean
          description: True when more results exist after this page.
      required:
        - total
        - limit
        - offset
        - hasMore
      title: OffsetPageInfo
    ResponseMeta:
      type: object
      properties:
        requestId:
          type: string
          description: >-
            Opaque request identifier echoed for support traceability. Matches
            the x-request-id response header.
        timestamp:
          type: string
          description: ISO 8601 timestamp at which the server completed the request.
        durationMs:
          type: number
          format: double
          description: Server-measured request duration in milliseconds.
      required:
        - requestId
        - timestamp
        - durationMs
      title: ResponseMeta
    TextSearchResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ProviderSearchResult'
          description: Provider rows matching the query, ranked by relevance.
        pagination:
          $ref: '#/components/schemas/OffsetPageInfo'
          description: Pagination metadata for stepping forward by offset.
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      required:
        - data
        - pagination
        - meta
      title: TextSearchResponse
  securitySchemes:
    auth0Bearer:
      type: http
      scheme: bearer

```

## Examples



**Response**

```json
{
  "data": [
    {
      "providerId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "St Thomas' Hospital",
      "address": {
        "line": [
          "Westminster Bridge Road"
        ],
        "city": "London",
        "district": "Greater London",
        "postalCode": "SE1 7EH"
      },
      "phone": "+442071887188",
      "website": "https://example.nhs.uk",
      "coordinates": {
        "latitude": 51.4988,
        "longitude": -0.1187
      },
      "distanceMetres": null,
      "serviceTypes": [
        "50849002"
      ],
      "isOpenNow": true,
      "availabilityStatus": "open_now",
      "routingReasonCodes": [
        "match.service_type",
        "match.open_now"
      ],
      "action": {
        "kind": "call",
        "phone": "+442071887188"
      },
      "confidence": {
        "level": "high",
        "reasonCodes": [
          "data.has_hours",
          "data.recent_wait_time"
        ]
      },
      "waitTime": {
        "medianMinutes": 22,
        "reportCount": 14,
        "isStale": false,
        "newestReportAt": "2026-05-12T14:21:00.000Z"
      }
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 10,
    "offset": 0,
    "hasMore": false
  },
  "meta": {
    "requestId": "4a3b2c1d-5e6f-4890-9abc-def0fedcba98",
    "timestamp": "2026-05-13T14:21:00.000Z",
    "durationMs": 38
  }
}
```

**SDK Code**

```python A single matching provider for "cardiac surgery london"
import requests

url = "https://staging.cail.health/v1/search/text"

querystring = {"query":"cardiac surgery london"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript A single matching provider for "cardiac surgery london"
const url = 'https://staging.cail.health/v1/search/text?query=cardiac+surgery+london';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go A single matching provider for "cardiac surgery london"
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://staging.cail.health/v1/search/text?query=cardiac+surgery+london"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby A single matching provider for "cardiac surgery london"
require 'uri'
require 'net/http'

url = URI("https://staging.cail.health/v1/search/text?query=cardiac+surgery+london")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java A single matching provider for "cardiac surgery london"
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://staging.cail.health/v1/search/text?query=cardiac+surgery+london")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php A single matching provider for "cardiac surgery london"
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://staging.cail.health/v1/search/text?query=cardiac+surgery+london', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp A single matching provider for "cardiac surgery london"
using RestSharp;

var client = new RestClient("https://staging.cail.health/v1/search/text?query=cardiac+surgery+london");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift A single matching provider for "cardiac surgery london"
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://staging.cail.health/v1/search/text?query=cardiac+surgery+london")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```