Optum Eligibility Transactions API

openapi: 3.2.0
info:
  title: Enhanced Eligibility Eligibility Transactions API
  description: 'Enhanced Eligibility provides real-time eligibility verification for medical benefit inquiries and optional Coverage Discovery workflows when additional coverage needs to be researched asynchronously.


    Timing guidance:

    - Real-Time Eligibility is synchronous, but payer and clearinghouse response time dominate the end-to-end latency.

    - The OI Enterprise gateway times out at 110 seconds for this API.

    - Request deduplication is customer-configurable and determines whether a request is sent to the clearinghouse or short-circuited by replaying a prior transaction response.

    - RTCOB and Coverage Insight also use a separate non-configurable 72-hour request cache. When that cache is hit, the path is marked as skipped instead of creating a new downstream submission.

    - Coverage Discovery is asynchronous because some paths involve chained clearinghouse work and additional connected workflow dependencies.

    - Most non-Coverage-Insight discovery paths are near real time relative to traditional discovery workflows.

    - Customers with strict turnaround sensitivity should evaluate Coverage Insight enrollment carefully.

    - Coverage Discovery paths and add-ons are enabled per customer and are not included automatically.


    Primary integration patterns:

    1. Submit a real-time eligibility request as normalized JSON or as a JSON request body with `x12` set to the X12 270 payload, and receive a normalized JSON response.

    2. If enrolled in Coverage Discovery, inspect the real-time response `link` header for related discovery task resources when discovery is automatically triggered from the real-time request/response.

    3. For advanced use cases, submit Coverage Discovery requests directly when you already possess a processed canonical eligibility request and, when needed, a processed eligibility response, and want asynchronous follow-up processing using a callback URL or by polling the discovery task resource.

    4. When using direct discovery, the X12 workflow is often easier than the canonical JSON workflow because it accepts the processed `x12-270` and `x12-271` rather than requiring mapping into both canonical models.

    '
  version: v0.2.0
servers:
- url: https://sandbox-apigw.optum.com
  description: Sandbox server (uses test data)
- url: https://apigw.optum.com
  description: Production server (uses live data)
tags:
- name: Eligibility Transactions
  description: 'Retrieve previously processed real-time eligibility transactions. Use these endpoints to list transactions, filter by status, date range, patient details, or correlation metadata, and fetch a single transaction record by id for audit, troubleshooting, and downstream workflows.

    '
paths:
  /rcm/eligibility/v1/transactions:
    get:
      tags:
      - Eligibility Transactions
      summary: Find all eligibility transactions
      security:
      - oAuth:
        - read_txn
      description: 'Returns matching eligibility transactions. You can use the query parameters listed below to filter the results. If no query parameters are provided, all eligibility transactions will be returned in paginated form.

        '
      parameters:
      - $ref: '#/components/parameters/header-correlation-id'
      - $ref: '#/components/parameters/query-status'
      - $ref: '#/components/parameters/query-correlationid'
      - $ref: '#/components/parameters/query-patientFirstName'
      - $ref: '#/components/parameters/query-patientLastName'
      - $ref: '#/components/parameters/query-patientAccountNumber'
      - $ref: '#/components/parameters/query-medicalRecordNumber'
      - $ref: '#/components/parameters/query-memberId'
      - $ref: '#/components/parameters/query-patientDateOfBirth'
      - $ref: '#/components/parameters/query-npi'
      - $ref: '#/components/parameters/query-payerId'
      - $ref: '#/components/parameters/query-start-date-time'
      - $ref: '#/components/parameters/query-end-date-time'
      - $ref: '#/components/parameters/query-sort-txns'
      - $ref: '#/components/parameters/query-offset'
      - $ref: '#/components/parameters/query-limit'
      - $ref: '#/components/parameters/query-return-total-count'
      responses:
        '200':
          description: OK
          headers:
            x-optum-tenant-id:
              $ref: '#/components/headers/tenantid'
            x-optum-correlation-id:
              $ref: '#/components/headers/correlationid'
            x-optum-trace-id:
              $ref: '#/components/headers/traceid'
            link:
              $ref: '#/components/headers/link'
            x-total-count:
              $ref: '#/components/headers/total-count'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/PermissionDeniedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        5XX:
          $ref: '#/components/responses/UnexpectedError'
  /rcm/eligibility/v1/transactions/{id}:
    get:
      tags:
      - Eligibility Transactions
      summary: Find eligibility transaction by ID
      security:
      - oAuth:
        - read_txn
      description: Returns an individual transaction with the corresponding ID, if found.
      parameters:
      - $ref: '#/components/parameters/header-correlation-id'
      - $ref: '#/components/parameters/path-txn-id'
      responses:
        '200':
          description: OK
          headers:
            x-optum-tenant-id:
              $ref: '#/components/headers/tenantid'
            x-optum-correlation-id:
              $ref: '#/components/headers/correlationid'
            x-optum-trace-id:
              $ref: '#/components/headers/traceid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/PermissionDeniedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
        5XX:
          $ref: '#/components/responses/UnexpectedError'
