Certifyos Shared Member Status Change API

openapi: 3.2.0
info:
  description: API for Certify application
  title: Certify API Layer Shared Member Status Change 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: SharedMemberStatusChange
  description: Change a shared workflow's member statuses (internal).
paths:
  /api/v1/anchor-groups/{anchorGroupId}/shared-credentialing-workflows/{sharedCredWorkflowId}/member-status-changes:
    post:
      summary: Change a shared workflow's member statuses
      description: Moves each named member workflow through the same status-change path an interactive change uses, authorizing the caller in each member's own tenant, then recomputes the group's rollup once and returns the derived shared status alongside the per-member outcomes.
      operationId: sharedWorkflowChangeMemberStatuses
      tags:
      - SharedMemberStatusChange
      parameters:
      - description: Anchor Group id
        required: true
        name: anchorGroupId
        in: path
        schema:
          type: string
      - description: Shared credentialing workflow id
        required: true
        name: sharedCredWorkflowId
        in: path
        schema:
          type: string
      - name: tenant-id
        in: header
        required: true
        description: Tenant ID
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SharedMemberStatusChangeRequest'
        required: true
      responses:
        '200':
          description: Per-member outcomes and the recomputed shared status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SharedMemberStatusChangeResponse'
        '400':
          description: Missing request body or workflow ids
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Not authenticated
        '403':
          description: Missing the credentialing-workflow update permission
        '404':
          description: No such shared workflow in this anchor group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
      - jwt: []
