openapi: 3.2.0
info:
  title: Payer List API V1 Payers API
  version: 1.0.0
  description: PayerList API empowers providers to programmatically access and integrate accurate, up-to-date payer list data into your systems to eliminate manual processes and enable smarter transaction workflows.
servers:
- url: https://sandbox-apigw.optum.com
  description: Sandbox
security:
- bearerAuth: []
tags:
- name: Payers
paths:
  /medicalnetwork/payerlist/v1/payers:
    get:
      tags:
      - Payers
      summary: Get payers
      operationId: getPayers
      parameters:
      - name: system
        in: query
        required: true
        schema:
          type: string
        description: 'Source system. Example values from collection: exch, imn, IMN, EXCH, IEDI, RPA, DENTAL.'
      - name: transactionType
        in: query
        required: false
        schema:
          type: string
        description: Transaction type filter.
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
        description: Maximum number of records to return.
      - name: lastUpdatedAfter
        in: query
        required: false
        schema:
          type: string
        description: 'Return records updated after this date. Format: YYYY-MM-DD.'
      - name: exchangeInstClaimPayerId
        in: query
        required: false
        schema:
          type: string
        description: Exchange institutional claim payer ID.
      - name: exchangeProfClaimPayerId
        in: query
        required: false
        schema:
          type: string
        description: Exchange professional claim payer ID.
      - name: iediInstClaimPayerId
        in: query
        required: false
        schema:
          type: string
        description: IEDI institutional claim payer ID.
      - name: iediProfClaimPayerId
        in: query
        required: false
        schema:
          type: string
        description: IEDI professional claim payer ID.
      - name: status
        in: query
        required: false
        schema:
          type: string
        description: Payer status filter.
      - name: payerNotes
        in: query
        required: false
        schema:
          type: string
        description: Payer notes filter.
      - name: enrollmentNotes
        in: query
        required: false
        schema:
          type: string
        description: Enrollment notes filter.
      - name: claimSubmissionRequiredThroughExchange
        in: query
        required: false
        schema:
          type: string
        description: Indicates whether claim submission is required through exchange.
      - name: additionalLCHCPayerId
        in: query
        required: false
        schema:
          type: string
        description: Additional LCHC payer ID.
      - name: activationDate
        in: query
        required: false
        schema:
          type: string
        description: 'Activation date. Format: YYYY-MM-DD.'
      - name: standInIndicator
        in: query
        required: false
        schema:
          type: string
        description: Stand-in indicator.
      - name: serviceRestored
        in: query
        required: false
        schema:
          type: string
        description: Service restored indicator.
      - name: payerType
        in: query
        required: false
        schema:
          type: string
        description: Payer type.
      - name: payerPlanName
        in: query
        required: false
        schema:
          type: string
        description: Payer plan name.
      - name: stateDoingBusiness
        in: query
        required: false
        schema:
          type: string
        description: State where payer does business.
      - name: chiPayer
        in: query
        required: false
        schema:
          type: boolean
        description: Indicates whether this is a CHI payer.
      - name: payerId
        in: query
        required: false
        schema:
          type: string
        description: Payer ID.
      - name: additionalPayerIDs
        in: query
        required: false
        schema:
          type: string
        description: Additional payer IDs. Repeat parameter or comma-separated value may be accepted depending on implementation.
      - name: X-CHC-PayerList-SubmitterId
        in: header
        required: false
        schema:
          type: string
        description: Optional submitter ID header shown in the source collection.
      responses:
        '200':
          description: Successful payer list response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayerListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    PayerListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Payer'
        page:
          type: integer
        pageSize:
          type: integer
        totalCount:
          type: integer
      additionalProperties: true
      description: Payer list response placeholder. Exact response schema was not provided in the source collection.
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: string
    Payer:
      type: object
      properties:
        payerId:
          type: string
        payerPlanName:
          type: string
        status:
          type: string
        payerType:
          type: string
        stateDoingBusiness:
          type: string
        transactionType:
          type: string
      additionalProperties: true
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT