Optum Real (Medical) API

openapi: 3.0.0
info:
  title: attachment
  description: attachment
  version: 1.0.0
servers:
- url: https://sandbox-apigw.optum.com
paths:
  /oihub/claim/actions/v1:
    post:
      security:
      - oAuth:
        - read_healthcheck
      parameters:
      - name: providerTaxId
        in: header
        description: Provider Tax ID
        required: true
        schema:
          example: '123456789'
          type: string
      - name: x-optum-consumer-correlation-id
        in: header
        description: unique UUID to track the transaction
        required: false
        schema:
          example: 4d4a8964-e5fa-42dc-a37d-12345789
          type: string
      - name: environment
        in: header
        description: Environment
        required: false
        schema:
          example: sandbox
          type: string
      operationId: claimActions
      summary: Call Claim Actions API
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: array
                    description: List of errors that occurred during Claim Actions
                    items:
                      properties:
                        description:
                          description: Detailed error message
                          type: string
                        code:
                          description: Error code identifying the specific error
                          type: string
                      type: object
                  data:
                    properties:
                      claimSubmissionResponse:
                        $ref: '#/components/schemas/ClaimSubmissionResponse'
                        description: ''
                      claimTicketResponse:
                        $ref: '#/components/schemas/ClaimTicketResponse'
                        description: ''
                    type: object
                type: object
              examples:
                SubmitClaimAttachment:
                  value:
                    data:
                      submitClaimAttachment:
                        attachmentId: 1234-1111-46a9-111-11117Cu_prov_attch_2021-11
                  summary: Submit Attachment Response
        '400':
          description: Bad Request
          content:
            application/json:
              example:
                errors:
                - extensions:
                    classification: ValidationError
                  locations:
                  - line: 1
                    column: 87
                  message: 'Validation error (FieldUndefined@[claimSubmission/transactionId]) : Field
                    ''transactionId'' in type ''ClaimSubmissionResponse'' is undefined'
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                message: Unauthorized
                statusCode: 401
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                message: Internal server error
                statusCode: 500
      tags:
      - Claim Actions
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              required:
              - map
              - operations
              - '0'
              type: object
              properties:
                '0':
                  type: string
                  description: The attachment file to upload
                  format: binary
                map:
                  type: string
                  description: Maps file fields in 'operations' to the file form fields.
                  example: '{"0": ["variables.file"]}'
                operations:
                  type: string
                  description: GraphQL mutation with variables.
                  example: "{\n  \"query\": \"mutation submitClaimAttachment($file: Upload!, $attachmentInput:\
                    \ AttachmentInput!) { submitClaimAttachment(file: $file,attachmentInput: $attachmentInput)\
                    \ { attachmentId } }\",\n  \"variables\":\n    {\n      \"file\": null,\n      \"\
                    attachmentInput\":\n        {\n          \"documentTypeCode\": \"M1\",\n         \
                    \ \"documentName\": \"ACN-AttachmentControlNumber\",\n          \"claimReceiptLocatorNumber\"\
                    : \"9162500198765\",\n          \"claimNumber\": \"FE12345678\",\n          \"editCode\"\
                    : \"EDIT123\",\n          \"expiryDate\": \"2025-12-31\",\n          \"claimActionIdentifier\"\
                    : \"XXXX-AAAA-BBBB-CCCCC\",\n          \"ticketNumber\": \"PIQ-123456\",\n       \
                    \   \"payerId\": \"87726\"\n        }\n    }\n}\n"
