Certifyos Facility Credentialing Outreach Resource API

openapi: 3.2.0
info:
  description: API for Certify application
  title: Certify API Layer Facility Credentialing Outreach Resource API
  version: 1.0.0
servers:
- url: http://localhost:9000
  description: Local Development Server
- url: https://api-service.staging.certifyos.com
  description: Staging Server
- url: https://api-service.internal.certifyos.com
  description: Internal Server
- url: https://api-service.test.certifyos.com
  description: Test Server
- url: https://api-service.demo.certifyos.com
  description: Demo Server
- url: https://api-service.certifyos.com
  description: Production Server
tags:
- name: Facility Credentialing Outreach Resource
paths:
  /facility-credentialing-outreaches:
    post:
      summary: Send a new facility credentialing outreach email
      description: Sends a credentialing outreach email for a facility credentialing workflow. For multi-tenant outreach, supply workflowIds (>1 entry) and initiatingWorkflowId.
      operationId: sendFacilityCredentialingOutreach
      parameters:
      - description: Tenant ID
        required: true
        name: tenant-id
        in: header
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendCredentialingOutreachRequest'
        required: true
      responses:
        '201':
          description: Outreach email sent successfully
          content:
            application/json: {}
        '400':
          description: Invalid request data
          content:
            application/json: {}
        '401':
          description: Unauthorized - Authentication required
        '403':
          description: Forbidden - User does not have required permissions
        '422':
          description: Initiating tenant outreach template missing or incomplete
        '500':
          description: Internal Server Error - An unexpected error occurred
        '503':
          description: Multi-tenant outreach feature not enabled in this environment
      tags:
      - Facility Credentialing Outreach Resource
      security:
      - jwt: []
  /facility-credentialing-outreaches/attachments/{attachmentId}/download:
    get:
      summary: Download email attachment
      description: Returns a presigned URL for downloading an email attachment from Google Cloud Storage. The URL expires after 1 hour.
      operationId: downloadFacilityOutreachEmailAttachment
      parameters:
      - description: Attachment ID
        required: true
        name: attachmentId
        in: path
        schema:
          type: string
          pattern: \S
      - description: Tenant ID
        required: true
        name: tenant-id
        in: header
        schema:
          type: string
      responses:
        '200':
          description: Presigned URL generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentDownloadResponse'
        '401':
          description: Unauthorized - Authentication required
        '403':
          description: Forbidden - User does not have required permissions
        '404':
          description: Attachment not found
        '500':
          description: Internal Server Error - An unexpected error occurred
      tags:
      - Facility Credentialing Outreach Resource
      security:
      - jwt: []
  /facility-credentialing-outreaches/workflow/{workflowId}:
    get:
      summary: List all facility outreaches for a workflow
      description: Returns a list of all facility outreaches associated with the specified facility credentialing workflow
      operationId: listFacilityCredentialingOutreaches
      parameters:
      - description: Workflow ID
        required: true
        name: workflowId
        in: path
        schema:
          type: string
          pattern: \S
      - description: Tenant ID
        required: true
        name: tenant-id
        in: header
        schema:
          type: string
      responses:
        '200':
          description: List of outreaches retrieved successfully
          content:
            application/json: {}
        '401':
          description: Unauthorized - Authentication required
        '403':
          description: Forbidden - User does not have required permissions
        '500':
          description: Internal Server Error - An unexpected error occurred
      tags:
      - Facility Credentialing Outreach Resource
      security:
      - jwt: []
  /facility-credentialing-outreaches/{outreachId}/details:
    get:
      summary: Get a single facility outreach with emails and replies
      description: Returns the details of a facility outreach including all its emails, their replies, and a timeline
      operationId: getFacilityCredentialingOutreachDetail
      parameters:
      - description: Outreach ID
        required: true
        name: outreachId
        in: path
        schema:
          type: string
          pattern: \S
      - description: Tenant ID
        required: true
        name: tenant-id
        in: header
        schema:
          type: string
      responses:
        '200':
          description: Outreach detail retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutreachDetailResponse'
        '401':
          description: Unauthorized - Authentication required
        '403':
          description: Forbidden - User does not have required permissions
        '404':
          description: Outreach not found
        '500':
          description: Internal Server Error - An unexpected error occurred
      tags:
      - Facility Credentialing Outreach Resource
      security:
      - jwt: []
