> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tavrn.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search facilities

> Search by facility name, alias, phone, fax, address, or NPI. Requires retrievals:read. Use a result's id as facility_id when creating a retrieval request.



## OpenAPI

````yaml GET /v2/facilities
openapi: 3.0.1
info:
  title: Tavrn Platform API
  version: 1.0.0
  description: >-
    Enterprise API for medical record retrieval: cases, retrieval requests,
    retrieved records and provider invoices, case documents, and webhook
    notifications.
  contact:
    name: Tavrn Support
    email: contact@tavrn.ai
servers:
  - url: https://enterprise.tavrn.ai
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: Cases
    description: Case management operations
  - name: Documents
    description: Document upload and management
  - name: Retrieval Requests
    description: Medical record retrieval requests submitted to healthcare facilities
  - name: Requestors
    description: Multiple retrieval profiles within one organization
  - name: Webhooks
    description: Webhook registration and event notifications
paths:
  /v2/facilities:
    get:
      tags:
        - Retrieval Requests
      summary: Search facilities
      description: >-
        Search by facility name, alias, phone, fax, address, or NPI. Requires
        retrievals:read. Use a result's id as facility_id when creating a
        retrieval request.
      operationId: searchFacilities
      parameters:
        - name: q
          in: query
          required: true
          description: >-
            Search text, trimmed before validation. Must contain at least 3
            alphanumeric characters.
          schema:
            type: string
            minLength: 3
            maxLength: 200
          example: Example Hospital
        - name: state
          in: query
          description: Optional uppercase US state code.
          schema:
            type: string
            pattern: ^[A-Z]{2}$
          example: PA
        - name: limit
          in: query
          description: Maximum results to return.
          schema:
            type: integer
            minimum: 1
            maximum: 10
            default: 10
      responses:
        '200':
          description: Matching facilities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FacilitySearchResponse'
              example:
                results:
                  - id: facility_example
                    name: Example General Hospital
                    requirements: []
        '400':
          description: Invalid search parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Requires retrievals:read
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests. Wait for Retry-After before trying again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
        '503':
          description: Search temporarily unavailable; try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    FacilitySearchResponse:
      type: object
      required:
        - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/FacilitySearchResult'
      description: Matching facilities. No pagination or total count.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Machine-readable error code
              example: validation_error
            message:
              type: string
              description: Human-readable error message
              example: The patient.date_of_birth field is required
    FacilitySearchResult:
      type: object
      required:
        - id
        - name
        - requirements
      properties:
        id:
          type: string
          description: Facility ID to pass as facility_id when creating a retrieval.
          example: facility_example
        name:
          type: string
          example: Example General Hospital
        requirements:
          type: array
          items:
            $ref: '#/components/schemas/FacilityRequirement'
          description: Requirements for requesting records. Empty when none are listed.
    FacilityRequirement:
      type: object
      required:
        - slug
        - label
        - description
        - category
        - record_types
      properties:
        slug:
          type: string
          description: Requirement identifier.
        label:
          type: string
          description: Requirement name.
        description:
          type: string
          nullable: true
          description: Additional instructions, when available.
        category:
          type: string
          enum:
            - input
            - document
            - instruction
        record_types:
          type: array
          items:
            type: string
          description: >-
            Applicable record categories, such as medical_records, billings, or
            radiology. Empty means all record types.
        template_download_url:
          type: string
          format: uri
          description: >-
            For document requirements, a download link to a blank template when
            available. Valid for 1 hour; repeat the facility search for a fresh
            link. Omitted when unavailable.
          example: https://example.com/authorization-template.pdf
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        API key authentication. Use format: `Authorization: Bearer
        tavrn_sk_live_...`

````