tmp updates

jhutchison-nava · jhutchison-nava · commit e6fe9cb5d197 · 2026-03-23T17:06:11.000-04:00
diff --git a/src/_pages/api-documentation/attestation-attribution.md b/src/_pages/api-documentation/attestation-attribution.md
@@ -10,7 +10,8 @@ in-page-nav: true
 
 ## Data Sources
 
-DPC provides you with a set of sample practitioners to complete attestation and attribution in the sandbox.
+<!-- RATIONALE: Make it explicit that users must upload sample JSON (sandbox does not preload data), to reduce confusion. -->
+DPC provides sample Practitioner, Patient, and Group JSON resources you can upload to complete attestation and attribution in the sandbox.
 
 Attestation/Attribution is when DPC establishes that you have a valid patient-practitioner relationship with Medicare and Medicaid beneficiaries. 
 
@@ -25,17 +26,26 @@ You need to keep attributions up-to-date by submitting an attestation with each
 
 ## Load sample data
 
-The DPC team has created a collection of sample Practitioner, Patient, and Group Resources to use with the sandbox. These resources can be found in our public GitHub repository as JSON files. 
+<!-- RATIONALE: Link directly to the sample bundles available in this site so users can find them without hunting elsewhere. -->
+The DPC team provides sample Practitioner and Patient resources you can upload to the sandbox:
+
+- <a href="{{ site.url }}/assets/downloads/practitioner_bundle.json">practitioner_bundle.json</a>
+- <a href="{{ site.url }}/assets/downloads/patient_bundle.json">patient_bundle.json</a>
 
 ### Uploading practitioners
 
 We include four generic Practitioner Resources to add to your organization.
 
-### Uploading Patients
+### Uploading patients
 
 The Beneficiary FHIR Data Server (BFD) maintains a list of 101 patients, along with their Medicare Beneficiary Identifiers (MBI), that match synthetic sandbox data. More details and the corresponding data files can be found on the Blue Button 2.0 API's documentation under <a href="https://bluebutton.cms.gov/developers/#sample-beneficiaries" target="_blank" rel=noopener>Sample Beneficiaries</a>.
 
-You also provide your own sample FHIR resources. These will need to fulfill the required FHIR profiles. All Patient Resources need an MBI that matches a record in BFD.
+You can also provide your own sample FHIR resources. These will need to fulfill the required FHIR profiles. All Patient Resources need an MBI that matches a record in BFD.
+
+<!-- RATIONALE: The doc referenced “find organization id” but didn’t explain how; add a small, concrete section tied to the Organization examples. -->
+### Find organization ID {#find-organization-id-2}
+
+Use the Organization endpoint to retrieve your Organization resource and its `Organization.id`.
 
 #### Request
 
@@ -44,12 +54,12 @@ GET /api/v1/Organization
 {% endraw %}{% endcapture %}
 {% include copy_snippet.html code=curlSnippet language="shell" %}
 
-#### cURL command
+#### Headers
 
+<!-- RATIONALE: Keep examples copy/pasteable by separating header listing from the cURL command; also avoid implying GET needs Content-Type/Prefer headers. -->
 {% capture curlSnippet %}{% raw %}
 Authorization: Bearer {access_token}
 Accept: application/fhir+json
-Prefer: respond-async
 {% endraw %}{% endcapture %}
 {% include copy_snippet.html code=curlSnippet language="shell" %}
 
@@ -59,7 +69,6 @@ Prefer: respond-async
 curl -v https://sandbox.dpc.cms.gov/api/v1/Organization \
      -H 'Authorization: Bearer {access_token}' \
      -H 'Accept: application/fhir+json' \
-     -H 'Content-Type: application/fhir+json' \
      -X GET
 {% endraw %}{% endcapture %}
 {% include copy_snippet.html code=curlSnippet language="shell" %}
@@ -117,12 +126,12 @@ GET /api/v1/Organization/{id}
 {% endraw %}{% endcapture %}
 {% include copy_snippet.html code=curlSnippet language="shell" %}
 
-#### cURL command
+#### Headers
 