components:
  schemas:
    Instant:
      type: string
      format: date-time
      examples:
      - '2022-03-10T16:15:50Z'
    EmailWithReplies:
      type: object
      properties:
        id:
          type: string
        subject:
          type: string
        body:
          type: string
        fromAddress:
          type: array
          items:
            type: string
        toAddresses:
          type: array
          items:
            type: string
        ccAddresses:
          type: array
          items:
            type: string
        bccAddresses:
          type: array
          items:
            type: string
        direction:
          type: string
        deliveryStatus:
          type: string
        engagementData:
          type: string
        dispatched:
          type: boolean
        sendgridId:
          type: string
        statusCode:
          type: integer
          format: int32
        createdAt:
          $ref: '#/components/schemas/Instant'
        updatedAt:
          $ref: '#/components/schemas/Instant'
        replies:
          type: array
          items:
            $ref: '#/components/schemas/EmailReply'
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
    OutreachReasonWithLabel:
      type: object
      description: Outreach reason with ID and label
      properties:
        id:
          type: string
          description: Unique identifier for the outreach reason
          examples:
          - reason-123e4567-e89b-12d3-a456-426614174000
        label:
          type: string
          description: Display label for the outreach reason
          examples:
          - Malpractice Insurance Missing
    EmailReply:
      type: object
      properties:
        id:
          type: string
        subject:
          type: string
        body:
          type: string
        fromAddress:
          type: array
          items:
            type: string
        toAddresses:
          type: array
          items:
            type: string
        ccAddresses:
          type: array
          items:
            type: string
        direction:
          type: string
        deliveryStatus:
          type: string
        createdAt:
          $ref: '#/components/schemas/Instant'
        updatedAt:
          $ref: '#/components/schemas/Instant'
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
    OutreachDetailResponse:
      description: Response containing outreach details including emails, replies, and timeline
      type: object
      properties:
        id:
          type: string
        tenantId:
          type: string
        workflowId:
          type: string
        outreachType:
          type: string
        reasons:
          type: array
          items:
            $ref: '#/components/schemas/OutreachReasonWithLabel'
          description: 'List of outreach reasons with IDs and labels. Note: This field changed from List<String> to List<OutreachReasonWithLabel> to provide enriched reason information with labels.'
          examples:
          - - id: reason-123
              label: Malpractice Insurance Missing
        active:
          type: boolean
        attemptsCount:
          type: integer
          format: int32
        lastAttemptedAt:
          $ref: '#/components/schemas/Instant'
        workflowStatus:
          type: string
        createdBy:
          type: string
        createdByName:
          type: string
        createdAt:
          $ref: '#/components/schemas/Instant'
        updatedAt:
          $ref: '#/components/schemas/Instant'
        emails:
          type: array
          items:
            $ref: '#/components/schemas/EmailWithReplies'
        timeline:
          type: array
          items:
            $ref: '#/components/schemas/TimelineItem'
    Attachment:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
        size:
          type: integer
          format: int64
    AttachmentDTO:
      type: object
      required:
      - filename
      - content
      - contentType
      properties:
        filename:
          type: string
          pattern: \S
        content:
          type: string
          format: binary
        contentType:
          type: string
          pattern: \S
    SendCredentialingOutreachRequest:
      description: Request body for sending a credentialing outreach email
      type: object
      properties:
        workflowId:
          type: string
          description: The workflow ID for the credentialing outreach. Required for single-workflow requests. When workflowIds is provided with more than one entry, this field is optional.
          examples:
          - workflow-123
        workflowIds:
          type: array
          items:
            type: string
          description: List of workflow IDs for multi-tenant outreach. When more than one entry is provided, initiatingWorkflowId must also be set. Single-workflow requests should leave this null and use workflowId instead.
          examples:
          - - workflow-123
            - workflow-456
        initiatingWorkflowId:
          type: string
          description: The workflow ID of the initiating org for multi-tenant outreach. Required when workflowIds contains more than one entry. Must be present in the workflowIds list. The initiating workflow's tenant outreach-settings template is applied to all bundled workflows.
          examples:
          - workflow-123
        toEmails:
          type: array
          items:
            type: string
          description: List of email addresses to send the outreach email to
          examples:
          - - recipient@example.com
          minItems: 1
        body:
          type: string
          description: Email body content
          examples:
          - Please complete your credentialing application.
          pattern: \S
        ccEmails:
          type: array
          items:
            type: string
          description: Optional list of CC email addresses
          examples:
          - - cc@example.com
        bccEmails:
          type: array
          items:
            type: string
          description: Optional list of BCC email addresses
          examples:
          - - bcc@example.com
        outreachReasons:
          type: array
          items:
            type: string
          description: List of reasons for the outreach
          examples:
          - - Missing documentation
            - Expired license
          minItems: 1
        subject:
          type: string
          description: Email subject line
          examples:
          - 'Action Required: Complete Your Credentialing'
          pattern: \S
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/AttachmentDTO'
          description: Optional list of email attachments
        multiTenant:
          type: boolean
      required:
      - toEmails
      - body
      - outreachReasons
      - subject
    AttachmentDownloadResponse:
      description: Response containing presigned URL for downloading email attachment
      type: object
      properties:
        url:
          type: string
          description: Presigned URL for downloading the attachment
        expiresIn:
          type: integer
          format: int32
          description: Number of hours until the URL expires
        expiresAt:
          type: integer
          format: int64
          description: Unix timestamp when the URL expires
        fileName:
          type: string
          description: Original filename of the attachment
    TimelineItem:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        date:
          $ref: '#/components/schemas/Instant'
        type:
          type: string
        status:
          type: string
  securitySchemes:
    jwt:
      type: http
      description: JWT Authentication - Provide only the raw token without Bearer prefix
      scheme: bearer
      bearerFormat: JWT