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

# Submit an eligibility check

> Creates a new insurance eligibility check task for the given subscriber and provider. The check is processed asynchronously. Use the `id` in the response to poll for the result via `GET /api/eligibility/{id}/status`.



## OpenAPI

````yaml /openapi/eligibility.json post /api/eligibility
openapi: 3.1.0
info:
  title: Shasta Health Eligibility API
  description: >-
    API for submitting insurance eligibility check requests and polling their
    status. Requests are authenticated using an API key issued from the Shasta
    provider portal.
  version: 1.0.0
servers:
  - url: https://app.shasta.health
    description: Production
security: []
tags:
  - name: Eligibility
    description: Submit insurance eligibility check requests and retrieve their status.
  - name: Webhooks
    description: Webhook events fired by Shasta when async operations complete.
paths:
  /api/eligibility:
    post:
      tags:
        - Eligibility
      summary: Submit an eligibility check
      description: >-
        Creates a new insurance eligibility check task for the given subscriber
        and provider. The check is processed asynchronously. Use the `id` in the
        response to poll for the result via `GET /api/eligibility/{id}/status`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EligibilityCheckRequest'
            example:
              provider:
                organizationName: Shasta Medical Group
                npi: '1234567890'
              subscriber:
                firstName: Jane
                lastName: Doe
                dateOfBirth: '19800115'
                memberId: XYZ123456
              encounter:
                dateOfService: '20260301'
                serviceTypeCodes:
                  - '30'
              tradingPartnerServiceId: '60054'
      responses:
        '200':
          description: Eligibility check accepted and queued for processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EligibilityStatusResponse'
              example:
                id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                status: IN_PROGRESS
        '400':
          description: Request body failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationExceptionResponse'
              example:
                code: ValidationException
                message: Missing required subscriber fields
                fieldList:
                  - path: /subscriber/dateOfBirth
                    message: dateOfBirth is required
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: UnauthorizedException
                message: Unauthorized
        '403':
          description: The API key does not have permission to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: AccessDeniedException
                message: Site is not configured for eligibility checks
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: ResourceNotFoundException
                message: Site not found
        '429':
          description: Rate limit exceeded. Retry after a short delay.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: ThrottlingException
                message: Too many requests, please retry later
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: InternalFailureException
                message: Internal server error
      security:
        - ApiKeyAuth: []