components:
  headers:
    correlationid:
      schema:
        type: string
        example: 9fb77454-8c58-4345-aa50-43f133e06d20
      description: A unique identifier value that is attached to the response that allow reference to the original request. Differs from `x-optum-trace-id` as the correlation-id is stored within the datastore for future queryability.
    total-count:
      schema:
        type: string
        example: '1440'
      description: The total number of records associated with the query. For example, with the query `?correlationId=123456579`, `x-total-count` returns the total amount of records associated with the given correlationId.
    link:
      schema:
        type: string
        example: </?limit=30&offset=2>; rel="next"
      description: RFC 8288-style pagination link header used by list endpoints such as `GET /transactions` and `GET /coverage-discovery`. This header is separate from the related-task `link` header used by real-time eligibility responses.
    traceid:
      schema:
        type: string
        example: 9fb77454-8c58-4345-aa50-43f133e06d20
      description: A unique identifier value that is attached to the response that allow reference to the original request.
    tenantid:
      schema:
        type: string
        example: 9fb77454-8c58-4345-aa50-43f133e06d20
      description: The unique ID of the tenant that invoking user belongs to. Used to enforce data tenancy.
    subtenantid:
      schema:
        type: string
        example: 5e2f9f4f-6f1d-4b37-92b5-6c5a9d1f8a21
      description: (Optional) Identifies an Optum-assigned sub-tenant configuration for your organization. Include this header only when Optum has provided a value for a specific enabled customer configuration. Clients must not generate or infer this value.
  parameters:
    query-payerId:
      in: query
      name: payerId
      schema:
        type: string
        example: '12345'
      description: (Optional) Payer ID (CHC ID).
    path-txn-id:
      in: path
      name: id
      description: The unique ID of the target transaction
      required: true
      schema:
        type: string
        example: 36743735-3303-4d9d-9f21-20dd5f6d7ab2
    query-start-date-time:
      in: query
      name: startDateTime
      required: false
      schema:
        type: string
        example: '2017-07-21T17:32:28Z'
      description: (Optional) The start date for the report. Start date must be before the end date
    query-patientLastName:
      in: query
      name: patientLastName
      schema:
        type: string
        example: Doe
      description: (Optional) Patient's last name.
    query-end-date-time:
      in: query
      name: endDateTime
      required: false
      schema:
        type: string
        example: '2017-09-21T17:32:28Z'
      description: (Optional) The end date for the report. Must occur after the provided start date
    query-npi:
      in: query
      name: npi
      schema:
        type: string
        example: '1234567893'
      description: (Optional) NPI of the primary care provider.
    query-return-total-count:
      in: query
      name: returnTotalCount
      schema:
        type:
        - boolean
        - 'null'
        example: true
      description: (Optional) Whether or not to return the total number of records matching the supplied query parameters under the x-total-number HTTP response header. Defaults to false
    query-offset:
      in: query
      name: offset
      required: false
      schema:
        type: integer
      description: (Optional) Pagination. The offset number to retrieve, which is determined by the limit. For example,if limit is 30 and offset is 0, then the response data will include records 1~30; If offset is 30 and limit is 30 then the response data will include records 30~59.
    query-patientAccountNumber:
      in: query
      name: patientAccountNumber
      schema:
        type: string
        example: '38300904'
      description: (Optional) Patient's account number.
    query-memberId:
      in: query
      name: memberId
      schema:
        type: string
        example: XKY933M53442
      description: (Optional) Member Id.
    query-status:
      in: query
      name: status
      required: false
      explode: false
      schema:
        type: array
        items:
          enum:
          - eligible
          - ineligible
          - payer_unavailable
          - payer_not_in_system
          - processing_error
          - patient_unknown
      description: (Optional) The status of the eligibility transaction. Valid values match `Transaction.status.value`.
    query-correlationid:
      in: query
      name: correlationId
      schema:
        type: string
        example: 9fb77454-8c58-4345-aa50-43f133e06d20
      description: (Optional) The correlationId associated with the original request.
    query-patientDateOfBirth:
      in: query
      name: patientDateOfBirth
      schema:
        type: string
        example: '1995-01-15'
      description: (Optional) Patient's date of birth.
    query-patientFirstName:
      in: query
      name: patientFirstName
      schema:
        type: string
        example: Jane
      description: (Optional) Patient's first name.
    query-sort-txns:
      in: query
      name: sort
      required: false
      explode: false
      schema:
        type: array
        items:
          enum:
          - processedDate
          - -processedDate
        example:
        - -processedDate
      description: (Optional) The property to order the results of the report by. Defaults to '-processedDate', negative sign is 'desc'
    header-correlation-id:
      in: header
      name: x-optum-correlation-id
      schema:
        type: string
        example: 9fb77454-8c58-4345-aa50-43f133e06d20
      required: false
      description: (Optional) A unique identifier value that is attached to the response that allow reference to the original request. Differs from `x-optum-trace-id` as the correlation-id is stored within the datastore for future queryability.
    query-limit:
      in: query
      name: limit
      schema:
        type:
        - integer
        - 'null'
        minimum: 1
        maximum: 100
        example: 30
      description: (Optional) Number of transactions to return per page. Must be greater than 0 and less than or equal to 100. Defaults to 30.
    query-medicalRecordNumber:
      in: query
      name: medicalRecordNumber
      schema:
        type: string
        example: '194570'
      description: (Optional) Medical Record Number.
  responses:
    ForbiddenError:
      description: Forbidden.
      headers:
        x-optum-tenant-id:
          $ref: '#/components/headers/tenantid'
        x-optum-subtenant-id:
          $ref: '#/components/headers/subtenantid'
        x-optum-correlation-id:
          $ref: '#/components/headers/correlationid'
        x-optum-trace-id:
          $ref: '#/components/headers/traceid'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
          - invalid tenant id
    UnexpectedError:
      description: Unexpected error.
      headers:
        x-optum-tenant-id:
          $ref: '#/components/headers/tenantid'
        x-optum-subtenant-id:
          $ref: '#/components/headers/subtenantid'
        x-optum-correlation-id:
          $ref: '#/components/headers/correlationid'
        x-optum-trace-id:
          $ref: '#/components/headers/traceid'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntityError:
      description: Unprocessable Entity.
      headers:
        x-optum-tenant-id:
          $ref: '#/components/headers/tenantid'
        x-optum-subtenant-id:
          $ref: '#/components/headers/subtenantid'
        x-optum-correlation-id:
          $ref: '#/components/headers/correlationid'
        x-optum-trace-id:
          $ref: '#/components/headers/traceid'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
          - Unprocessable Entity - Unable to deserialize record
    PermissionDeniedError:
      description: Unauthorized.
      headers:
        x-optum-subtenant-id:
          $ref: '#/components/headers/subtenantid'
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: invalid_product
              error_description:
                type: string
                example: Permission Denied.
              traceId:
                type: string
                example: 942537e6-d544-ed7c-469b-a27efc4a6cff
    NotFoundError:
      description: Not found.
      headers:
        x-optum-tenant-id:
          $ref: '#/components/headers/tenantid'
        x-optum-subtenant-id:
          $ref: '#/components/headers/subtenantid'
        x-optum-correlation-id:
          $ref: '#/components/headers/correlationid'
        x-optum-trace-id:
          $ref: '#/components/headers/traceid'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
          - Not Found - record not found
  schemas:
    Error:
      description: The base object model for errors returned from the workflow
      type: array
      items:
        type: string
        example: Internal - An unknown error occurred
    Transaction:
      type: object
      description: The base object model for the `/transactions` endpoints and the canonical model for Enhanced Eligibility
      properties:
        id:
          type: string
          example: 9fb77454-8c58-4345-aa50-43f133e06d20
          description: The unique ID of the transaction
        sourceId:
          type: string
          example: 9fb77454-8c58-4345-aa50-43f133e06d20
          description: The id of the transaction that spawned this record. If empty, this transaction has no parent.
        sourceType:
          type: string
          enum:
          - new
          - historical
          - duplicate
          - autosubmit
          example: new
          description: How the transaction was created. `new` means the transaction was submitted through the Real-Time Eligibility flow. `duplicate` means customer-configured deduplication found a prior matching request, skipped clearinghouse submission, and returned the previous response. `autosubmit` means the transaction was generated by Coverage Discovery path execution. `historical` means the record originated from historical retrieval rather than a newly created request.
        correlationId:
          type: string
          description: An ID provided by the consumer at the time of transaction processing
        processedDate:
          type: string
          example: '2017-07-21T17:32:28Z'
          description: The time the transaction was processed by the system
        status:
          type: object
          description: The outcome of the transaction
          properties:
            value:
              type: string
              enum:
              - eligible
              - ineligible
              - payer_unavailable
              - payer_not_in_system
              - processing_error
              - patient_unknown
              example: eligible
            description:
              type: string
              example: Eligible with insurance
              description: A human readable representation of the 'value' field.
        errors:
          type: array
          items:
            type: string
          description: A list of errors that occurred during process
        benefits:
          type: array
          items:
            type: object
            example:
              service: Urgent Care
              networkClass: inNetwork
              benefitType: family
              name: copay
              type: string
              scope: common
              benefitQualifier: DY
            properties:
              service:
                type: string
                example: Urgent Care
                description: Text description of service type code
              networkClass:
                type: string
                enum:
                - inNetwork
                - outNetwork
                example: inNetwork
                description: Whether the benefit conditions apply to 'in' or 'out' of network
              benefitType:
                type: string
                enum:
                - individual
                - family
                example: individual
                description: Benefit type maps to either individual or family
              name:
                type: string
                example: copay
                description: Benefit field name
              value:
                type: string
                description: Benefit field value
              type:
                type: string
                enum:
                - string
                - date
                - number
                - percent
                - monetary
                - phone
                description: Benefit field data type
              scope:
                type: string
                enum:
                - common
                - service
                example: common
                description: Benefit field relates either to a service type or is common (not related to a service type)
              insuranceType:
                type: string
                enum:
                - AllPayers
                - Medicaid
                - Medicare
                example: AllPayers
                description: 'Insurance classification: Medicare, Medicaid, or AllPayers'
              benefitQualifier:
                type: string
                example: DY (value of the benefit is in days)
                description: Benefit field code identifying type or source
          description: Detailed benefit information for each service returned by the payer
        patient:
          type: object
          properties:
            dateOfBirth:
              type: string
              format: date
              example: '1880-01-02'
            dateOfDeath:
              type: string
              format: date
              example: '1880-01-02'
            eligibilityCategory:
              type: string
              description: Expresses the eligibility category of the member to properly administer health benefits and coverage (from Department of Defense)
            firstName:
              type: string
              example: John
            gender:
              type: string
              example: M
            lastName:
              type: string
              example: Doe
            memberId:
              type: string
              example: '4784784'
            middleName:
              type: string
              example: Dave
            militaryPersonnel:
              type: boolean
              example: false
            mrn:
              type: string
              example: '657883'
            phone:
              type: string
              example: '1234567890'
            relationship:
              type: string
              example: child
            ssn:
              type: string
              example: '555443333'
            suffix:
              type: string
              example: Mr.
            agencyClaimNumber:
              type: string
              example: WC1234567
            address:
              type: object
              properties:
                lines:
                  type: array
                  items:
                    type: string
                    example:
                    - 1234 Main Street
                city:
                  type: string
                  example: Dallas
                county:
                  type: string
                  example: Harris County
                state:
                  type: string
                  example: TX
                subdivisionCode:
                  type: string
                  example: TX
                zip:
                  type: string
                  example: '77001'
          description: The patient details captured on the eligibility response
        payer:
          type: object
          properties:
            aaaSource:
              type: string
              example: Additional Text From Payer
            certificationNumber:
              type: string
              example: '9999999999'
              description: 10 digits
            contactExtension:
              type: string
              example: '7657'
            contactName:
              type: string
              example: Contact Example
            description:
              type: string
              example: HEALTHFIRST-MANAGED MEDICAID
            email:
              type: string
              example: payer.email@email.com
            fax:
              type: string
              example: '8009999999'
            name:
              type: string
              example: HEALTHFIRST
            phone:
              type: string
              example: '8009252272'
            thirdPartyAdminstrator:
              type: object
              properties:
                name:
                  type: string
                  example: BCBSM TPA
                phone:
                  type: string
                  example: '8009252272'
            url:
              type: string
              example: payerwebsite.com
            address:
              type: object
              properties:
                lines:
                  type: array
                  items:
                    type: string
                    example:
                    - 1234 Main Street
                city:
                  type: string
                  example: Dallas
                county:
                  type: string
                  example: Harris County
                state:
                  type: string
                  example: TX
                subdivisionCode:
                  type: string
                  example: TX
                zip:
                  type: string
                  example: '77001'
            chcId:
              type: string
              example: 09876z5y-43x2-1w09-v8u7-tr6543s210qp
          description: Represents data about the payer that is on record for the eligibility request
        plan:
          type: object
          description: Detailed information about the Subscriber’s plan, group, and policy
          properties:
            beginDate:
              type: string
              format: date
              example: '2008-01-02'
            dateOfDecision:
              type: string
              format: date
              example: '2008-01-02'
            endDate:
              type: string
              format: date
              example: '2008-01-02'
            benefitFirstBilledDate:
              type: string
              format: date
              example: '2008-01-02'
            groupOrPolicyNumber:
              type: string
              example: '8888888888'
            insuranceType:
              type: string
              example: Health Maintenance Organization (HMO)
            lastBilledDate:
              type: string
              format: date
              example: '2008-01-02'
            medicalAssistanceCategory:
              type: string
              example: '999'
            otherAdditionalCoverageQualifier:
              type: string
              example: PHARMACY
            otherCoverage:
              type: string
              example: FIRST HEALTH LIFE & HEALTH INSURANCE COMPANY
            otherProductDescription:
              type: string
              example: HealthPlan
            planBeginDate:
              type: string
              format: date
              example: '2008-01-02'
            planCoverageDescription:
              type: string
              example: HEALTHFIRST-MANAGED MEDICAID
            description:
              type: string
              example: Plan Description
            name:
              type: string
              example: Cigna PPO
            number:
              type: string
              example: S5768 135
            ppo:
              type: string
              example: Dr. T Test
              description: Preferred provider organization
            productDescription:
              type: string
              example: HEALTHFIRST-MANAGED MEDICAID
            dependentMemberID:
              type: string
              example: M20220314
            familyUnitNumber:
              type: string
              example: '01'
            identificationCardSerialNumber:
              type: string
              example: ICSN0001
            insurancePolicyNumber:
              type: string
              example: ICSN0001
            subscriberPremiumPaidEndDate:
              type: string
              format: date
              example: '2008-01-01'
            aca:
              type: object
              properties:
                hixMessage:
                  type: string
                  example: HIX Grace Period
                periodStart:
                  type: string
                  format: date
                  example: '2008-01-01'
                periodEnd:
                  type: string
                  format: date
                  example: '2008-01-01'
            case:
              type: object
              description: Used to clarify plan level details
              properties:
                type:
                  type: string
                  description: Reference Information as defined for a Reference Identification Qualifier
                description:
                  type: string
                  example: Free form text
            gatewayProvider:
              type: object
              properties:
                name:
                  type: string
                  example: Gateway Provider A
                address:
                  type: object
                  properties:
                    lines:
                      type: array
                      items:
                        type: string
                        example:
                        - 1234 Main Street
                    city:
                      type: string
                      example: Dallas
                    county:
                      type: string
                      example: Harris County
                    state:
                      type: string
                      example: TX
                    subdivisionCode:
                      type: string
                      example: TX
                    zip:
                      type: string
                      example: '77001'
            group:
              type: object
              properties:
                name:
                  type: string
                  example: FLORIDA MEDICAID
                number:
                  type: string
                  example: FLMCD000
                policyName:
                  type: string
                  example: FLMPOL256
            hmo:
              type: object
              description: Health maintenance organization details
              properties:
                name:
                  type: string
                  example: Cigna HMO
                planNumber:
                  type: string
                  example: CIG991122
            hra:
              type: object
              description: Health reimbursement arrangement details
              properties:
                balance:
                  type: string
                  example: '90'
                employerPledge:
                  type: string
                  example: '500'
                paid:
                  type: string
                  example: '400'
                priorCarryover:
                  type: string
                  example: '100'
            hsa:
              type: object
              description: Health savings account details
              properties:
                balance:
                  type: string
                  example: '500'
                employerPledge:
                  type: string
                  example: '800'
                paid:
                  type: string
                  example: '200'
                priorCarryover:
                  type: string
                  example: '0'
            ipa:
              type: object
              description: Individual practice association details
              properties:
                name:
                  type: string
                  example: AETNA CHOICE POS II
                contactName:
                  type: string
                  example: MERITAIN HEALTH CUSTOMER SERVICE
                id:
                  type: string
                  example: IPAID
                phone:
                  type: string
                  example: '8009252272'
                address:
                  type: object
                  properties:
                    lines:
                      type: array
                      items:
                        type: string
                        example:
                        - 1234 Main Street
                    city:
                      type: string
                      example: Dallas
                    county:
                      type: string
                      example: Harris County
                    state:
                      type: string
                      example: TX
                    subdivisionCode:
                      type: string
                      example: TX
                    zip:
                      type: string
                      example: '77001'
            otherPayer:
              type: object
              description: Additional Payer Associated with Patient
              properties:
                groupNumber:
                  type: string
                  example: CIG998877
                policyNumber:
                  type: string
                  example: CIGNA PPO
            planNetworkIdentification

# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/optum/refs/heads/main/openapi/optum-eligibility-transactions-api-openapi.yml