$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>/$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. 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.
4. Content Persistence — All attachment content resources are persisted in Aidbox via a FHIR transaction bundle.
5. 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.

Error responses

Example

POST /$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": "invalid",
      "diagnostics": "No matching Claim found for the given TrackingId. Unsolicited attachments are not supported."
    }
  ]
}