One profile-backed verification story
Built in three milestones, nine epics

Promise 1 One vocabulary across two surfaces

The web app (PTApp) and the computer-to-computer feed (the API) use the same plain-English status for the same real-world situation. A check that is simply old is labeled “Stale,” not “Failed.” A check that ran and found nothing is labeled “Not found,” which does not mean “we never looked.”

Promise 2 Aliases earn their place

Name variants that a client or CAQH supplied stay internal hints until the National Provider Identifier (NPI), license, and board records support the same story. Then the variant can move to confirmed and help the next lookup for any client who touches that profile.

Promise 3 Onboarding and monitoring are different journeys

The pre-go-live file pass is not the same product path as live monitoring after go-live. The file pass returns a result for every row, never drops a row quietly, and allows reruns. When something conflicts after go-live, the experience compares what the client submitted to what the primary source shows. It does not ask the client to “fix ProviderTrust’s profile” as the default story.

Promise 4 The audit trail is for PT staff, not customers

ProviderTrust employees who need to investigate get a “what changed?” timeline behind role-based access control (RBAC). A full customer-facing audit log for every field change is deliberately out of scope for version 3.0.

What stays in place, what we add

Already built or stays: automated data ingest (labeled EGEN in the diagram), the verification application’s monitor-and-verify path, the augmented provider record, and feeds from CAQH and NSC that enrich the profile.

New for 3.0: clearer origin attribution, alias resolution before data leaves the profile, lifecycle-aware APIs for initial credentialing, ongoing monitoring, and re-credentialing, the redesigned client experience, and the internal audit experience for ProviderTrust administrators.

Interim bridge: a handful of VAP fields into Monitor

Until a deeper Monitor API redesign lands, we plan to forward about five carefully chosen fields from the verification application (VAP) into Monitor so that what a person sees in the product matches what automated checks record.

Engineering leadership has questioned a “shoehorn only” long-term path; treat “about five fields” as planning shorthand until the responsible engineering manager publishes a revised estimate and scope.

Engineering note: a translator, not a rewrite

We do not need to repaint every legacy database value in one release. Instead, stand up a status mapping layer—a translator—at the boundary where data becomes a client response. That layer turns internal Monitor and VAP states into the canonical vocabulary in the table. Keep the legacy codes in storage; only the wire format that PTApp and public integrators see changes.

The sample code below shows how such a translator behaves; the exact switch values will mirror Decision 6 once the mapping artifact lands.

// Pseudocode — status translator at the API/UI boundary
enum DnpiStatus {
  VERIFIED, NOT_VERIFIED, IN_PROGRESS,
  CONFLICT, MANUAL_FEE_REQUIRED,
  NOT_FOUND, ON_FILE_UNVERIFIED, STALE, DEACTIVATED
}

function toDnpi(internal): DnpiStatus {
  switch (internal.legacyState) {
    case 'AUTO_VERIFIED':        return VERIFIED;
    case 'STALE_NO_FAILURE':      return STALE;
    case 'NPPES_DEACTIVATED':     return DEACTIVATED;
    case 'NO_MATCH_AFTER_LOOKUP': return NOT_FOUND;
    case 'CHECK_NEVER_RAN':
      // CRITICAL: never collapse this into NOT_FOUND
      return IN_PROGRESS;
    case 'SOURCES_DIVERGE':       return CONFLICT;
    case 'FEE_REQUIRED':          return MANUAL_FEE_REQUIRED;
    default:
      // fail-loud: surface a structured warning to ops
      ops.warn('unmapped_legacy_state', internal);
      return ON_FILE_UNVERIFIED;
  }
}

Sample — verification status response

