$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

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. A DocumentReference in Content must carry base64 data in every content[].attachment.data; a missing or malformed value returns HTTP 422 (invalid) naming the element. A deployment with SUBMIT_ATTACHMENT_ACCEPT_URL=true also accepts a content[] entry that has attachment.url and no data — see Configuration.
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 uploaded to cloud storage. The base64 data is replaced with a URL reference, size is populated, and a blank title is filled from creation, the DocumentReference.description, or a generated attachment.<ext> name. A QuestionnaireResponse is stored as submitted: an inline valueAttachment.data in any answer stays in the resource. A deployment with SUBMIT_ATTACHMENT_OFFLOAD_QUESTIONNAIRE_RESPONSE=true uploads every inline valueAttachment the same way and stores the answer with a url — see Configuration. Without cloud storage configured, data stays inline in both resource types.
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

Configuration

Two deployment flags on the prior-auth service relax the default handling of attachment content. Both are off by default and take effect on service restart.

SUBMIT_ATTACHMENT_ACCEPT_URL=true

A DocumentReference content[] entry may carry attachment.url and no data. The entry is stored as given; Payerbox does not fetch the URL, so the submitter is responsible for its reachability from the payer side.

SUBMIT_ATTACHMENT_OFFLOAD_QUESTIONNAIRE_RESPONSE=true

Inline valueAttachment.data found in a submitted QuestionnaireResponse is uploaded to cloud storage and replaced with a url, as for DocumentReference content. Requires cloud storage to be configured; with no storage the data stays inline.

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": "Invalid $submit-attachment attachment content: Attachment[0].Content.content[0].attachment.data is missing",
      "expression": ["Parameters.parameter"]
    }
  ]
}

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