+<!-- RATIONALE: Keep examples copy/pasteable by separating header listing from the cURL command; also avoid implying GET needs Content-Type/Prefer headers. -->
 {% capture curlSnippet %}{% raw %}
 Authorization: Bearer {access_token}
 Accept: application/fhir+json
-Prefer: respond-async
 {% endraw %}{% endcapture %}
 {% include copy_snippet.html code=curlSnippet language="shell" %}
 
@@ -132,7 +141,6 @@ Prefer: respond-async
 curl -v https://sandbox.dpc.cms.gov/api/v1/Organization/{id} \
   -H 'Authorization: Bearer {access_token}' \
   -H 'Accept: application/fhir+json' \
-  -H 'Content-Type: application/fhir+json' \
   -X GET
 {% endraw %}{% endcapture %}
 {% include copy_snippet.html code=curlSnippet language="shell" %}
@@ -176,7 +184,8 @@ curl -v https://sandbox.dpc.cms.gov/api/v1/Organization/{id} \
 
 ### Add a practitioner
 
-To register a practitioner at your organization, you must send a FHIR-formatted <a href="https://dpc.cms.gov/ig/StructureDefinition-dpc-profile-practitioner.html" target="_blank" rel=noopener>Practitioner</a> Resource in the body of your request. Don't use encoding (raw) when uploading via a POST request to the /Practitioner endpoint.
+<!-- RATIONALE: “encoding (raw)” is ambiguous; clarify as “send raw JSON body” so users know what to do in tools like Postman/cURL. -->
+To register a practitioner at your organization, you must send a FHIR-formatted <a href="https://dpc.cms.gov/ig/StructureDefinition-dpc-profile-practitioner.html" target="_blank" rel=noopener>Practitioner</a> Resource in the body of your request. Send the raw JSON body (do not form-encode it) when uploading via a POST request to the /Practitioner endpoint.
 
 The Practitioner Resource may include additional attributes detailed in the FHIR Implementation Guide within <a href="https://dpc.cms.gov/ig/StructureDefinition-dpc-profile-practitioner.html" target="_blank" rel=noopener>DPC Practitioner Profile</a>.
 
@@ -185,7 +194,8 @@ The Practitioner Resource may include additional attributes detailed in the FHIR
 - First and last name
 - Type 1 National Provider Identifier (NPI)
  
-Note: If an existing practitioner is found with the same NPI, the `/practitioner` endpoint will return that same practitioner.
+<!-- RATIONALE: Normalize endpoint casing to match the rest of the examples and avoid 404s in case of case-sensitive tooling/docs. -->
+Note: If an existing practitioner is found with the same NPI, the `/Practitioner` endpoint will return that same practitioner.
 
 #### Request
 
