UMTenantConfig

Custom resource that configures forwarding of Prior Auth submissions to a payer's utilization management (UM) system. Its StructureDefinition is registered by Payerbox at startup; instances are managed over the FHIR REST API at <base>/fhir/UMTenantConfig.

One instance per payer per UM system. Instances are re-read about once a minute, so changes apply without a restart. Narrative overview: UM System Integration.

Authentication

UMTenantConfig is an administrative resource — access is governed by the same Aidbox access policies as any other resource, and is not part of the PAS partner-facing scope set. See Authentication.

Routing

Identifier match is attempted first and requires the insurer Organization to be present in the submitted Bundle. Reference match compares the last two path segments, so Organization/payer-1 and http://example.org/fhir/Organization/payer-1 are equivalent.

Endpoint and delivery policy

Each header entry needs exactly one of value or valueEnv.

Authentication to the UM system

Secrets are always referenced by environment-variable name. There is no element that stores a secret value.

Transform

The transform elements above are consumed by the guidingcare connector. pas-passthrough forwards the PAS Bundle unchanged and uses only routing, endpoint and inquireRefresh.

ConceptMap names

A ConceptMap group may declare unmapped with mode: "fixed" to supply a default target. Targets with equivalence unmatched or disjoint are ignored.

Examples

{
  "resourceType": "UMTenantConfig",
  "id": "payer-1-um",
  "connector": "pas-passthrough",
  "insurer": {
    "reference": "Organization/payer-1",
    "identifier": { "system": "http://hl7.org/fhir/sid/us-npi", "value": "1234567893" }
  },
  "endpoint": {
    "baseUrl": "https://um.example.org/fhir",
    "timeoutMs": 30000,
    "retry": { "maxAttempts": 5, "backoffSeconds": [30, 120, 600, 1800] },
    "auth": {
      "type": "oauth2-client-credentials",
      "tokenUrl": "https://um.example.org/auth/token",
      "clientIdEnv": "UM_PAYER1_CLIENT_ID",
      "clientSecretEnv": "UM_PAYER1_CLIENT_SECRET",
      "scopeEnv": "UM_PAYER1_SCOPE"
    }
  },
  "insurerReference": "Organization/payer-1",
  "inquireRefresh": true
}

{
  "resourceType": "UMTenantConfig",
  "id": "payer-2-guidingcare",
  "connector": "guidingcare",
  "insurer": {
    "reference": "Organization/payer-2",
    "identifier": { "system": "http://hl7.org/fhir/sid/us-npi", "value": "9876543210" }
  },
  "endpoint": {
    "baseUrl": "https://um-gateway.example.net/epa",
    "timeoutMs": 90000,
    "retry": { "maxAttempts": 5, "backoffSeconds": [30, 120, 600, 1800] },
    "auth": {
      "type": "oauth2-client-credentials",
      "tokenUrl": "https://login.example.net/oauth2/v2.0/token",
      "clientIdEnv": "UM_PAYER2_CLIENT_ID",
      "clientSecretEnv": "UM_PAYER2_CLIENT_SECRET",
      "scopeEnv": "UM_PAYER2_SCOPE"
    },
    "headers": [
      { "name": "ocp-apim-subscription-key", "valueEnv": "UM_PAYER2_SUBSCRIPTION_KEY" },
      { "name": "tenant-id", "value": "payer-2-tenant" }
    ]
  },
  "insurerReference": "Organization/payer2.example.net",
  "defaults": {
    "authRequester": "CONTRACTED PROVIDER",
    "authType": "Durable Medical Equipment Medicaid (MLTC)",
    "treatmentType": "Durable Medical Equipment"
  },
  "requiredSupplemental": [{ "name": "AOR on File?", "value": "Yes" }],
  "lobBenId": { "identifierSystem": "https://example.net/lobBenID" },
  "conceptMaps": [
    { "name": "claimType->authClass", "reference": "ConceptMap/um-payer2-authclass" },
    { "name": "priority->authPriority", "reference": "ConceptMap/um-payer2-authpriority" },
    { "name": "pos->label", "reference": "ConceptMap/um-payer2-pos" },
    { "name": "careTeamRole->slot", "reference": "ConceptMap/um-payer2-provider-roles" },
    { "name": "providerNpi->gcId", "reference": "ConceptMap/um-payer2-provider-npi" },
    { "name": "decisionStatus->reviewAction", "reference": "ConceptMap/um-payer2-reviewaction" }
  ],
  "inquireRefresh": false,
  "passThroughExtensions": false
}

Readiness

Each config compiles to ready or invalid. An invalid config is excluded from routing: its payer's submissions are stored and returned as queued, but never delivered. Check GET /health:

{
  "um": {
    "tenants": {
      "payer-1-um": { "status": "ready", "gaps": [], "warnings": [] },
      "payer-2-guidingcare": {
        "status": "invalid",
        "gaps": ["env UM_PAYER2_CLIENT_SECRET not set", "ConceptMap/um-payer2-pos not found"],
        "warnings": []
      }
    }
  }
}

Gaps found at delivery time rather than at load time (for example a Coverage without the lobBenId identifier system) fail that Task and are recorded in ClaimResponse.error[].