$submit-attachment

Submits clinical documentation (attachments) to associate with a previously submitted prior authorization request. This operation follows the Da Vinci CDex (Clinical Data Exchange) Implementation Guide and supports the solicited attachment workflow — the Claim must already exist in the system before attachments can be submitted.

Unlike Claim/$submit and Claim/$inquire, this is a system-level operation (not scoped to a resource type) and accepts a FHIR Parameters resource instead of a Bundle.

Endpoint

POST <base>/fhir/$submit-attachment

Auth

SMART Backend Services. Scope requirements depend on the attachment content type (e.g. system/DocumentReference.c) plus Claim update (system/Claim.u). See Authentication.

Parameters

Attachment sub-parameters (nested part elements):

Processing flow

1. Validation — The Parameters resource is validated against the CDex Parameters Submit Attachment profile. Missing required parameters or invalid structure returns HTTP 422.
2. Claim Lookup — The system searches for an existing Claim matching the TrackingId identifier and AttachTo use code. If no matching Claim is found, the request is rejected with HTTP 422. Unsolicited attachments (where no prior Claim exists) are not supported.
3. Decision Check — If the Claim's latest ClaimResponse has outcome = "complete", the prior authorization is finalized and the request is rejected with HTTP 422 (business-rule). The diagnostic carries the ClaimResponse.disposition so the caller can tell an approved authorization from a denied one.
4. Duplicate Check — Attachments whose Content resource id is already linked from the Claim's supportingInfo are rejected. When every attachment in the request collides, the request fails with HTTP 422 (duplicate). When only some collide, the non-colliding attachments are attached and the response is HTTP 200 with a warning issue listing the collisions. To submit new content, use a unique id or omit id to have one generated.
5. Cloud Storage Upload — For DocumentReference resources containing inline base64 data (content[].attachment.data), the data is automatically uploaded to cloud storage. The base64 data is replaced with a URL reference, and the size field is populated.
6. Content Persistence — All attachment content resources are persisted in Aidbox via a FHIR transaction bundle.
7. Claim Association — The Claim is updated with new supportingInfo entries referencing the persisted content resources. Each entry includes a fixed PAS-valid category code and an optional code from the Attachment's Code parameter.
8. Re-queue on Final — see below.

Re-queue on Final

When Final is true (the default), a successful submission puts the prior authorization back in review: the Claim's latest ClaimResponse gets outcome set to "queued", and its disposition, preAuthRef, and communicationRequest elements are removed. A system watching the ClaimResponse (via Claim/$inquire or Event Notifications) will therefore see a pended decision revert to queued, and previously present fields disappear, until the payer's review of the new documentation produces a fresh decision.

With Final = false the ClaimResponse is left untouched — use it to stream attachments across several calls and set Final = true on the last one.

Error responses

Example

POST /fhir/$submit-attachment
Content-Type: application/json
Accept: application/json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "TrackingId",
      "valueIdentifier": {
        "system": "http://example.org/claim-id",
        "value": "claim-1765213116210"
      }
    },
    {
      "name": "AttachTo",
      "valueCode": "preauthorization"
    },
    {
      "name": "MemberId",
      "valueIdentifier": {
        "system": "http://example.org/MIN",
        "value": "99999"
      }
    },
    {
      "name": "Attachment",
      "part": [
        {
          "name": "Code",
          "valueCodeableConcept": {
            "coding": [
              {
                "system": "http://loinc.org",
                "code": "11506-3",
                "display": "Progress note"
              }
            ]
          }
        },
        {
          "name": "Content",
          "resource": {
            "resourceType": "DocumentReference",
            "status": "current",
            "type": {
              "coding": [
                { "system": "http://loinc.org", "code": "11506-3", "display": "Progress note" }
              ]
            },
            "content": [
              {
                "attachment": {
                  "contentType": "text/plain",
                  "data": "UHJvZ3Jlc3Mgbm90ZSBjb250ZW50IGZvciB0aGUgcGF0aWVudCB2aXNpdC4="
                }
              }
            ]
          }
        }
      ]
    },
    {
      "name": "Final",
      "valueBoolean": true
    }
  ]
}

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "information",
      "code": "informational",
      "diagnostics": "Attachments accepted and associated with Claim/claim-1765213116210"
    }
  ]
}

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "business-rule",
      "diagnostics": "Cannot submit attachments for Claim/claim-1765213116210: ClaimResponse outcome=complete, disposition=Denied (prior authorization denied)."
    }
  ]
}

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "duplicate",
      "diagnostics": "Attachment id collision: DocumentReference/doc-1 already linked to Claim/claim-1765213116210. To submit new content use a unique id, or omit `id` to have one auto-generated."
    }
  ]
}

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "diagnostics": "No matching Claim found for the given TrackingId. Unsolicited attachments are not supported."
    }
  ]
}