> 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. # List providers in your network GET https://staging.cail.health/v1/providers Returns a cursor-paginated list of providers in the operator’s jurisdiction. Filters cover service type, free-text search, freshness, verification state, source system, source adapter, and data-conflict status. Sort by name or by trust signals (sourceFetchedAt, freshUntil, expiresAt, verifiedAt) to triage rows that need review. The response includes provider open status, recent wait-time signals, and trust metadata so the network can be assessed at a glance. Use the cursor returned in `pagination.cursor` to step forward through pages; when `hasMore` is false, the cursor is null and the page is the last one. Reference: https://docs.cail.health/api-references/api-reference/curate-your-network/list ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: cail-api version: 1.0.0 paths: /v1/providers: get: operationId: list summary: List providers in your network description: >- Returns a cursor-paginated list of providers in the operator’s jurisdiction. Filters cover service type, free-text search, freshness, verification state, source system, source adapter, and data-conflict status. Sort by name or by trust signals (sourceFetchedAt, freshUntil, expiresAt, verifiedAt) to triage rows that need review. The response includes provider open status, recent wait-time signals, and trust metadata so the network can be assessed at a glance. Use the cursor returned in `pagination.cursor` to step forward through pages; when `hasMore` is false, the cursor is null and the page is the last one. tags: - subpackage_curateYourNetwork parameters: - name: cursor in: query description: Opaque cursor returned from a prior call. Omit on the first page. required: false schema: type: string - name: limit in: query description: Maximum number of results to return. Defaults to 20. Maximum 100. required: false schema: type: number format: double - name: sortBy in: query description: >- Sort field. Trust-related fields are useful when triaging stale or unverified rows. required: false schema: $ref: '#/components/schemas/V1ProvidersGetParametersSortBy' - name: sortOrder in: query description: Sort order. Defaults to desc. required: false schema: $ref: '#/components/schemas/V1ProvidersGetParametersSortOrder' - name: serviceTypeCode in: query description: Restrict results to providers offering this service type. required: false schema: type: string - name: searchTerm in: query description: Free-text search against provider name and address. required: false schema: type: string - name: freshnessStatus in: query description: Filter by freshness of the upstream sync. required: false schema: $ref: '#/components/schemas/V1ProvidersGetParametersFreshnessStatus' - name: verificationStatus in: query description: Filter by operator verification state. required: false schema: $ref: '#/components/schemas/V1ProvidersGetParametersVerificationStatus' - name: sourceSystem in: query description: Filter by upstream source system. required: false schema: type: string - name: sourceAdapter in: query description: Filter by upstream source adapter. required: false schema: type: string - name: conflictStatus in: query description: >- Filter by data-conflict state. Use "none" to find providers with no recorded conflicts. required: false schema: $ref: '#/components/schemas/V1ProvidersGetParametersConflictStatus' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: A cursor-paginated page of providers. content: application/json: schema: $ref: '#/components/schemas/ListProvidersResponse' servers: - url: https://staging.cail.health description: https://staging.cail.health components: schemas: V1ProvidersGetParametersSortBy: type: string enum: - name - sourceFetchedAt - freshUntil - expiresAt - verifiedAt title: V1ProvidersGetParametersSortBy V1ProvidersGetParametersSortOrder: type: string enum: - asc - desc title: V1ProvidersGetParametersSortOrder V1ProvidersGetParametersFreshnessStatus: type: string enum: - unknown - fresh - stale - expired title: V1ProvidersGetParametersFreshnessStatus V1ProvidersGetParametersVerificationStatus: type: string enum: - unverified - verified - rejected - needs_review title: V1ProvidersGetParametersVerificationStatus V1ProvidersGetParametersConflictStatus: type: string enum: - open - ignored - resolved_with_current - resolved_with_incoming - none title: V1ProvidersGetParametersConflictStatus ProviderListItemAddress: type: object properties: line1: type: string description: First address line. line2: type: string description: Second address line. city: type: string description: Town or city. postcode: type: string description: Postal code. country: type: string description: Country. title: ProviderListItemAddress ProviderListItemContactPhone: type: object properties: {} description: Public phone number. title: ProviderListItemContactPhone ProviderListItemContactWebsite: type: object properties: {} description: Public website. title: ProviderListItemContactWebsite ProviderListItemContact: type: object properties: phone: oneOf: - $ref: '#/components/schemas/ProviderListItemContactPhone' - type: 'null' description: Public phone number. website: oneOf: - $ref: '#/components/schemas/ProviderListItemContactWebsite' - type: 'null' description: Public website. required: - phone - website title: ProviderListItemContact ProviderListItemCoordinates: type: object properties: latitude: type: number format: double description: WGS84 latitude. longitude: type: number format: double description: WGS84 longitude. required: - latitude - longitude title: ProviderListItemCoordinates ProviderListItemIsOpen: type: object properties: {} description: >- True when the provider is open right now. Null when hours data is unavailable. title: ProviderListItemIsOpen ProviderListItemAvailableStartTime: type: object properties: {} description: >- Earliest open time today (HH:mm local). Null when hours data is unavailable. title: ProviderListItemAvailableStartTime ProviderListItemAvailableEndTime: type: object properties: {} description: >- Latest close time today (HH:mm local). Null when hours data is unavailable. title: ProviderListItemAvailableEndTime ProviderListItemAvailableTimeSlot: type: object properties: daysOfWeek: type: array items: type: string description: Days of the week this slot applies to. availableStartTime: type: string description: Slot start time (HH:mm local). availableEndTime: type: string description: Slot end time (HH:mm local). required: - daysOfWeek - availableStartTime - availableEndTime title: ProviderListItemAvailableTimeSlot ProviderListItemWaitTimeLatestReportAt: type: object properties: {} description: ISO 8601 timestamp of the most recent contributing report. title: ProviderListItemWaitTimeLatestReportAt ProviderListItemWaitTime: type: object properties: medianMinutes: type: number format: double description: Median wait time in minutes across recent reports. reportCount: type: number format: double description: Number of reports backing the median. latestReportAt: oneOf: - $ref: '#/components/schemas/ProviderListItemWaitTimeLatestReportAt' - type: 'null' description: ISO 8601 timestamp of the most recent contributing report. isStale: type: boolean description: True when the most recent report is older than the freshness window. required: - medianMinutes - reportCount - latestReportAt - isStale title: ProviderListItemWaitTime ProviderTrustFreshnessStatus: type: object properties: {} description: Freshness state of the row sourced from the upstream registry. title: ProviderTrustFreshnessStatus ProviderTrustVerificationStatus: type: object properties: {} description: Verification state assigned by the operator review workflow. title: ProviderTrustVerificationStatus ProviderTrustSourceSystem: type: object properties: {} description: >- Upstream registry the row was sourced from. Null for operator-authored rows. title: ProviderTrustSourceSystem ProviderTrustSourceAdapter: type: object properties: {} description: >- Adapter implementation that synced the row. Null for operator-authored rows. title: ProviderTrustSourceAdapter ProviderTrustSourceFetchedAt: type: object properties: {} description: ISO 8601 timestamp the adapter last pulled the upstream record. title: ProviderTrustSourceFetchedAt ProviderTrustFreshUntil: type: object properties: {} description: ISO 8601 timestamp after which the row is considered stale. title: ProviderTrustFreshUntil ProviderTrustExpiresAt: type: object properties: {} description: ISO 8601 timestamp when the row transitioned to expired. title: ProviderTrustExpiresAt ProviderTrustVerifiedAt: type: object properties: {} description: >- ISO 8601 timestamp when the row most recently entered a non-unverified state. title: ProviderTrustVerifiedAt ProviderTrust: type: object properties: freshnessStatus: oneOf: - $ref: '#/components/schemas/ProviderTrustFreshnessStatus' - type: 'null' description: Freshness state of the row sourced from the upstream registry. verificationStatus: oneOf: - $ref: '#/components/schemas/ProviderTrustVerificationStatus' - type: 'null' description: Verification state assigned by the operator review workflow. sourceSystem: oneOf: - $ref: '#/components/schemas/ProviderTrustSourceSystem' - type: 'null' description: >- Upstream registry the row was sourced from. Null for operator-authored rows. sourceAdapter: oneOf: - $ref: '#/components/schemas/ProviderTrustSourceAdapter' - type: 'null' description: >- Adapter implementation that synced the row. Null for operator-authored rows. sourceFetchedAt: oneOf: - $ref: '#/components/schemas/ProviderTrustSourceFetchedAt' - type: 'null' description: ISO 8601 timestamp the adapter last pulled the upstream record. freshUntil: oneOf: - $ref: '#/components/schemas/ProviderTrustFreshUntil' - type: 'null' description: ISO 8601 timestamp after which the row is considered stale. expiresAt: oneOf: - $ref: '#/components/schemas/ProviderTrustExpiresAt' - type: 'null' description: ISO 8601 timestamp when the row transitioned to expired. verifiedAt: oneOf: - $ref: '#/components/schemas/ProviderTrustVerifiedAt' - type: 'null' description: >- ISO 8601 timestamp when the row most recently entered a non-unverified state. required: - freshnessStatus - verificationStatus - sourceSystem - sourceAdapter - sourceFetchedAt - freshUntil - expiresAt - verifiedAt title: ProviderTrust ProviderListItem: type: object properties: id: type: string description: Stable provider identifier. name: type: string description: Display name for the provider. serviceTypeCode: type: string description: Primary service-type code offered by the provider. address: $ref: '#/components/schemas/ProviderListItemAddress' contact: $ref: '#/components/schemas/ProviderListItemContact' coordinates: oneOf: - $ref: '#/components/schemas/ProviderListItemCoordinates' - type: 'null' description: >- Geographic coordinates of the primary location. Null when no coordinates are published. isOpen: oneOf: - $ref: '#/components/schemas/ProviderListItemIsOpen' - type: 'null' description: >- True when the provider is open right now. Null when hours data is unavailable. availableStartTime: oneOf: - $ref: '#/components/schemas/ProviderListItemAvailableStartTime' - type: 'null' description: >- Earliest open time today (HH:mm local). Null when hours data is unavailable. availableEndTime: oneOf: - $ref: '#/components/schemas/ProviderListItemAvailableEndTime' - type: 'null' description: >- Latest close time today (HH:mm local). Null when hours data is unavailable. availableTime: type: - array - 'null' items: $ref: '#/components/schemas/ProviderListItemAvailableTimeSlot' description: Weekly availability windows. Null when no schedule is published. waitTime: oneOf: - $ref: '#/components/schemas/ProviderListItemWaitTime' - type: 'null' description: >- Wait-time data for the provider. Null when no recent reports are available. distanceMetres: type: number format: double description: >- Great-circle distance from the operator-supplied search anchor in metres. locationId: type: string description: Stable identifier for the primary location of the provider. organizationId: type: string description: Stable identifier for the operating organisation. trust: $ref: '#/components/schemas/ProviderTrust' description: >- Trust metadata for the row. Present once trust signals have been computed. required: - id - name - serviceTypeCode - address - locationId - organizationId title: ProviderListItem ListProvidersPaginationCursor: type: object properties: {} description: Opaque cursor for the next page. Null when there are no more results. title: ListProvidersPaginationCursor ListProvidersPagination: type: object properties: cursor: oneOf: - $ref: '#/components/schemas/ListProvidersPaginationCursor' - type: 'null' description: >- Opaque cursor for the next page. Null when there are no more results. hasMore: type: boolean description: True when more results exist after this page. limit: type: number format: double description: Echoes the requested page size for client convenience. required: - cursor - hasMore - limit title: ListProvidersPagination 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 ListProvidersResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/ProviderListItem' description: Provider rows for this page. pagination: $ref: '#/components/schemas/ListProvidersPagination' description: Cursor metadata for paging forward. meta: $ref: '#/components/schemas/ResponseMeta' required: - data - pagination - meta title: ListProvidersResponse securitySchemes: auth0Bearer: type: http scheme: bearer ``` ## Examples **Response** ```json { "data": [ { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "name": "St Thomas' Hospital", "serviceTypeCode": "50849002", "address": { "line1": "Westminster Bridge Road", "city": "London", "postcode": "SE1 7EH", "country": "United Kingdom" }, "locationId": "b3c8a5d2-1f4e-4d9a-9c8b-7a6e5f4d3c2b", "organizationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "contact": { "phone": "+442071887188", "website": "https://example.nhs.uk" }, "coordinates": { "latitude": 51.4988, "longitude": -0.1187 }, "isOpen": true, "availableStartTime": "00:00", "availableEndTime": "23:59", "availableTime": null, "waitTime": { "medianMinutes": 22, "reportCount": 14, "latestReportAt": "2026-05-12T14:21:00.000Z", "isStale": false }, "trust": { "freshnessStatus": "fresh", "verificationStatus": "verified", "sourceSystem": "ods", "sourceAdapter": "nhs-ods-v1", "sourceFetchedAt": "2026-05-10T03:00:00.000Z", "freshUntil": "2026-06-09T03:00:00.000Z", "expiresAt": null, "verifiedAt": "2026-04-19T11:32:00.000Z" } } ], "pagination": { "cursor": "eyJpZCI6ICJvcmdfMDJIIn0", "hasMore": true, "limit": 25 }, "meta": { "requestId": "4a3b2c1d-5e6f-4890-9abc-def0fedcba98", "timestamp": "2026-05-13T14:21:00.000Z", "durationMs": 65 } } ``` **SDK Code** ```python First page of 25 providers, sorted by name import requests url = "https://staging.cail.health/v1/providers" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript First page of 25 providers, sorted by name const url = 'https://staging.cail.health/v1/providers'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go First page of 25 providers, sorted by name package main import ( "fmt" "net/http" "io" ) func main() { url := "https://staging.cail.health/v1/providers" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby First page of 25 providers, sorted by name require 'uri' require 'net/http' url = URI("https://staging.cail.health/v1/providers") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java First page of 25 providers, sorted by name import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://staging.cail.health/v1/providers") .header("Authorization", "Bearer ") .asString(); ``` ```php First page of 25 providers, sorted by name request('GET', 'https://staging.cail.health/v1/providers', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp First page of 25 providers, sorted by name using RestSharp; var client = new RestClient("https://staging.cail.health/v1/providers"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift First page of 25 providers, sorted by name import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://staging.cail.health/v1/providers")! 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() ```