openapi: 3.0.0
info:
  title: Document Search API
  description: The GraphQL Document Search API allows users to retrieve document metadata and downloading
    a document as well.
  version: 1.0.0
servers:
- url: https://sandbox-apigw.optum.com
paths:
  /oihub/document/search/v1:
    post:
      security:
      - oAuth:
        - read_healthcheck
      operationId: documentSearch
      tags:
      - Document Search
      parameters:
      - name: providerTaxId
        in: header
        description: Provider Tax ID Number
        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
      - name: nextPageToken
        in: header
        description: Paging Identifier to access the next set of records
        required: false
        schema:
          example: '2'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                query:
                  description: GraphQL query
                  type: string
                variables:
                  description: Variables for the GraphQL query
                  type: object
                  properties:
                    documentMetadataInput:
                      $ref: '#/components/schemas/DocumentMetadataInput'
                    documentInput:
                      $ref: '#/components/schemas/DocumentInput'
                operationName:
                  description: Name of the GraphQL operation to execute
                  type: string
              type: object
              required:
              - query
              - variables
              - operationName
              description: GraphQL queries to fetch Documents information
            examples:
              DocumentMetadata:
                value:
                  query: 'query DocumentMetadata($documentMetadataInput: DocumentMetadataInput!) { documentMetadata(documentMetadataInput:
                    $documentMetadataInput) { documentList { documentInfo { tin claimNumber memberId category
                    documentId fileName createdDate expiryDate physicianName policyNbr serviceDate patientName
                    checkId notificationId contentType filePath patientAccountNumber } } pagination {
                    hasMoreRecords nextPageToken } } }'
                  variables:
                    documentMetadataInput:
                      fromDate: 09/17/2021
                      toDate: 09/17/2021
                      categories: Claim
                      patientAccountNumber: '1234567890'
                      claimNumber: '1234567890'
                      filePath: File Path
                      checkId: '12345678'
                      notificationId: '12345678'
                      payerId: '87726'
                  operationName: DocumentMetadata
                summary: Document Metadata
              GetDocument:
                value:
                  query: 'query GetDocument($documentInput: DocumentInput!) { getDocument(documentInput:
                    $documentInput) { base64Document } }'
                  variables:
                    documentInput:
                      documentId: 5e63205d-9517-4043-9231-ea1a47fb6c07~repoid~fdsid~cloudspaceid
                      payerId: '87726'
                  operationName: GetDocument
                summary: Get Document
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  errors:
                    items:
                      properties:
                        code:
                          description: Error code identifying the specific error
                          type: string
                        description:
                          description: Detailed error message
                          type: string
                      type: object
                    description: List of errors if occurred during Document Search
                    type: array
                  data:
                    properties:
                      getDocument:
                        $ref: '#/components/schemas/DocumentDownloadResponse'
                      documentMetadata:
                        $ref: '#/components/schemas/DocumentMetadataResponse'
                    type: object
                type: object
              examples:
                DocumentMetadata:
                  value:
                    data:
                      documentMetadata:
                        documentList:
                        - documentInfo:
                            tin: '12345678'
                            claimNumber: '1234567890'
                            memberId: '12345678'
                            category: Prior Auth Notification
                            documentId: 11111111-1111-1111-1111-111111111111
                            fileName: 111111.PDF
                            createdDate: 09/13/2021
                            expiryDate: 09/13/2023
                            physicianName: RAM ROY
                            policyNbr: '51017'
                            serviceDate: 09/20/2021
                            patientName: Alison Curry
                            checkId: '123456789'
                            notificationId: '1111111'
                            contentType: application/pdf
                            filePath: Commercial Appeals and Disputes/Acknowledgement, Notification, and
                              Response
                            patientAccountNumber: '1234567890'
                        pagination:
                          hasMoreRecords: true
                          nextPageToken: '2'
                  summary: Document Metadata Response
                GetDocument:
                  value:
                    data:
                      getDocument:
                        base64Document: TUlNRS1WZXJzaW9uOiAxL....NWRlQwWU5DZz09
                  summary: Get Document Response
          description: Successful operation
        '400':
          description: Bad request - includes validation errors for missing or invalid fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          description: Error code identifying the specific error
                          type: string
                        description:
                          type: string
                      required:
                      - code
                      - description
              examples:
                SchemaValidationErrors:
                  summary: Schema Validation Errors
                  value:
                    errors:
                    - code: GRAPHQL_VALIDATION_FAILED
                      description: Cannot query field...
        '401':
          description: Unauthorized - Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: Authentication error message
                    type: string
              examples:
                invalidToken:
                  summary: Invalid authentication token
                  value:
                    message: 'Authentication failed: Invalid or expired token'
                missingToken:
                  summary: Missing authentication token
                  value:
                    message: 'Authentication required: No token provided'
        '500':
          description: Internal server error - Problem occurred on the server
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          description: Error code identifying the specific error
                          type: string
                        description:
                          type: string
                      required:
                      - code
                      - description
              examples:
                generalServerError:
                  summary: General server error
                  value:
                    errors:
                    - code: INTERNAL_SERVER_ERROR
                      description: An unexpected error occurred while processing the request
