OSG JourneyConnect 1.3 Specification

openapi: 3.0.3
info:
  title: OSG JourneyConnect - API Specification
  description: |-
    This document is the [OpenAPI 3.0 specification](https://swagger.io/specification/v3/) of the OSG JourneyConnect API.
    For more information, please see the [full documentation](https://docs.api.osgconnect.com) site.

    This API is intended for use by the employees and clients of OSG.  Any other use is strictly prohibited.
  contact:
    name: Customer Service
    email: clientcaredept@osgconnect.com
  version: 1.3.0
externalDocs:
  description: Privacy Policy
  url: https://osgconnect.com/privacy-policy/
servers:
  - url: https://testapi.osgconnect.com/v1
    description: Test
  - url: https://api.osgconnect.com/v1
    description: Production
tags:
  - name: utilities
    description: Verify connectivity and authentication with the API
  - name: communications
    description: Initiate digital communications
  - name: documents
    description: Search and fetch document information and artifacts

paths:
  /communications/send:
    post:
      security:
        - osgconnect_auth:
            - client:admin
            - communication-manager
            - communication-sender
      tags:
        - communications
      summary: Send a digital communication
      operationId: CommunicationsSend
      externalDocs:
        description: Full Documentation
        url: https://docs.api.osgconnect.com/docs/Api/Communications/Send/Send.html
      requestBody:
        $ref: '#/components/requestBodies/SendCommunicationRequest'
      responses:
        '202':
          $ref: '#/components/responses/SendCommunicationResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/NotAuthenticatedResponse'
        '403':
          $ref: '#/components/responses/NotAuthorizedResponse'
        default:
          $ref: '#/components/responses/UnexpectedErrorResponse'

  /documents/{documentId}:
    post:
      tags:
        - documents
      security:
        - osgconnect_auth:
            - client:admin
            - document:manager
            - document:viewer
      summary: Retrieves a document by its unique identifier
      operationId: GetDocumentById
      externalDocs:
        description: Full Documentation
        url: https://docs.api.osgconnect.com/docs/Api/Documents/Get/Get.html
      parameters:
        - name: documentId
          in: path
          description: The id of the document to be downloaded
          required: true
          schema:
            type: string
      requestBody:
        $ref: '#/components/requestBodies/GetDocumentByIdQueryRequest'
      responses:
        '200':
          $ref: '#/components/responses/GetDocumentByIdQueryResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/NotAuthenticatedResponse'
        '403':
          $ref: '#/components/responses/NotAuthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        default:
          $ref: '#/components/responses/UnexpectedErrorResponse'

  /documents/{documentId}/download:
    post:
      tags:
        - documents
      security:
        - osgconnect_auth:
            - client:admin
            - document:manager
            - document:viewer
      summary: Download a document
      operationId: DocumentsDownload
      externalDocs:
        description: Full Documentation
        url: https://docs.api.osgconnect.com/docs/Api/Documents/Download/Download.html
      parameters:
        - name: documentId
          in: path
          description: The id of the document to be downloaded
          required: true
          schema:
            type: string
      requestBody:
        $ref: '#/components/requestBodies/DownloadDocumentRequest'
      responses:
        '200':
          $ref: '#/components/responses/DownloadDocumentResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/NotAuthenticatedResponse'
        '403':
          $ref: '#/components/responses/NotAuthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        default:
          $ref: '#/components/responses/UnexpectedErrorResponse'

  /documents/search:
    post:
      tags:
        - documents
      security:
        - osgconnect_auth:
            - client:admin
            - document:manager
            - document:viewer
      summary: Search documents
      operationId: SearchDocuments
      externalDocs:
        description: Full Documentation
        url: https://docs.api.osgconnect.com/docs/Api/Documents/Search/Search.html
      requestBody:
        $ref: '#/components/requestBodies/SearchDocumentsQueryRequest'
      responses:
        '200':
          $ref: '#/components/responses/SearchDocumentsQueryResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/NotAuthenticatedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        default:
          $ref: '#/components/responses/UnexpectedErrorResponse'


  /utilities/echo:
    post:
      tags:
        - utilities
      summary: Test Authentication
      operationId: echo
      externalDocs:
        description: Full Documentation
        url: https://docs.api.osgconnect.com/docs/Api/Utilities/Echo/Echo.html
      requestBody:
        required: true
        description: Have the API echo the provided content.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EchoCommand'
      responses:
        '200':
          $ref: '#/components/responses/EchoCommandResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/NotAuthenticatedResponse'
        default:
          $ref: '#/components/responses/UnexpectedErrorResponse'
      security:
        - osgconnect_auth:
            - client:authenticated

  /utilities/ping:
    get:
      tags:
        - utilities
      summary: Test Connectivity
      externalDocs:
        description: Full Documentation
        url: https://docs.api.osgconnect.com/docs/Api/Utilities/Ping/Ping.html
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        default:
          $ref: '#/components/responses/UnexpectedErrorResponse'

#########################################################################

components:
  schemas:
    Address:
      type: object
      properties:
        AddressLine1:
          type: string
          example: Headquarters
        AddressLine2:
          type: string
          example: OSG
        AddressLine3:
          type: string
          example: 1234 Main Street
        AddressLine4:
          type: string
          example: Suite 1
        City:
          type: string
          example: Carol Stream
        State:
          type: string
          example: IL
        PostalCode:
          type: string
          example: 60188
        PostalCodeExtension:
          type: string
          example: 0000
        AddressCountry:
          type: string
          example: US

    ApiResult:
      type: object
      properties:
        IsSuccess:
          type: boolean
          example: true
        Messages:
          type: array
          items:
            type: string
            example: Hello!
        SentOnUtc:
          type: string
          format: date-time
          example: '2025-01-01Z00:00:00'
        TraceId:
          type: string
          example: 00000000-0000-0000-0000-000000000000
        CorrelationId:
          type: string
          example: test-request-1

    Caller:
      type: object
      properties:
        ClientId:
          type: string
          example: 00000000-0000-0000-0000-000000000000
        ClientCustomerId:
          type: string
          example: test-user-1
        CorrelationId:
          type: string
          example: customer-request-1

    ClientDataEntry:
      type: object
      properties:
        Name:
          type: string
          example: customer-name
        Value:
          type: string
          example: Test User

    DocumentSummary:
      type: object
      properties:
        DocumentId:
          type: string
          example: df767cc2-2c9e-48cb-986b-2bc05d01cae7
        DocumentName:
          type: string
          example: test.txt
        ContentType:
          type: string
          example: text/plain
        ContentLength:
          type: number
          example: 4
        Contents:
          type: string
          example: VGhpcyBpcyBhIHRlc3Q=

    DownloadDocumentQuery:
      type: object
      properties:
        Caller:
          $ref: '#/components/schemas/Caller'

    EchoCommand:
      type: object
      properties:
        InputValue:
          type: string
          example: Hello API!
        Caller:
          $ref: '#/components/schemas/Caller'

    EchoCommandResult:
      type: object
      properties:
        OutputValue:
          type: string
          example: Hello API!
        Result:
          $ref: '#/components/schemas/ApiResult'

    GetDocumentByIdQuery:
      type: object
      properties:
        IncludeContents:
          type: boolean
          example: true
        Caller:
          $ref: '#/components/schemas/Caller'

    GetDocumentByIdQueryResult:
      type: object
      properties:
        Document:
          $ref: '#/components/schemas/DocumentSummary'
        Result:
          $ref: '#/components/schemas/ApiResult'

    SearchDocumentsQuery:
      type: object
      properties:
        AccountNumber:
          type: string
          example: 1234567890
        AccountDiscriminator:
          type: string
          example: 1
        StartDate:
          type: string
          format: date
          example: 2025-01-01
        EndDate:
          type: string
          format: date
          example: 2025-04-30
        PageSize:
          type: number
          example: 25
        PageNumber:
          type: number
          example: 1
        Caller:
          $ref: '#/components/schemas/Caller'

    SearchDocumentsQueryResult:
      type: object
      properties:
        Documents:
          type: array
          items:
            $ref: '#/components/schemas/DocumentSummary'
        TotalResults:
          type: number
          example: 1
        PageNumber:
          type: number
          example: 1
        TotalPages:
          type: number
          example: 1
        PageSize:
          type: number
          example: 25
        Result:
          $ref: '#/components/schemas/ApiResult'

    SendCommunicationCommand:
      type: object
      properties:
        CommunicationType:
          type: string
          example: osg-test-letter
        CommunicationSubType:
          type: string
          example: welcome-letter
        DeliveryMethod:
          type: string
          example: email
          enum:
            - Email
            - Print
            - EmailAndPrint
        AccountNumber:
          type: string
          example: 1234567890
        AccountDiscriminator:
          type: string
          example: 1
        EmailAddress:
          type: string
          example: test@osgconnect.com
        EmailOptions:
          type: string
          example: PrintOnFailure
          enum:
            - None
            - PrintOnFailure
        MailingAddress:
          $ref: '#/components/schemas/Address'
        ClientData:
          type: object
          properties:
            Items:
              type: array
              items:
                $ref: '#/components/schemas/ClientDataEntry'
        Caller:
          $ref: '#/components/schemas/Caller'

    SendCommunicationResult:
      type: object
      properties:
        Result:
          $ref: '#/components/schemas/ApiResult'

          #-------------------------------------------------------------------------------  

  requestBodies:
    DownloadDocumentRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DownloadDocumentQuery'

    EchoCommandRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EchoCommand'

    GetDocumentByIdQueryRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetDocumentByIdQuery'

    SearchDocumentsQueryRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SearchDocumentsQuery'

    SendCommunicationRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SendCommunicationCommand'

          #-------------------------------------------------------------------------------

  responses:
    AcceptedResponse:
      description: The request was received and is being processed.

    BadRequestResponse:
      description: The request was not valid.  The document body may contain additional details.
      content:
        text/plain:
          schema:
            type: string

    DownloadDocumentResponse:
      description: The request was successful
      content:
        application/octet-stream:
          schema:
            type: string
            format: binary


    EchoCommandResponse:
      description: Contains the result of the echo command.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EchoCommandResult'

    GetDocumentByIdQueryResponse:
      description: Contains the result of the get document by id query
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetDocumentByIdQueryResult'

    NotAuthenticatedResponse:
      description: The user is not authenticated or the security token has expired.

    NotAuthorizedResponse:
      description: The user is not authorized to execute the request.

    NotFoundResponse:
      description: The requested item was not found.

    SearchDocumentsQueryResponse:
      description: Contains the results of the document search.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SearchDocumentsQueryResult'

    SendCommunicationResponse:
      description: Contain the result of the send communication request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SendCommunicationResult'

    SuccessResponse:
      description: The request was successful.

    UnexpectedErrorResponse:
      description: An unexpected error occurred processing the request.
      content:
        text/plain:
          schema:
            type: string

  #-------------------------------------------------------------------------------

  securitySchemes:
    osgconnect_auth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: security/token
          refreshUrl: security/refresh
          scopes:
            "client:admin": you have the ability to execute all operations for your organization
            "client:authenticated": you have been successfully authenticated
            "communication:manager": you can manage and view communications
            "communication:sender": you can send new communications
            "document:manager": you can manage and view documents
            "document:viewer": you can view documents