// GET /dnpi/providers/1234567890/verification-status
{
  "npi": "1234567890",
  "profile_id": "prof_27aa",
  "as_of": "2026-05-07T14:21:00Z",
  "status": "CONFLICT",
  "reason_code": "BOARD_SUSPENDED_VS_SUBMITTED_ACTIVE",
  "required_action": "client_acknowledge",
  "credentials": [
    {
      "id": "lic-tn-12345",
      "type": "RN",
      "jurisdiction": "TN",
      "status": "CONFLICT",
      "submitted": { "name": "Jane Doe",
                      "license_number": "RN-12345",
                      "origin": "CLIENT_SUPPLIED" },
      "profile": { "name": "Jane A. Doe",
                    "aliases_known": ["Janie Doe","J. A. Doe"],
                    "origin": "PT_PROFILE" },
      "primary_source": { "name": "Jane Anne Doe",
                           "board_status": "SUSPENDED",
                           "effective": "2026-05-01",
                           "origin": "PRIMARY_SOURCE_BOARD" },
      "reason_code": "BOARD_SUSPENDED_VS_SUBMITTED_ACTIVE"
    }
  ],
  "explainability": {
    "freshness_seconds": 14400,
    "matched_via": ["NPI","LICENSE_NUMBER","BOARD_NAME"]
  }
}

Sample — onboarding row outcome

// GET /dnpi/onboarding-runs/run_8b1f3/results (one row)
{
  "row_index": 4,
  "submitted": { "name": null,
                  "npi": "5555555555" },
  "outcome": "UNABLE_TO_VERIFY_AUTOMATICALLY",
  "status": "MANUAL_FEE_REQUIRED",
  "reason_code": "PRIMARY_SOURCE_TIMEOUT",
  "review_queue": "impl_review",
  "client_fields_preserved": true,
  "silent_drop": false,    // invariant for Epic 2
  "can_rerun": true
}

Permission tag pattern

Each capability maps to a permission tag, and tags attach to access roles. When a tag is marked for ProviderTrust-only internal work, global client roles must receive a hard denial—even if a screen URL leaks.

// Permission tags map to AccessRoles. PT-Only must DENY for Global-Client roles.
permissions:
  - id: "dnpi.onboarding.upload"
    pt_only: false
    default_for: ["CLIENT_ADMIN", "IMPLEMENTATION"]
  - id: "dnpi.audit.read"
    pt_only: true     // MUST deny for Global-Client AccessRoles
    default_for: ["PT_ADMIN", "DATA_SERVICES"]
  - id: "dnpi.alias.promote"
    pt_only: true
    default_for: ["PT_ADMIN"]
    requires_audit_event: true

Read-only failure mode

A read-only user who tries to upload a roster or resolve a conflict should see the same plain-English explanation in the web app (PTApp) and in the error payload from the computer-to-computer feed (the API)—the same “one vocabulary” discipline as Epic 1, applied to permission errors.

// 403 response shape (PTApp surfaces the same wording)
{
  "error": "FORBIDDEN_ROLE",
  "message": "Your role can view but not modify this. Ask your admin for access.",
  "required_permission": "dnpi.onboarding.upload",
  "current_role": "CLIENT_READ_ONLY"
}

Before you cut a pilot over

• Capture baseline counts of monitored subjects and open alerts.
• Review the status-mapping table against this tenant’s live data quirks.
• Spot-check a handful of alias confirmations for obvious mistakes.
• Confirm role-based access control matches the real user list for that client.
• Have the engineering manager and Client Success sign the rollback runbook.

During the cutover window

• Keep the change in alert volume within the agreed band versus baseline (exact percentage is tuned per pilot).
• Do not introduce new client copy that implies the customer must “fix ProviderTrust’s aggregate profile.”
• When credential origin shifts, avoid duplicate alerts for the same underlying issue.
• Exclude termed or deactivated subjects from automated re-check loops.

If you need to roll back

• Turn off the Dynamic NPI pilot flag for that tenant so legacy behavior returns immediately.
• Write a short postmortem that includes before/after tables and the alert diff.
• Feed lessons learned back into Decision 7 (cutover strategy) so the next pilot benefits.