components:
  schemas:
    SharedMemberStatusChangeResponse:
      type: object
      required:
      - successful
      - failed
      - totalCount
      - successCount
      - failureCount
      description: Per-member outcomes plus the recomputed shared status.
      properties:
        successful:
          type: array
          items:
            $ref: '#/components/schemas/StatusChangeResult'
          description: Members whose status change was applied.
        failed:
          type: array
          items:
            $ref: '#/components/schemas/StatusChangeResult'
          description: Members whose status change was refused.
        totalCount:
          type: integer
          format: int32
          examples:
          - 3
          description: Members processed.
        successCount:
          type: integer
          format: int32
          examples:
          - 2
          description: Members changed.
        failureCount:
          type: integer
          format: int32
          examples:
          - 1
          description: Members refused.
        sharedStatus:
          type: string
          examples:
          - PSV_READY
          description: The group's derived status after the recompute.
    ApiError:
      type: object
      description: Standard API error response containing a list of error objects
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorObject'
          description: List of error objects describing validation or processing failures
    NextCredentialingDateChangeLogEntry:
      type: object
      required:
      - changedFrom
      - changedTo
      - changeReason
      - createdBy
      - createdAt
      description: Change log entry tracking changes to the next credentialing date
      properties:
        changedFrom:
          $ref: '#/components/schemas/LocalDate'
          type: string
          examples:
          - '2025-12-31'
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: Previous next credentialing date in YYYY-MM-DD format
        changedTo:
          $ref: '#/components/schemas/LocalDate'
          type: string
          examples:
          - '2026-01-15'
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: New next credentialing date in YYYY-MM-DD format
        changeReason:
          type: string
          examples:
          - Updated based on new license expiration
          description: Reason for the change
        createdBy:
          type: string
          examples:
          - user_123456
          description: User who made the change
        createdAt:
          type: string
          format: date-time
          examples:
          - '2024-01-15T10:30:00Z'
          description: Timestamp when the change was made
    Instant:
      type: string
      format: date-time
      examples:
      - '2022-03-10T16:15:50Z'
    CreateTimelineEventRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          pattern: \S
        changeReason:
          type: string
        credentialingDecisionDate:
          $ref: '#/components/schemas/LocalDate'
        nextCredentialingDate:
          $ref: '#/components/schemas/LocalDate'
        overrideReason:
          type: string
        isOverride:
          type: boolean
        progressionReason:
          type: string
          maxLength: 1000
          description: The reason to move past the open PSV blockers. At most 1000 characters.
        acknowledgedCoverKeys:
          type: array
          maxItems: 500
          items:
            type: string
            pattern: \S
          description: Cover keys of the open PSV blockers this move goes past, as the progression read returned them. Request-only, never stored. At most 500 non-blank entries.
        hiddenCoverKeys:
          type: array
          maxItems: 100
          items:
            type: string
            pattern: \S
          description: 'Cover keys of the open blockers to hide from the PSV packet: on a move to PSV Complete (the gate writes the mark on the stored covered blockers), or on a single-tenant Withdraw / Cancel before PSV Complete (from GET {workflowId}/psv-progression). Request-only, never stored. Refused on the bulk route; ignored when PSV transparency is off for the tenant. At most 100 non-blank entries.'
        hiddenFindingRuleKeys:
          type: array
          maxItems: 100
          items:
            type: string
            pattern: \S
          description: 'Single-tenant Withdraw / Cancel at PSV Complete: the full desired set of non-clean reasons (finding rule keys) hidden from the packet. Absent leaves the marks as they are; an empty list removes every mark; a key that is not a finding is ignored. Request-only. Ignored at PSV Ready or later and when PSV transparency is off for the tenant; refused on the bulk route. At most 100 non-blank entries.'
    GatedRuleItem:
      type: object
      required:
      - ruleKey
      description: 'A PSV rule result: its key, the PSV type it belongs to and a description'
      properties:
        ruleKey:
          type: string
          examples:
          - LICENSE_ACTIVE
          description: Key of the rule
        psvType:
          type: string
          examples:
          - License
          description: PSV type the rule belongs to, '-' when unknown
        description:
          type: string
          examples:
          - License is expired
          description: Human readable description of the rule result
        coverKey:
          type: string
          examples:
          - LICENSE_ACTIVE|lic_1
          description: Stable key of the open blocker, used to match covers and acknowledgements
        hiddenFromPacket:
          type: boolean
          examples:
          - true
          description: True when the analyst chose to hide this rule from the PSV packet (CP-40893)
    MemberReason:
      type: object
      description: One member's own change reason, and for a single-member request its hide choices.
      properties:
        changeReason:
          type: string
          maxLength: 1000
          description: This member's change reason; at most 1000 characters.
        hiddenCoverKeys:
          type: array
          maxItems: 100
          items:
            type: string
            pattern: \S
          description: Cover keys to hide from the packet. Allowed only when the request moves exactly one workflow; at most 100 non-blank entries.
        hiddenFindingRuleKeys:
          type: array
          maxItems: 100
          items:
            type: string
            pattern: \S
          description: The full desired set of non-clean reasons (finding rule keys) hidden from the packet. Absent leaves the marks as they are; an empty list removes every mark. Allowed only when the request moves exactly one workflow; at most 100 non-blank entries.
        acknowledgedCoverKeys:
          type: array
          maxItems: 500
          items:
            type: string
            pattern: \S
          description: 'CP-42729: cover keys of the open PSV blockers this reason moves past, as the progression read returned them. Allowed with any number of members; at most 500 non-blank entries. When the open blockers are not all among them the member is refused with BLOCKERS_CHANGED.'
    StatusChangeResult:
      type: object
      description: Result of a single workflow status change
      properties:
        workflowId:
          type: string
          examples:
          - a2b4f213-f56e-49b7-9ffe-070ff70f0539
          description: Workflow ID that was processed
        timelineEvent:
          $ref: '#/components/schemas/TimelineEventResponse'
          type: object
          description: Timeline event response if successful
        errorMessage:
          type: string
          description: Error message if the operation failed
        errorCode:
          type: string
          description: Error code if the operation failed
        blockers:
          type: array
          items:
            $ref: '#/components/schemas/GatedRuleItem'
          description: 'CP-42729: the open PSV blockers when the PSV progression gate refused the move; absent otherwise'
    LocalDate:
      type: string
      format: date
      examples:
      - '2022-03-10'
    ErrorObject:
      type: object
      description: Individual error object containing details about a specific validation or processing error
      properties:
        httpStatus:
          type: integer
          format: int32
          examples:
          - 400
          description: HTTP status code for this error
        reason:
          type: string
          examples:
          - VALIDATION_ERROR
          description: Error reason/code
        title:
          type: string
          examples:
          - 'Validation failed for field: eventTypes'
          description: Error title/summary
        detail:
          type: string
          examples:
          - eventTypes is required and cannot be empty or null
          description: Detailed error message
        rejectedValue:
          type: string
          description: The value that was rejected, omitted for sensitive fields such as SSN
    TimelineEventResponse:
      type: object
      description: Response containing timeline event information
      properties:
        id:
          type: string
          examples:
          - te_123456
          description: Unique identifier for the timeline event
        workflowId:
          type: string
          examples:
          - cw_123456
          description: ID of the associated credentialing workflow
        data:
          $ref: '#/components/schemas/TimelineEventData'
          type: object
          description: Timeline event data containing name, changeReason, and date fields
        createdBy:
          type: string
          examples:
          - user_123456
          description: ID of the user who created the timeline event
        updatedBy:
          type: string
          examples:
          - user_123456
          description: ID of the user who last updated the timeline event
        createdAt:
          $ref: '#/components/schemas/Instant'
          type: string
          examples:
          - '2024-01-01T00:00:00Z'
          description: Timestamp when the timeline event was created
        updatedAt:
          $ref: '#/components/schemas/Instant'
          type: string
          examples:
          - '2024-01-01T00:00:00Z'
          description: Timestamp when the timeline event was last updated
    TimelineEventData:
      type: object
      required:
      - name
      description: Timeline event data containing event details. Field requirements vary by event name (see oneOf conditions in schema).
      properties:
        name:
          type: string
          enum:
          - NOT_STARTED
          - IN_PROGRESS
          - OUTREACH_IN_PROGRESS
          - DATA_MISSING
          - PSV_COMPLETED
          - PSV_READY
          - SENT_TO_COMMITTEE
          - TABLED
          - WITHDRAWN_CANCELLED
          - CRED_DENIED
          - CRED_APPROVED
          examples:
          - CRED_APPROVED
          description: Name of the timeline event. Must be one of the TimelineStatus enum values.
        changeReason:
          type: string
          examples:
          - Application approved by committee
          description: 'Reason for the change or status update. REQUIRED for: DATA_MISSING, WITHDRAWN_CANCELLED. Optional for: CRED_APPROVED, CRED_DENIED, and other statuses. Note: Whether this field is required or optional varies based on the permissions assigned to the user performing the action.'
        credentialingDecisionDate:
          $ref: '#/components/schemas/LocalDate'
          type: string
          examples:
          - '2024-01-15'
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: 'Date when the credentialing decision was made (YYYY-MM-DD format). REQUIRED for: CRED_APPROVED, CRED_DENIED. Not applicable for other statuses.'
        nextCredentialingDate:
          $ref: '#/components/schemas/LocalDate'
          type: string
          examples:
          - '2026-01-15'
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: 'Date when the next credentialing is due (YYYY-MM-DD format). REQUIRED for: CRED_APPROVED. Not applicable for other statuses. Should reflect the latest value from nextCredentialingDateChangeLog if present.'
        nextCredentialingDateSource:
          type: string
          enum:
          - SYSTEM_CALCULATED
          - USER_INPUT
          examples:
          - SYSTEM_CALCULATED
          description: Indicates whether the next credentialing date was calculated by the system or entered by a user. Only applicable for CRED_APPROVED events.
        nextCredentialingDateChangeLog:
          type: array
          items:
            $ref: '#/components/schemas/NextCredentialingDateChangeLogEntry'
          description: Array to track changes to the next credentialing date. The nextCredentialingDate field should reflect the latest value from this array. Only applicable for CRED_APPROVED events.
        psvPdfPath:
          type: string
          format: uri-reference
          examples:
          - /files/psv_123456.pdf
          description: 'URI reference to the PSV (Provider Summary Verification) PDF document. '
        overrideReason:
          type: string
          format: string
          examples:
          - Test override reason
          description: Indicates the reason for the override
        isOverride:
          type: boolean
          format: boolean
          examples:
          - true
          description: Indicates if the timeline event is an override bypassing the default validations
    SharedMemberStatusChangeRequest:
      type: object
      required:
      - workflowIds
      - timelineEventData
      description: Request to change the status of a shared workflow's members.
      properties:
        workflowIds:
          type: array
          maxItems: 500
          minItems: 1
          items:
            type: string
            pattern: \S
          description: Member workflow ids to move. At most 500 entries; blanks are rejected and duplicates removed (first occurrence wins), so a repeated id is moved once.
        timelineEventData:
          $ref: '#/components/schemas/CreateTimelineEventRequest'
          type: object
          description: Timeline event to apply to each member; its name is the target status.
        memberReasons:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/MemberReason'
          description: Optional change reason per member, keyed by workflow id. A member with an entry uses it; the others use timelineEventData.changeReason. Every key must also be in workflowIds.
  securitySchemes:
    jwt:
      type: http
      description: JWT Authentication - Provide only the raw token without Bearer prefix
      scheme: bearer
      bearerFormat: JWT
x-provenance:
  method: harvested
  publisher: Certifyos
  source: https://api-service.internal.certifyos.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)