components:
  schemas:
    DocumentMetadataResponseDataWrapper:
      type: object
      properties:
        data:
          description: Document Metadata Response Wrapper.
          $ref: '#/components/schemas/DocumentMetadataResponseWrapper'
      description: Document Metadata Response Data Wrapper.
    DocumentMetadataInput:
      type: object
      properties:
        fromDate:
          description: Filter data starting from a specific date in MM/dd/yyyy format.
          example: 09/17/2021
          type: string
        toDate:
          description: Filter data up to a specific date in MM/dd/yyyy format. Keep last date less than
            31 days from the First Date.
          example: 09/17/2021
          type: string
        categories:
          description: This helps in narrowing down the data set to only include files that belong to
            the specified categories.
          example: Claim
          type: string
        patientAccountNumber:
          description: This helps in narrowing down the data set to only include files that belong to
            the specified patient account number (PAN).
          example: '1234567890'
          type: string
        claimNumber:
          description: Claim Number - UnitedHealthcare claim number.
          example: '1234567890'
          type: string
        filePath:
          description: File path of a document, optional parameter.
          example: File Path
          type: string
        checkId:
          description: The checkId parameter is used to uniquely identify a record.
          example: '12345678'
          type: string
        notificationId:
          description: Narrow down results based on notificationId.
          example: '12345678'
          type: string
        payerId:
          description: Required. Unique identifier assigned to a health insurance payer.
          example: '87726'
          type: string
      required:
      - fromDate
      - toDate
      - payerId
    GetDocumentResponseDataWrapper:
      type: object
      properties:
        data:
          description: Get Document Response Wrapper.
          $ref: '#/components/schemas/GetDocumentResponseWrapper'
      description: Get Document Response Data Wrapper.
    DocumentInput:
      type: object
      properties:
        documentId:
          description: A unique identifier for the document, typically a UUID or composite key.
          example: 5e63205d-9517-4043-9231-ea1a47fb6c07~repoid~fdsid~cloudspaceid
          type: string
        payerId:
          description: Required. Unique identifier assigned to a health insurance payer.
          example: '87726'
          type: string
      required:
      - documentId
      - payerId
    DocumentMetadataResponseWrapper:
      type: object
      properties:
        documentMetadata:
          description: Document Metadata Response
          $ref: '#/components/schemas/DocumentMetadataResponse'
      description: Document Metadata Response Wrapper.
    GetDocumentResponseWrapper:
      type: object
      properties:
        getDocument:
          description: Get Document Response
          $ref: '#/components/schemas/DocumentDownloadResponse'
      description: Get Document Response Wrapper.
    DocumentInfo:
      type: object
      properties:
        tin:
          description: provider tin
          example: '12345678'
          type: string
        claimNumber:
          description: claim number
          example: '1234567890'
          type: string
        memberId:
          description: member id
          example: '12345678'
          type: string
        category:
          description: document category
          example: Prior Auth Notification
          type: string
        documentId:
          description: document id
          example: 11111111-1111-1111-1111-111111111111
          type: string
        fileName:
          description: file name
          example: 111111.PDF
          type: string
        createdDate:
          description: created date
          example: 09/13/2021
          type: string
        expiryDate:
          description: expiry date
          example: 09/13/2023
          type: string
        physicianName:
          description: physician name
          example: RAM ROY
          type: string
        policyNbr:
          description: policy number
          example: '51017'
          type: string
        serviceDate:
          description: date of service
          example: 09/20/2021
          type: string
        patientName:
          description: patient name
          example: Alison Curry
          type: string
        checkId:
          description: check id
          example: '123456789'
          type: string
        notificationId:
          description: notification id
          example: '1111111'
          type: string
        contentType:
          description: file format or document type
          example: application/pdf
          type: string
        filePath:
          description: file path
          example: Commercial Appeals and Disputes/Acknowledgement, Notification, and Response
          type: string
        patientAccountNumber:
          description: patient account number
          example: '1234567890'
          type: string
      description: Document information.
    DocumentMetadataResponse:
      type: object
      properties:
        documentList:
          description: List of documents matching search criteria.
          type: array
          items:
            $ref: '#/components/schemas/DocumentList'
        pagination:
          description: Pagination details.
          $ref: '#/components/schemas/Pagination'
      description: DocumentMetadata response containing the document list and pagination.
    DocumentDownloadResponse:
      type: object
      properties:
        base64Document:
          description: Base64 encoded document content.
          example: TUlNRS1WZXJzaW9uOiAxL....NWRlQwWU5DZz09
          type: string
    Pagination:
      type: object
      properties:
        hasMoreRecords:
          description: Indicates if more results are available
          example: true
          type: boolean
        nextPageToken:
          description: Page identifier for pagination
          example: '2'
          type: string
    DocumentList:
      type: object
      properties:
        documentInfo:
          description: Document details.
          $ref: '#/components/schemas/DocumentInfo'
    DocumentMetadataRequest:
      required:
      - query
      - variables
      - operationName
      type: object
      properties:
        query:
          description: GraphQL query
          type: string
        variables:
          properties:
            input:
              $ref: '#/components/schemas/DocumentMetadataInput'
          type: object
        operationName:
          description: Name of the GraphQL operation to execute
          type: string
    GetDocumentRequest:
      required:
      - query
      - variables
      - operationName
      type: object
      properties:
        query:
          description: GraphQL query
          type: string
        variables:
          properties:
            input:
              $ref: '#/components/schemas/DocumentInput'
          type: object
        operationName:
          description: Name of the GraphQL operation to execute
          type: string
  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