@@ -213,7 +223,8 @@ The Practitioner endpoint supports a $submit operation. This operation lets you
 Each individual Practitioner Resource in your bundle must satisfy the requirements on how to add a [Practitioner Resource](#add-a-practitioner). Otherwise a 422-Unprocessable Entity error will be returned.
 
 
-<a href="{{ site.url }}/assets/downloads/practitioner_bundle.json">Sample practitoner_bundle.json</a>
+<!-- RATIONALE: Fix typo in link text (“practitoner”) so readers can search/copy the filename accurately. -->
+<a href="{{ site.url }}/assets/downloads/practitioner_bundle.json">Sample practitioner_bundle.json</a>
 
 
 #### Request
@@ -269,11 +280,11 @@ GET /api/v1/Practitioner?identifier={practitioner_npi}
 
 #### cURL command:
 
+<!-- RATIONALE: The prior cURL example omitted the query parameter; keep request + cURL consistent so copy/paste works. -->
 {% capture curlSnippet %}{% raw %}
-curl -v https://sandbox.dpc.cms.gov/api/v1/Practitioner \
+curl -v 'https://sandbox.dpc.cms.gov/api/v1/Practitioner?identifier={practitioner_npi}' \
      -H 'Authorization: Bearer {access_token}' \
      -H 'Accept: application/fhir+json' \
-     -H 'Content-Type: application/fhir+json' \
      -X GET
 {% endraw %}{% endcapture %}
 {% include copy_snippet.html code=curlSnippet language="shell" %}
@@ -317,52 +328,8 @@ curl -v https://sandbox.dpc.cms.gov/api/v1/Practitioner \
 {% endraw %}{% endcapture %}
 {% include copy_snippet.html code=jsonSnippet language="json" %}
 
-## Make Practitioner/Provenance 
-
-CMS requires practitioners to attest that they have a treatment-related purpose for adding a patient to their group each time they make a group addition. This is accomplished by submitting an attestation with every request. Attestations are posted as a <a href="https://www.hl7.org/fhir/provenance.html" target="_blank" rel=noopener>Provenance</a> Resource via the X-Provenance header, as outlined in the <a href="https://www.hl7.org/fhir/implementationguide.html" target="_blank" rel=noopener>FHIR specification</a>.
-
-The attestation is then included in the X-Provenance header as part of any operations which add patients to the Group Resource.
-
-#### Example attestation for X-Provenance header
-
-{% capture jsonSnippet %}{% raw %}
-{
-  "resourceType": "Provenance",
-  "meta": {
-    "profile": [
-      "https://dpc.cms.gov/api/v1/StructureDefinition/dpc-profile-attestation"
-    ]
-  },
-  "recorded": "1990-01-01T00:00:00.000-05:00",
-  "reason": [
-    {
-      "system": "http://hl7.org/fhir/v3/ActReason",
-      "code": "TREAT"
-    }
-  ],
-  "agent": [
-    {
-      "role": [
-        {
-          "coding": [
-            {
-              "system": "http://hl7.org/fhir/v3/RoleClass",
-              "code": "AGNT"
-            }
-          ]
-        }
-      ],
-      "whoReference": {
-        "reference": "Organization/{organization_id}"
-      },
-      "onBehalfOfReference": {
-        "reference": "Practitioner/{practitioner_id}"
-      }
-    }
-  ]
-}
-{% endraw %}{% endcapture %}
-{% include copy_snippet.html code=jsonSnippet language="json" %}
+<!-- RATIONALE: Remove duplicated/renamed “Make Practitioner/Provenance” section and point readers to the canonical Attestation section to avoid drift. -->
+Attestation is required when adding patients to a Group. See the [Attestation](#attestation) section below for requirements and an example `X-Provenance` header.
 
 ## Patients
 
@@ -372,9 +339,10 @@ Since there is not any preloaded data in DPC's sandbox, the Beneficiary FHIR Dat
 
 ### Add a patient
 
-To register a patient at your organization, you must create a <a href="https://dpc.cms.gov/ig/StructureDefinition-dpc-profile-patient.html" target="_blank" rel=noopener>Patient</a> Resource as a JSON file in FHIR format. The JSON file must be in the body of your request with no encoding (raw) when uploading via a POST request to the /Patient endpoint.
+<!-- RATIONALE: Clarify “raw/encoding” wording and fix mislabeled profile link text (Patient section should refer to Patient profile). -->
+To register a patient at your organization, you must create a <a href="https://dpc.cms.gov/ig/StructureDefinition-dpc-profile-patient.html" target="_blank" rel=noopener>Patient</a> Resource as a JSON file in FHIR format. Send the raw JSON body (do not form-encode it) when uploading via a POST request to the /Patient endpoint.
 
-To create the Patient Resource, the JSON file may include additional attributes detailed in the FHIR Implementation Guide within the <a href="https://dpc.cms.gov/ig/StructureDefinition-dpc-profile-patient.html" target="_blank" rel=noopener>DPC Practitioner Profile</a>. 
+To create the Patient Resource, the JSON file may include additional attributes detailed in the FHIR Implementation Guide within the <a href="https://dpc.cms.gov/ig/StructureDefinition-dpc-profile-patient.html" target="_blank" rel=noopener>DPC Patient Profile</a>. 
 
 #### Minimum requirements 
 
@@ -385,7 +353,8 @@ To create the Patient Resource, the JSON file may include additional attributes
 
 When sharing data, DPC uses the Patient.gender property to represent the sex of the patient as maintained on record at CMS. When registering a patient to your organization, DPC will require you to submit the Patient.gender property following the corresponding value set. The input provided may be used by DPC to match and validate the patient against CMS records.
 
-Note: If an existing patient is found with the same MBI, the /patient endpoint will return that same patient.
+<!-- RATIONALE: Normalize endpoint casing for consistency with the rest of the page and examples. -->
+Note: If an existing patient is found with the same MBI, the /Patient endpoint will return that same patient.
 
 #### Example
 
@@ -535,7 +504,7 @@ curl -v https://sandbox.dpc.cms.gov/api/v1/Patient \
 
 ### List a specific patient
 
-The Patient endpoint also supports a GET /Patient operation. This operations lets you supply the Patient MBI and receive the Patient Resource. You may use this to identify a Patient's DPC ID based off on an MBI.
+The Patient endpoint also supports a GET /Patient operation. This operation lets you supply the Patient MBI and receive the Patient Resource. You may use this to identify a Patient's DPC ID based on an MBI.
 
 #### Request
 
@@ -546,11 +515,11 @@ GET /api/v1/Patient?identifier={patient_mbi}
 
 #### cURL command
 
+<!-- RATIONALE: The prior cURL example omitted the query parameter; keep request + cURL consistent so copy/paste works. -->
 {% capture curlSnippet %}{% raw %}
-curl -v https://sandbox.dpc.cms.gov/api/v1/Patient \
+curl -v 'https://sandbox.dpc.cms.gov/api/v1/Patient?identifier={patient_mbi}' \
   -H 'Authorization: Bearer {access_token}' \
   -H 'Accept: application/fhir+json' \
-  -H 'Content-Type: application/fhir+json' \
   -X GET
 {% endraw %}{% endcapture %}
 {% include copy_snippet.html code=curlSnippet language="shell" %}
@@ -610,7 +579,7 @@ Details on Provenance Resources are given in the <a href="https://www.hl7.org/fh
 Timestamp. Time when attestation was made
 Reason. Reason for the attestation (currently only: <a href="http://hl7.org/fhir/v3/ActReason#TREAT">http://hl7.org/fhir/v3/ActReason#TREAT</a> is supported)
 Organization ID. The agent making the attestation referenced by their Organization Resource ID 
- _Your Organization ID can be found in the DPC Portal by following <a href="#find-organization-id"> these instructions</a>._
+ _Your Organization ID can be found in the DPC Portal by following <a href="#find-organization-id-2"> these instructions</a>._
 Practitioner ID. The practitioner attached to the attestation referenced by their Practitioner ID. _Your Practitioner ID can be found by referencing the `{id}` variable in the resource object of your practitioner._
 
 The attestation is then included in the X-Provenance header as part of any operations which add patients to the Group Resource.
@@ -656,27 +625,32 @@ The attestation is then included in the X-Provenance header as part of any opera
 {% endraw %}{% endcapture %}
 {% include copy_snippet.html code=jsonSnippet language="json" %}
 
+<!-- RATIONALE: Users often paste multi-line JSON into headers and get hard-to-debug errors; call out the “single-line JSON string” requirement. -->
+To send this Provenance in the `X-Provenance` header, serialize it as JSON on a single line (no newlines). Your tooling may require escaping quotes when setting header values.
+
 ### Update a group
 
 Patient/practitioner relationships automatically expire after 90 days and must be re-attested by the practitioner. This is accomplished by re-attributing the patient to the practitioner's group.
 
 ### Identifying expired patients
 
-Patient attributions expire and must be renewed after 90 days. You can identify these patients through a GET request to the /Group endpoint. This will return a JSON file with all the patients attributed to the group. Evaluate this JSON for patients with attribution dates greater than 90 days.
+<!-- RATIONALE: Previous guidance referenced “attribution dates” without showing where to find them; point to Group.member.period.end and ensure the example includes it. -->
+Patient attributions expire and must be renewed after 90 days. You can identify these patients by retrieving the Group and checking each member's `period.end`.
 
 #### Request
 
 {% capture curlSnippet %}{% raw %}
-GET api/v1/Group?characteristic-value=attributed-to${group_id}
+GET /api/v1/Group/{group_id}
 {% endraw %}{% endcapture %}
 {% include copy_snippet.html code=curlSnippet language="shell" %}
 
 #### cURL command:
 
 {% capture curlSnippet %}{% raw %}
-curl -v https://sandbox.dpc.cms.gov/api/v1/Group?characteristic-value=attributed-to${group_id}
+curl -v https://sandbox.dpc.cms.gov/api/v1/Group/{group_id} \
   -H 'Authorization: Bearer {access_token}' \
-  -H 'Accept: application/fhir+json'
+  -H 'Accept: application/fhir+json' \
+  -X GET
 {% endraw %}{% endcapture %}
 {% include copy_snippet.html code=curlSnippet language="shell" %}
 
@@ -710,6 +684,10 @@ curl -v https://sandbox.dpc.cms.gov/api/v1/Group?characteristic-value=attributed
    {
      "entity": {
        "reference": "Patient/bb151edf-a8b5-4f5c-9867-69794bcb48d1"
+     },
+     "period": {
+       "start": "2020-06-17T17:44:27+00:00",
+       "end": "2020-09-15T17:44:27+00:00"
      }
    }
  ]
@@ -721,11 +699,12 @@ curl -v https://sandbox.dpc.cms.gov/api/v1/Group?characteristic-value=attributed
 
 #### cURL command
 
+<!-- RATIONALE: Fix malformed header example (stray HTML) and make the placeholder indicate a header-safe JSON string. -->
 {% capture curlSnippet %}{% raw %}
-curl -v https://sandbox.dpc.cms.gov/api/v1/Group/{group_id}/\$add
+curl -v https://sandbox.dpc.cms.gov/api/v1/Group/{group_id}/\$add \
   -H 'Authorization: Bearer {access_token}' \
   -H 'Accept: application/fhir+json' \
-  -H 'X-Provenance: {FHIR provenance resource}</span> \
+  -H 'X-Provenance: {FHIR Provenance resource (JSON string)}' \
   -X POST \
   -d @group_addition.json
 {% endraw %}{% endcapture %}
@@ -837,11 +816,12 @@ PUT /api/v1/Group/{group_id}
 
 #### cURL command
 
+<!-- RATIONALE: Same as $add: keep cURL syntactically valid and clarify `X-Provenance` expects a JSON string value. -->
 {% capture curlSnippet %}{% raw %}
 curl -v https://sandbox.dpc.cms.gov/api/v1/Group/{group_id} \
   -H 'Authorization: Bearer {access_token}' \
   -H 'Accept: application/fhir+json' \
-  -H 'X-Provenance: {FHIR provenance resource}</span> \
+  -H 'X-Provenance: {FHIR Provenance resource (JSON string)}' \
   -X PUT \
   -d @updated_group.json
 {% endraw %}{% endcapture %}
@@ -906,6 +886,9 @@ The response will return a <a href="https://www.hl7.org/fhir/STU3/bundle.html" t
 
 You can use the `Group.id` value of the returned resources to initiate an export job. Find your Group ID by referencing the `{id}` variable in your group's resource object.
 
+<!-- RATIONALE: `${var}` looked like shell interpolation; use `%24` to represent the composite delimiter unambiguously and explain what it means. -->
+In the request below, `%24` is the URL-encoded form of `$`, which separates values for FHIR composite search parameters.
+
 #### Example
 
 {% capture jsonSnippet %}{% raw %}
@@ -921,17 +904,17 @@ You can use the `Group.id` value of the returned resources to initiate an export
 #### Request
 
 {% capture curlSnippet %}{% raw %}
-GET /api/v1/Group?characteristic-value=attributed-to${practitioner_npi}
+GET /api/v1/Group?characteristic-value=attributed-to%24{practitioner_npi}
 {% endraw %}{% endcapture %}
 {% include copy_snippet.html code=curlSnippet language="shell" %}
 
 #### cURL command
 
 {% capture curlSnippet %}{% raw %}
-curl -v https://sandbox.dpc.cms.gov/api/v1/Group/{group_id} \
+curl -v 'https://sandbox.dpc.cms.gov/api/v1/Group?characteristic-value=attributed-to%24{practitioner_npi}' \
   -H 'Authorization: Bearer {access_token}' \
   -H 'Accept: application/fhir+json' \
-  -H 'X-Provenance: {FHIR provenance resource}
+  -X GET
 {% endraw %}{% endcapture %}
 {% include copy_snippet.html code=curlSnippet language="shell" %}
 
