openapi: 3.1.0
info:
  title: Chapter Provider API
  description: >
    The Chapter Provider API gives you access to:


    - Coverage information for provider-plan combinations

    - Location-based provider search

    - Specific provider location lookups


    All endpoints require a valid bearer token. Contact support@getchapter.com
    to request credentials.
  version: 1.6.1
  contact:
    name: Chapter Support
    email: support@getchapter.com
servers:
  - url: https://api2.askchapter.org/v2
    description: Production server
  - url: https://api2.staging.askchapter.org/v2
    description: Staging server
security:
  - bearerAuth: []
x-tagGroups:
  - name: Providers
    tags:
      - Providers
  - name: Plan Coverage Queries
    tags:
      - Coverage
tags:
  - name: Providers
    description: Locate providers based on geographic and semantic search inputs
  - name: Coverage
    description: Query provider coverage by plan and NPI
paths:
  /providers/search:
    post:
      summary: Search providers
      description: >
        Search for providers using flexible location options and query string.
        Supports searching by provider name, hospital group, or other text
        combined with various location formats.
      operationId: search
      tags:
        - Providers
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UniversalSearchRequest'
      responses:
        '200':
          description: List of providers matching the search criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedSearchResponse'
  /providers/coverage:
    post:
      summary: Get provider coverage by plan and NPI
      description: >
        Returns a nested list of provider coverage results grouped by bid ID and
        NPI. Used to determine whether a provider participates in specific
        Medicare Advantage plans.
      operationId: getProviderCoverage
      tags:
        - Coverage
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CoverageRequest'
      responses:
        '200':
          description: Nested list of provider plan coverage results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoverageResponse'
  /providers/{npi}:
    get:
      summary: Get metadata for a specific provider
      description: |
        Use this endpoint to retrieve metadata for a provider by NPI.
      operationId: getProvider
      tags:
        - Providers
      parameters:
        - name: npi
          in: path
          required: true
          schema:
            type: string
            example: '1234567890'
      responses:
        '200':
          description: Provider metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Provider'
  /providers/{npi}/locations:
    get:
      summary: Get all known locations for a specific provider
      description: >
        Use this endpoint to retrieve every known practice location for a
        provider by NPI.
      operationId: getProviderLocations
      tags:
        - Providers
      parameters:
        - name: npi
          in: path
          required: true
          schema:
            type: string
            example: '1234567890'
      responses:
        '200':
          description: List of provider locations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProviderLocation'
components:
  schemas:
    NpiWithLocationsInput:
      type: object
      required:
        - npi
      properties:
        npi:
          type: string
          example: '1234567890'
        locationIds:
          type: array
          items:
            type: string
          example:
            - loc_001
            - loc_002
    CoverageRequest:
      type: object
      required:
        - contractYear
        - bidIds
        - npis
      properties:
        contractYear:
          type: integer
          example: 2023
          description: Contract year to query (e.g., 2023)
        bidIds:
          type: array
          description: Medicare bid IDs for plan lookup
          items:
            type: string
            example: H1234_001_000
        npis:
          type: array
          description: List of NPIs and optional related location IDs
          items:
            $ref: '#/components/schemas/NpiWithLocationsInput'
    CoverageResponse:
      type: array
      items:
        $ref: '#/components/schemas/PlanCoverage'
      example:
        - contractYear: 2023
          bidId: H1234_001_000
          providers:
            - provider:
                id: 070851a5-9501-4801-9074-d84b88b8a804
                npis:
                  - '1234567890'
                firstName: Jane
                lastName: Smith
                gender: F
                credentials:
                  - MD
                languages:
                  - English
              networkStatus: in_network
              locations:
                - id: loc_001
                  networkStatus: in_network
                  address:
                    streetLine1: 123 Main St
                    streetLine2: null
                    city: New York
                    state: NY
                    zip: '10001'
                    fullAddress: 123 Main St, New York, NY 10001
                    latitude: 40.7128
                    longitude: -74.006
                  phoneNumbers:
                    - '+12125551234'
                  faxNumbers:
                    - '+12125551235'
                  website: https://www.example.com
                  email: contact@example.com
                  pcpEligible: true
                  groupAffiliations: []
                  hospitalAffiliations: []
                - id: loc_002
                  networkStatus: out_of_network
                  address:
                    streetLine1: 441 Adams St
                    streetLine2: null
                    city: New York
                    state: NY
                    zip: '10001'
                    fullAddress: 441 Adams St, New York, NY 10001
                    latitude: 40.71281
                    longitude: -74.00601
                  phoneNumbers:
                    - '+16055551234'
                  faxNumbers: []
                  website: null
                  email: null
                  pcpEligible: false
                  groupAffiliations: []
                  hospitalAffiliations: []
    PlanCoverage:
      type: object
      properties:
        contractYear:
          type: integer
          example: 2023
        bidId:
          type: string
          example: H1234_001_000
        providers:
          type: array
          items:
            $ref: '#/components/schemas/PlanProviderCoverage'
    PlanProviderCoverage:
      type: object
      properties:
        provider:
          $ref: '#/components/schemas/Provider'
        networkStatus:
          type: string
          enum:
            - in_network
            - out_of_network
          description: The provider's overall network status with this plan
          example: in_network
        locations:
          type: array
          items:
            $ref: '#/components/schemas/ProviderLocationWithNetworkStatus'
    UniversalSearchRequest:
      type: object
      required:
        - location
        - radius
      properties:
        query:
          type: string
          example: Dr. Johnson Mount Sinai
          description: Search query for provider names, hospital groups, specialties, etc.
        location:
          oneOf:
            - type: object
              required:
                - lat
                - lng
              properties:
                lat:
                  type: number
                  example: 40.7128
                  description: Latitude coordinate
                lng:
                  type: number
                  example: -74.006
                  description: Longitude coordinate
              additionalProperties: false
            - type: object
              required:
                - query
              properties:
                query:
                  type: string
                  example: Brooklyn, New York
                  description: >-
                    Fuzzy location string (e.g. "NYC", "Brooklyn, New York",
                    "Chicago")
              additionalProperties: false
            - type: object
              required:
                - zip
              properties:
                zip:
                  type: string
                  example: '10001'
                  description: 5-digit ZIP code
              additionalProperties: false
        radius:
          type: number
          example: 10
          description: Search radius in miles
        pageSize:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
          description: Number of results to return per page
        offset:
          type: integer
          minimum: 0
          default: 0
          description: Number of results to skip for pagination
    PaginatedSearchResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/ProviderWithLocations'
        pageSize:
          type: integer
          description: Page size of current page
          example: 50
        offset:
          type: integer
          description: Current offset
          example: 0
        totalCount:
          type: integer
          description: Total number of results available
          example: 150
    WithMinDistance:
      allOf:
        - type: object
          properties:
            minDistanceMiles:
              type: number
              example: 1.3
              description: Distance of the closest location match
        - $ref: '#/components/schemas/ProviderWithLocations'
    ProviderWithLocations:
      type: object
      properties:
        provider:
          $ref: '#/components/schemas/Provider'
        locations:
          type: array
          items:
            $ref: '#/components/schemas/ProviderLocation'
    Address:
      type: object
      properties:
        streetLine1:
          type: string
          example: 123 Main St
          description: Primary street address line
        streetLine2:
          type:
            - string
            - 'null'
          example: Suite 200
          description: Secondary street address line (apartment, suite, etc.)
        streetLine3:
          type:
            - string
            - 'null'
          example: Rm 22
          description: Tertiary street address line
        city:
          type: string
          example: New York
          description: City name
        state:
          type: string
          example: NY
          description: State abbreviation
        zip:
          type: string
          example: '10001'
          description: ZIP code
        fullAddress:
          type: string
          example: 123 Main St Suite 200, New York, NY 10001
          description: Complete formatted address string
        latitude:
          type:
            - number
            - 'null'
          example: 40.7128
          description: Latitude coordinate (optional)
        longitude:
          type:
            - number
            - 'null'
          example: -74.006
          description: Longitude coordinate (optional)
    Provider:
      type: object
      properties:
        id:
          type: string
          example: 070851a5-9501-4801-9074-d84b88b8a804
        npis:
          type: array
          items:
            type: string
            example: '1234567890'
        doingBusinessAs:
          type:
            - string
            - 'null'
        firstName:
          type:
            - string
            - 'null'
          example: Jane
        lastName:
          type:
            - string
            - 'null'
          example: Smith
        middleName:
          type:
            - string
            - 'null'
          example: Marie
        prefix:
          type:
            - string
            - 'null'
          example: Dr.
        suffix:
          type:
            - string
            - 'null'
          example: Jr
        gender:
          type: string
          enum:
            - F
            - M
            - X
          example: F
        credentials:
          type: array
          items:
            type: string
            example: MD
        languages:
          type: array
          items:
            type: string
            example: English
        groupAffiliations:
          type: array
          items:
            type: string
            example: Vision Medical Group
        hospitalAffiliations:
          type: array
          items:
            type: string
            example: Rogue County Medical
    ProviderLocation:
      type: object
      properties:
        id:
          type: string
          description: Provider location identifier
          example: loc_001
        address:
          $ref: '#/components/schemas/Address'
        phoneNumbers:
          type: array
          items:
            type: string
            description: E.164 formatted phone number
            example: '+14155552671'
        faxNumbers:
          type: array
          items:
            type: string
            description: E.164 formatted fax number
            example: '+14155552671'
        website:
          type:
            - string
            - 'null'
          example: https://www.example.com
        email:
          type:
            - string
            - 'null'
          example: contact@example.com
        groupAffiliations:
          type: array
          description: Groups affiliated with this location
          items:
            type: string
            example: Community Health Center
        hospitalAffiliations:
          type: array
          description: Hospitals affiliated with this location
          items:
            type: string
            example: Rogue County Medical
        pcpEligible:
          type: boolean
          description: >-
            Whether the provider may be eligible for PCP designation at this
            location
    ProviderLocationWithNetworkStatus:
      allOf:
        - $ref: '#/components/schemas/ProviderLocation'
        - type: object
          properties:
            networkStatus:
              type: string
              enum:
                - in_network
                - out_of_network
              example: in_network
              description: >-
                The provider's network status designation at this particular
                location.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Authenticate using a bearer token in the `Authorization` header.
        Example: `Authorization: Bearer YOUR_TOKEN_HERE`
