openapi: 3.1.0 info: title: Member Eligibility Verification API version: 1.0.0 description: > Provides a single business capability that allows a client (initially the Salesforce Provider Relations experience) to verify whether a health insurance member currently has active coverage. Given a Member ID, the service retrieves member and coverage information and evaluates eligibility against the member's current coverage effective and termination dates, returning a standardized eligibility decision. This service owns all eligibility business rules. Consuming applications do not evaluate eligibility themselves. servers: - url: http://localhost:8000 description: Local development server tags: - name: Eligibility description: Member eligibility verification operations. paths: /api/v1/eligibility/verify: post: operationId: verifyEligibility tags: - Eligibility summary: Verify member eligibility description: > Evaluates whether the member identified by the supplied Member ID currently has active coverage. The eligibility decision is determined by comparing today's date to the member's coverage effective and termination dates: - If today falls between the effective and termination dates (inclusive), the member is ELIGIBLE. - If today is before the effective date, or after the termination date, the member is INELIGIBLE. - If sufficient coverage information is not available to evaluate eligibility, the outcome is UNABLE_TO_DETERMINE. - If no member exists for the supplied Member ID, the service responds with HTTP 404 instead of a 200 eligibility outcome. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/EligibilityVerificationRequest" examples: verifyByMemberId: summary: Verify eligibility for a member value: memberId: "M100234" responses: "200": description: Eligibility was successfully evaluated for the supplied Member ID. content: application/json: schema: $ref: "#/components/schemas/EligibilityVerificationResponse" examples: eligible: summary: Member has active coverage value: memberId: "M100234" memberName: "Sarah Johnson" eligibilityStatus: "ELIGIBLE" reason: "Active coverage" evaluationDate: "2026-08-02" coverageType: "Medical" effectiveDate: "2026-01-01" terminationDate: "2026-12-31" ineligibleNotYetEffective: summary: Coverage has not started yet value: memberId: "M100455" memberName: "David Chen" eligibilityStatus: "INELIGIBLE" reason: "Coverage Not Yet Effective" evaluationDate: "2026-08-02" coverageType: "Medical" effectiveDate: "2026-09-01" terminationDate: "2027-08-31" ineligibleTerminated: summary: Coverage has ended value: memberId: "M100678" memberName: "Maria Alvarez" eligibilityStatus: "INELIGIBLE" reason: "Coverage Terminated" evaluationDate: "2026-08-02" coverageType: "Dental" effectiveDate: "2025-01-01" terminationDate: "2025-12-31" unableToDetermine: summary: Coverage information is insufficient to decide value: memberId: "M100999" memberName: "James Patel" eligibilityStatus: "UNABLE_TO_DETERMINE" reason: "Coverage information unavailable" evaluationDate: "2026-08-02" coverageType: null effectiveDate: null terminationDate: null "400": description: The request was invalid, such as a missing or empty memberId. content: application/json: schema: $ref: "#/components/schemas/ValidationErrorResponse" examples: missingMemberId: summary: memberId was missing or empty value: code: "INVALID_REQUEST" message: "memberId is required and cannot be empty." timestamp: "2026-08-02T14:32:10Z" correlationId: "1b9d6bcd-bbfd-4b2e-8b19-c9c8b3e6f1a2" "404": description: No member was found for the supplied Member ID. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" examples: memberNotFound: summary: Member ID does not match any known member value: code: "MEMBER_NOT_FOUND" message: "No member found for memberId 'M999999'." timestamp: "2026-08-02T14:33:45Z" correlationId: "2c8e5a3f-2b8b-4e5b-9c9e-1a6d8f0e4b7a" "500": description: An unexpected failure occurred while evaluating eligibility. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" examples: unexpectedFailure: summary: Unhandled service failure value: code: "INTERNAL_SERVER_ERROR" message: "An unexpected error occurred while processing the request." timestamp: "2026-08-02T14:35:12Z" correlationId: "3d7f2b1a-4c5e-4f6a-8b9c-0d1e2f3a4b5c" components: schemas: EligibilityVerificationRequest: type: object description: Request payload used to verify eligibility for a member. required: - memberId additionalProperties: false properties: memberId: type: string minLength: 1 description: Unique identifier for the member, supplied by the provider. examples: - "M100234" EligibilityStatus: type: string description: > Business outcome of an eligibility evaluation. Returned only when the member was found; a member that cannot be found results in an HTTP 404 error response instead of an EligibilityStatus value. enum: - ELIGIBLE - INELIGIBLE - UNABLE_TO_DETERMINE EligibilityVerificationResponse: type: object description: > Result of an eligibility verification for a member that was successfully found. coverageType, effectiveDate, and terminationDate are nullable because they may be unavailable when eligibilityStatus is UNABLE_TO_DETERMINE. required: - memberId - memberName - eligibilityStatus - reason - evaluationDate additionalProperties: false properties: memberId: type: string description: Unique identifier for the member. examples: - "M100234" memberName: type: string description: Full name of the member. examples: - "Sarah Johnson" eligibilityStatus: $ref: "#/components/schemas/EligibilityStatus" reason: type: string description: Human-readable explanation for the eligibility status. examples: - "Active coverage" - "Coverage Not Yet Effective" - "Coverage Terminated" - "Coverage information unavailable" evaluationDate: type: string format: date description: ISO 8601 date on which eligibility was evaluated. examples: - "2026-08-02" coverageType: type: - string - "null" description: > Type of coverage held by the member (e.g. Medical, Dental, Vision). Null when eligibility could not be determined. examples: - "Medical" effectiveDate: type: - string - "null" format: date description: > ISO 8601 date on which the member's coverage becomes effective. Null when eligibility could not be determined. examples: - "2026-01-01" terminationDate: type: - string - "null" format: date description: > ISO 8601 date on which the member's coverage terminates. Null when eligibility could not be determined. examples: - "2026-12-31" ErrorResponse: type: object description: Standard error payload returned for all non-2xx responses. required: - code - message - timestamp - correlationId additionalProperties: false properties: code: type: string description: Machine-readable error code. examples: - "MEMBER_NOT_FOUND" message: type: string description: User-friendly explanation of the error. examples: - "No member found for memberId 'M999999'." timestamp: type: string format: date-time description: ISO 8601 timestamp at which the error occurred. examples: - "2026-08-02T14:33:45Z" correlationId: type: string format: uuid description: Unique identifier for the request, used to correlate logs. examples: - "2c8e5a3f-2b8b-4e5b-9c9e-1a6d8f0e4b7a" ValidationErrorResponse: description: > Error payload returned when the request fails input validation (HTTP 400). Uses the same structure as ErrorResponse; no additional validation-specific fields are defined by the source specifications. allOf: - $ref: "#/components/schemas/ErrorResponse"