components:
  schemas:
    EligibilityCheckRequest:
      type: object
      properties:
        controlNumber:
          type: string
          description: Optional client-supplied control number (up to 9 digits).
        eligibilitySearchId:
          type: string
        externalPatientId:
          type: string
          description: >-
            Your internal patient identifier; returned in the response for
            correlation.
        provider:
          $ref: '#/components/schemas/Provider'
        subscriber:
          $ref: '#/components/schemas/Subscriber'
        dependents:
          type: array
          items:
            $ref: '#/components/schemas/Dependent'
        encounter:
          $ref: '#/components/schemas/Encounter'
        tradingPartnerName:
          type: string
        tradingPartnerServiceId:
          type: string
          minLength: 1
          description: Payer trading-partner ID. Required.
          example: '60054'
        portalUsername:
          type: string
        portalPassword:
          type: string
        submitterTransactionIdentifier:
          type: string
      required:
        - provider
        - subscriber
        - tradingPartnerServiceId
    EligibilityStatusResponse:
      type: object
      properties:
        id:
          type: string
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        status:
          type: string
          description: Current task status.
          example: IN_PROGRESS
      required:
        - id
        - status
    ValidationExceptionResponse:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            fieldList:
              type: array
              items:
                $ref: '#/components/schemas/ValidationExceptionField'
              description: Present only on `ValidationException` responses.
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error classification.
          enum:
            - ValidationException
            - UnauthorizedException
            - AccessDeniedException
            - ResourceNotFoundException
            - ThrottlingException
            - InternalFailureException
        message:
          type: string
      required:
        - message
    Provider:
      type: object
      properties:
        organizationName:
          type: string
          example: Shasta Medical Group
        firstName:
          type: string
        lastName:
          type: string
        npi:
          type: string
          description: 10-digit National Provider Identifier.
          example: '1234567890'
        address:
          $ref: '#/components/schemas/RequestAddress'
        providerType:
          type: string
          enum:
            - provider
            - facility
          description: >-
            Type of provider. `provider` for individual provider, `facility` for
            organization or facility.
          example: provider
      description: The rendering or billing provider.
    Subscriber:
      type: object
      properties:
        firstName:
          type: string
          minLength: 1
          description: Subscriber's first name.
          example: Jane
        lastName:
          type: string
          minLength: 1
          description: Subscriber's last name.
          example: Doe
        dateOfBirth:
          type: string
          minLength: 1
          description: Date of birth in `YYYYMMDD` format.
          example: '19800101'
        memberId:
          type: string
          description: Insurance member/policy ID.
          example: XYZ123456
        middleName:
          type: string
        suffix:
          type: string
        groupNumber:
          type: string
        gender:
          type: string
          description: '`M` for male, `F` for female, `U` for unknown.'
        address:
          $ref: '#/components/schemas/RequestAddress'
        idCard:
          type: string
        providerCode:
          type: string
        providerIdentifier:
          type: string
        referenceIdentificationQualifier:
          type: string
        healthCareCodeInformation:
          type: array
          items:
            $ref: '#/components/schemas/HealthCareInformation'
      required:
        - firstName
        - lastName
        - dateOfBirth
      description: The insurance subscriber.
    Dependent:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        dateOfBirth:
          type: string
          description: Date of birth in `YYYYMMDD` format.
          example: '20100615'
        middleName:
          type: string
        suffix:
          type: string
        gender:
          type: string
        address:
          $ref: '#/components/schemas/RequestAddress'
        groupNumber:
          type: string
        individualRelationshipCode:
          type: string
          description: EDI X12 relationship code, e.g. `01` for spouse, `19` for child.
        providerCode:
          type: string
        providerIdentifier:
          type: string
        referenceIdentificationQualifier:
          type: string
        healthCareCodeInformation:
          type: array
          items:
            $ref: '#/components/schemas/HealthCareInformation'
      description: A dependent covered under the subscriber's plan.
    Encounter:
      type: object
      properties:
        dateOfService:
          type: string
          description: Date of service in `YYYYMMDD` format.
        beginningDateOfService:
          type: string
        endDateOfService:
          type: string
        serviceTypeCodes:
          type: array
          items:
            type: string
          description: >-
            X12 service type codes, e.g. `['30']` for health benefit plan
            coverage.
        procedureCode:
          type: string
        productOrServiceIDQualifier:
          type: string
        procedureModifiers:
          type: array
          items:
            type: string
        diagnosisCodePointer:
          type: array
          items:
            type: string
        priorAuthorizationOrReferralNumber:
          type: string
        referenceIdentificationQualifier:
          type: string
      description: Details about the planned or completed encounter.
    ValidationExceptionField:
      type: object
      properties:
        path:
          type: string
          description: >-
            JSON Pointer path to the invalid field, e.g.
            `/subscriber/firstName`.
        message:
          type: string
      required:
        - path
        - message
    RequestAddress:
      type: object
      properties:
        address1:
          type: string
        address2:
          type: string
        city:
          type: string
        state:
          type: string
          description: Two-letter state code, e.g. `CA`.
        postalCode:
          type: string
        countryCode:
          type: string
        countrySubDivisionCode:
          type: string
      description: Mailing or service address.
      example:
        address1: 123 Main St
        city: San Francisco
        state: CA
        postalCode: '94110'
        countryCode: US
        countrySubDivisionCode: CA
    HealthCareInformation:
      type: object
      properties:
        diagnosisCode:
          type: string
        diagnosisTypeCode:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Pass your API key as `Key <your-api-key>`. Example: `Authorization: Key
        sk_abc123`

````