components:
  schemas:
    AttachmentInput:
      type: object
      description: Represents the input for submitting a claim attachment.
      properties:
        documentTypeCode:
          type: string
          description: 'edi837 PWK01 report type code: M1 (Medical Recs), CK (Consent Form) etc'
          example: M1
        documentName:
          type: string
          description: document name or attachment control number
          example: attachment-control-number
        claimReceiptLocatorNumber:
          type: string
          description: claim FLN/claimReceiptLocatorNumber from claim inquiry
          example: '9162500112345'
        claimNumber:
          type: string
          description: claim ICN/claimNumber from claim inquiry
          example: FE12345678
        editCode:
          type: string
          description: edit code applied to the claim
          example: EDIT123
        expiryDate:
          type: string
          description: expiry date
          example: '2025-12-31'
        claimActionIdentifier:
          type: string
          description: claimActionIdentifier key from claim inquiry (Required when a new ticket is being
            created)
          example: fd00e249-fb5f-4601-a392-1ee032df61d0-1756148161470
        ticketNumber:
          type: string
          description: ticket number (Required when updating an existing ticket)
          example: PIQ-12345678
        payerId:
          type: string
          description: payer ID
          example: '00123'
      required:
      - payerId
    ClaimSubmissionInput:
      type: object
      description: Input data for the Claim Actions operation
      properties:
        x12RequestData:
          type: string
          description: EDI837 X12 formatted claim data
          example: ISA*00*          *00*          *ZZ*SENDER ID       *ZZ*RECEIVER ID    *231012*1200*U*00501*000000001*0*P*:~
            GS*HP*SENDERAPP*RECEIVERAPP*20231012*1200*000000001*X*005010X222A1~ ST*837*0001*005010X222A1~
            [... BHT, HL, PRV, N1, N3, N4, CLM, CAS, PLB, HI, DMG, and other 837 segments...] SE*32*0001~
            GE*1*000000001~ IEA*1*000000001~
        payerId:
          type: string
          description: Payer ID
          example: P123
      required:
      - payerId
      - x12RequestData
    ClaimSubmissionResponse:
      type: object
      description: Response model for Claim Submission operations
      properties:
        transactionId:
          type: string
          description: unique transactionID created by the payer for the claim submission request
          example: '8841512345678901'
        x12ResponseData:
          type: string
          description: EDI x12-999 acknowledgement for the claim
          example: ISA*00*          *00*          *ZZ*87726          *ZZ*B00099999805   *250911*1927*^*00501*000000000*0*P*:~GS*FA*87726_B2B*B00099999805*20250911*1927*0*X*005010X231A1~ST*999*0001*005010X231A1~AK1*HC*1*005010X222A1~AK2*837*0001*005010X222A1~IK5*A~AK9*A*1*1*1~SE*6*0001~GE*1*0~IEA*1*000000000~
        responseType:
          type: string
          description: value describing x12ResponseData type
          example: '837999'
        x12Response277CA:
          type: string
          description: EDI x12-277 claim acknowledgement
          example: ISA*00*          *00*          *ZZ*87726          *ZZ*B00099999805   *250911*1927*^*00501*000000000*0*P*:~GS*HN*87726_B2B*B00099999805*20250911*192706*0*X*005010X214~ST*277*0001*005010X214~BHT*0085*08*AB829992000298311665.1*20250911*192706*TH~HL*1**20*1~NM1*AY*2*INGENIXENS*****46*87726~TRN*1*AB829992000298311665.1~DTP*050*D8*20250911~DTP*009*D8*20250911~HL*2*1*21*1~NM1*41*2*B00099999805*****46*ENS~TRN*2*1~STC*A1:19*20250911*WQ*170~QTY*90*1~AMT*YU*170~HL*3*2*19*1~NM1*85*2*COVENANT
            MULTISPECIALTY GROUP, LLC*****XX*1942376918~TRN*1*1~QTY*QA*1~AMT*YU*170~HL*4*3*PT~NM1*QC*1*BROWN*ZIA****MI*963997463~TRN*2*CMG.126559~STC*A3:21*20250911*U*170********Prior
            auth validation could not be completed due to service failure~STC*A1:19*20250911*WQ*170********[BTH-V106
            LOB Filters applied, ace was not called-Bypassing claim edits]~REF*D9*P3QAVH0FGU03H4~DTP*472*RD8*20241008-20241008~SE*26*0001~GE*1*0~IEA*1*000000000~
        message:
          type: string
          description: message describing the final outcome of the claim submission process
          example: Claim submitted successfully. Refer 277CA for validation outcomes.
        statusCode:
          type: string
          description: status code for the submission process
          example: '000'
    ClaimTicketInput:
      type: object
      description: Input for submitting a claim ticket (Pend, Recon, Appeal)
      properties:
        lineDetails:
          type: array
          items:
            $ref: '#/components/schemas/LineDetailInput'
          description: selection of lineKeys from claim inquiry, to be submitted for rework
        claimActionIdentifier:
          type: string
          description: claimActionIdentifier key from claim inquiry (required for new ticket creation)
          example: fd00e249-fb5f-4601-a392-1ee032df61d0-1756148161470
        ticketType:
          type: string
          description: 'ticket (rework) type: PEND, RECON or APPEAL'
          example: RECON
        ticketAction:
          type: string
          description: 'allowable action for the ticket (from claim inquiry): Create, Resubmit/Update'
          example: Create
        ticketNumber:
          type: string
          description: ticket number (required if updating an existing ticket)
          example: PIQ-12345678
        providerComments:
          type: string
          description: provider comments elaborating claim ticket submission
          example: Reconsideration request
        hasAttachment:
          type: boolean
          description: 'boolean flag: provider intent to submit attachments substantiating the request'
          example: 'true'
        isAttachmentUploaded:
          type: boolean
          description: 'boolean flag: is/are attachments uploaded using submitClaimAttachment action'
          example: 'true'
        operator:
          $ref: '#/components/schemas/OperatorInput'
          description: details of the person submitting rework request
        claimAmountOwed:
          type: string
          description: expected claim amount owed by payer for reimbursement
          example: '1000.00'
        requestReconsiderationReason:
          type: string
          description: reason for submitting a Recon (select a value from claim inquiry response)
          example: INCORRECT_PAYMENT
        placeOfServiceState:
          type: string
          description: place of service state - required for Appeal submission
          example: MN
        isAppealOnBehalfOfMember:
          type: boolean
          description: 'boolean flag: to check if Appeal is submitted on behalf of the member'
          example: 'false'
        isExternalReviewAppeal:
          type: boolean
          description: 'boolean flag: external review Appeal'
          example: 'false'
        payerId:
          type: string
          description: payer ID
          example: '00123'
      required:
      - payerId
    ClaimTicketResponse:
      type: object
      description: Claim Ticket Response
      properties:
        ticketNumber:
          type: string
          description: payer generated unique identifier for the rework ticket
          example: PIQ-12345678
        ticketStatus:
          type: string
          description: status of the rework ticket
          example: Under Review
        referenceId:
          type: string
          description: reference ID for the ticket submission (internal use)
          example: REF-987654321
        preSignedUrl:
          type: string
          description: pre-signed URL link to upload bulk documents (as zip file) related to the rework
            ticket
          example: https://AWS-pre-signed-url
    LineDetailInput:
      type: object
      description: Details for a single claim line
      properties:
        lineKey:
          type: string
          description: unique line identifier for the service line from the claimStatusInquiry api
          example: lrlspg8hgksv971756148162162
        lineAmountOwed:
          type: string
          description: expected line amount owed by payer for reimbursement
          example: '450.00'
    OperatorInput:
      type: object
      description: Operator details for claim ticket
      properties:
        operatorEmailId:
          type: string
          description: operator email Id
          example: john.doe@gmail.com
        operatorFirstName:
          type: string
          description: operator first name
          example: John
        operatorLastName:
          type: string
          description: operator last name
          example: Doe
        operatorPhoneNumber:
          type: string
          description: operator phone number
          example: 512-888-9999
        operatorCity:
          type: string
          description: operator city
          example: Minneapolis
        operatorState:
          type: string
          description: operator state
          example: MN
        operatorStreet:
          type: string
          description: operator street address
          example: 1555 lex ave
        operatorZip:
          type: string
          description: operator zip code
          example: '12345'
  securitySchemes:
    oAuth:
      type: oauth2
      description: This API uses OAuth 2 with the client_credentials grant flow.
      flows:
        clientCredentials:
          tokenUrl: /apip/auth/sntl/v1/token
          scopes:
            read_txn: read transactions
            create_txn: submit a new transaction request
            read_coveragediscovery: read coverage discovery tasks
            create_coveragediscovery: submit a new coverage discovery task
            read_healthcheck: check the status of the system