openapi: 3.0.0
info:
  title: Claim ACTIONS api
  description: Claim Actions api
  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:
                SubmitClaimWithPreCheck:
                  value:
                    data:
                      claimSubmission:
                        transactionId: '8841512345678901'
                        x12ResponseData: 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: '837999'
                        x12Response277CA: 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: Claim submitted successfully. Refer 277CA for validation outcomes.
                        statusCode: '000'
                  summary: Claim Submission With Pre-Check Response
                SubmitClaimTicket:
                  value:
                    data:
                      submitClaimTicket:
                        ticketNumber: PIQ-12345678
                        ticketStatus: Under Review
                        preSignedUrl: https://AWS-pre-signed-url
                  summary: Claim Ticket Submission Response
                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:
          application/json:
            schema:
              type: object
              properties:
                query:
                  description: GraphQL query or mutation
                  example: 'mutation SubmitClaimWithPreCheck($input: ClaimSubmissionInput!) { claimSubmission(input:
                    $input) { transactionId x12ResponseData responseType x12Response277CA message statusCode
                    } }

                    '
                  type: string
                variables:
                  properties:
                    input:
                      $ref: '#/components/schemas/ClaimSubmissionInput'
                      description: ''
                    claimTicketInput:
                      $ref: '#/components/schemas/ClaimTicketInput'
                      description: ''
                  type: object
                  description: Variables for the GraphQL query
                operationName:
                  description: Name of the GraphQL operation to execute (optional)
                  type: string
              required:
              - query
              - variables
              description: GraphQL queries to fetch Claims information
            examples:
              SubmitClaim:
                value:
                  mutation: 'mutation claimSubmission($input: ClaimSubmissionInput!) { claimSubmission(input:
                    $input) { transactionId x12ResponseData responseType x12Response277CA message statusCode
                    } }'
                  variables:
                    input:
                      x12RequestData: ISA*00*          *00*          *ZZ*BRT219996150   *ZZ*87726          *250625*0826*^*00501*888251331*1*P*:~GS*HC*BRT219996150*87726*20250625*0826*525620842*X*005010X222A1~ST*837*101770887*005010X222A1~BHT*0019*00*25062588055*20250625*0826*CH~NM1*41*2*RTS*****46*223832302~PER*IC*LORAINE
                        GOETSCH*TE*7328735133~NM1*40*2*UNITED HEALTHCARE 1500*****46*87726~HL*1**20*1~NM1*85*2*MERCY
                        GILBERT MEDICAL CENTER*****XX*1992735088~N3*3555 S VAL VISTA DR~N4*EDWARDSVILLE*IL*620253776~REF*EI*352263845~PER*IC*DAVIS,
                        SARAH*TE*6185094866*FX*6185094866~HL*2*1*22*0~SBR*P*18*******ZZ~NM1*IL*1*LNLAMDA*FNTIMDA****MI*990313643~N3*201
                        MONTGOMERY STREET*APT 539~N4*JERSEY CITY*NJ*07302~DMG*D8*19800605*F~NM1*PR*2*UNITED
                        HEALTH CARE*****PI*87726~N3*PO BOX 30555~N4*SALT LAKE CITY*UT*841300555~CLM*9283712345*330***11:B:1*Y*A*Y*Y~DTP*435*D8*20250624~HI*ABK:B351*ABF:D649*ABF:R600~NM1*82*1*BOLES*STEVEN*J***XX*1114031507~PRV*PE*PXC*363LA2200X~LX*1~SV1*HC:99214*165*UN*1***1:2:3~DTP*472*D8*20250624~LX*2~SV1*HC:99214*165*UN*1***1:2:3~DTP*472*D8*20250624~REF*6R*9287481400~SE*33*101770887~GE*1*525620842~IEA*1*888251331~
                      payerId: P123
                  operationName: claimSubmission
                summary: Submit Claim With Pre-check Request
              SubmitClaimTicket:
                value:
                  mutation: 'mutation submitClaimTicket($claimTicketInput: ClaimTicketInput!) { submitClaimTicket(claimTicketInput:
                    $claimTicketInput) { ticketNumber ticketStatus preSignedUrl } }'
                  variables:
                    claimTicketInput:
                      lineDetails:
                      - lineKey: lrlspg8hgksv971756148162162
                        lineAmountOwed: '450.00'
                      claimActionIdentifier: fd00e249-fb5f-4601-a392-1ee032df61d0-1756148161470
                      ticketType: RECON
                      ticketAction: Create
                      ticketNumber: PIQ-12345678
                      providerComments: Reconsideration request
                      hasAttachment: true
                      isAttachmentUploaded: true
                      operator:
                        operatorEmailId: john.doe@gmail.com
                        operatorFirstName: John
                        operatorLastName: Doe
                        operatorPhoneNumber: 512-888-9999
                        operatorCity: Minneapolis
                        operatorState: MN
                        operatorStreet: 1555 lex ave
                        operatorZip: '12345'
                      claimAmountOwed: '1000.00'
                      requestReconsiderationReason: INCORRECT_PAYMENT
                      placeOfServiceState: MN
                      isAppealOnBehalfOfMember: false
                      isExternalReviewAppeal: false
                      payerId: '00123'
                  operationName: submitClaimTicket
                summary: Submit Claim Ticket
          multipart/form-data:
            schema:
              required:
              - operations
              - map
              - '0'
              type: object
              properties:
                '0':
                  type: string
                  description: The attachment file to upload
                  format: binary
                operations:
                  type: string
                  description: GraphQL mutation with variables
                  format: json
                map:
                  type: string
                  description: Maps file fields in 'operations' to the file form fields
                  format: json
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 (required for Unsolicited claim attachments)
          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
      - documentTypeCode
    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*BRT219996150   *ZZ*87726          *250625*0826*^*00501*888251331*1*P*:~GS*HC*BRT219996150*87726*20250625*0826*525620842*X*005010X222A1~ST*837*101770887*005010X222A1~BHT*0019*00*25062588055*20250625*0826*CH~NM1*41*2*RTS*****46*223832302~PER*IC*LORAINE
            GOETSCH*TE*7328735133~NM1*40*2*UNITED HEALTHCARE 1500*****46*87726~HL*1**20*1~NM1*85*2*MERCY
            GILBERT MEDICAL CENTER*****XX*1992735088~N3*3555 S VAL VISTA DR~N4*EDWARDSVILLE*IL*620253776~REF*EI*352263845~PER*IC*DAVIS,
            SARAH*TE*6185094866*FX*6185094866~HL*2*1*22*0~SBR*P*18*******ZZ~NM1*IL*1*LNLAMDA*FNTIMDA****MI*990313643~N3*201
            MONTGOMERY STREET*APT 539~N4*JERSEY CITY*NJ*07302~DMG*D8*19800605*F~NM1*PR*2*UNITED HEALTH
            CARE*****PI*87726~N3*PO BOX 30555~N4*SALT LAKE CITY*UT*841300555~CLM*9283712345*330***11:B:1*Y*A*Y*Y~DTP*435*D8*20250624~HI*ABK:B351*ABF:D649*ABF:R600~NM1*82*1*BOLES*STEVEN*J***XX*1114031507~PRV*PE*PXC*363LA2200X~LX*1~SV1*HC:99214*165*UN*1***1:2:3~DTP*472*D8*20250624~LX*2~SV1*HC:99214*165*UN*1***1:2:3~DTP*472*D8*20250624~REF*6R*9287481400~SE*33*101770887~GE*1*525620842~IEA*1*888251331~
        payerId:
          type: string
          description: Payer ID
          example: '87726'
      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*BRT21345676150   *ZZ*87726          *250625*0826*^*00501*888234331*1*P*:~GS*HC*BRT2123496150*87726*20250625*0826*525620842*X*005010X222A1~ST*837*101770887*005010X222A1~BHT*0019*00*25062588055*20250625*0826*CH~NM1*41*2*RTS*****46*223832302~PER*IC*ABCD*TE*7328735133~NM1*40*2*UNITED
            HEALTHCARE 1500*****46*87726~HL*1**20*1~NM1*85*2*ABCD*****XX*1992735088~N3*3555 S VAL AA DR~N4*EDWARDSVILLE*IL*620253776~REF*EI*352263845~PER*IC*NAME,
            LAST*TE*6185094866*FX*6185094866~HL*2*1*22*0~SBR*P*18*******ZZ~NM1*IL*1*LNLAMDA*ABCD****MI*990313643~N3*201
            STREET STREET*APT 123~N4* CITY*NJ*07302~DMG*D8*19800605*F~NM1*PR*2*UNITED HEALTH CARE*****PI*87726~N3*PO
            BOX 30555~N4*CITY*UT*841300555~CLM*9283712345*330***11:B:1*Y*A*Y*Y~DTP*435*D8*20250624~HI*ABK:B351*ABF:D649*ABF:R600~NM1*82*1*BOLES*STEVEN*J***XX*1114034507~PRV*PE*PXC*3634AL2200X~LX*1~SV1*HC:99214*165*UN*1***1:2:3~DTP*472*D8*20250624~LX*2~SV1*HC:99214*165*UN*1***1:2:3~DTP*472*D8*20250624~REF*6R*9287481400~SE*33*101770887~GE*1*525620842~IEA*1*888251331~
        responseType:
          type: string
          description: value describing x12ResponseData type
          example: '837999'
        x12Response277CA:
          type: string
          description: EDI x12-277 claim acknowledgement
          example: ISA*00*          *00*          *ZZ*BRT21345676150   *ZZ*87726          *250625*0826*^*00501*888234331*1*P*:~GS*HC*BRT2123496150*87726*20250625*0826*525620842*X*005010X222A1~ST*837*101770887*005010X222A1~BHT*0019*00*25062588055*20250625*0826*CH~NM1*41*2*RTS*****46*223832302~PER*IC*ABCD*TE*7328735133~NM1*40*2*UNITED
            HEALTHCARE 1500*****46*87726~HL*1**20*1~NM1*85*2*ABCD*****XX*1992735088~N3*3555 S VAL AA DR~N4*EDWARDSVILLE*IL*620253776~REF*EI*352263845~PER*IC*NAME,
            LAST*TE*6185094866*FX*6185094866~HL*2*1*22*0~SBR*P*18*******ZZ~NM1*IL*1*LNLAMDA*ABCD****MI*990313643~N3*201
            STREET STREET*APT 123~N4* CITY*NJ*07302~DMG*D8*19800605*F~NM1*PR*2*UNITED HEALTH CARE*****PI*87726~N3*PO
            BOX 30555~N4*CITY*UT*841300555~CLM*9283712345*330***11:B:1*Y*A*Y*Y~DTP*435*D8*20250624~HI*ABK:B351*ABF:D649*ABF:R600~NM1*82*1*BOLES*STEVEN*J***XX*1114034507~PRV*PE*PXC*3634AL2200X~LX*1~SV1*HC:99214*165*UN*1***1:2:3~DTP*472*D8*20250624~LX*2~SV1*HC:99214*165*UN*1***1:2:3~DTP*472*D8*20250624~REF*6R*9287481400~SE*33*101770887~GE*1*525620842~IEA*1*888251331~
        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
      - claimActionIdentifier
      - lineDetails
      - ticketType
      - ticketAction
    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
        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
x-readme:
  explorer-enabled: true
  proxy-enabled: true