Procedure

Overview

The Procedure resource represents healthcare procedures, interventions, and activities performed on or for patients within the Provider Patient Access API. Procedures include surgical operations, diagnostic procedures, therapeutic interventions, and other clinical activities.

Key Use Cases:

• Retrieve patient procedure history and surgical records
• Access diagnostic and therapeutic procedure information
• Query procedures by date, status, or performer
• Support care coordination and clinical decision making

Relationships to Other Resources:

• Patient - Individual who received the procedure
• Encounter - Healthcare encounter when procedure was performed
• Practitioner - Healthcare providers who performed the procedure
• Organization - Healthcare organizations where procedures were performed

Resource Schema

Key fields in the Procedure resource:

{
  "resourceType": "Procedure",
  "id": "string",
  "identifier": [
    {
      "system": "http://example.org/procedure-id",
      "value": "proc-123"
    }
  ],
  "status": "preparation|in-progress|not-done|on-hold|stopped|completed|entered-in-error|unknown",
  "category": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "387713003",
        "display": "Surgical procedure"
      }
    ]
  },
  "code": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "80146002",
        "display": "Appendectomy"
      }
    ]
  },
  "subject": {
    "reference": "Patient/patient-123"
  },
  "encounter": {
    "reference": "Encounter/encounter-456"
  },
  "performedDateTime": "2023-12-01T10:30:00Z",
  "performer": [
    {
      "actor": {
        "reference": "Practitioner/practitioner-789"
      },
      "function": {
        "coding": [
          {
            "system": "http://snomed.info/sct",
            "code": "304292004",
            "display": "Surgeon"
          }
        ]
      }
    }
  ],
  "reasonCode": [
    {
      "coding": [
        {
          "system": "http://snomed.info/sct",
          "code": "74400008",
          "display": "Appendicitis"
        }
      ]
    }
  ],
  "bodySite": [
    {
      "coding": [
        {
          "system": "http://snomed.info/sct",
          "code": "66754008",
          "display": "Appendix structure"
        }
      ]
    }
  ]
}

Key Fields:

• id - Unique identifier for the procedure
• status - Current state of the procedure
• category - Classification of procedure type
• code - Specific procedure performed (CPT, SNOMED CT codes)
• subject - Patient who received the procedure
• encounter - Healthcare encounter when procedure was performed
• performedDateTime - When procedure was performed
• performer - Healthcare providers who performed the procedure

Operations

Read

Retrieve a specific procedure by ID.

Production

GET /Procedure/{id}

Example Request

curl -X GET https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Procedure/proc-123 \
    -H "Accept: application/fhir+json"

Preview

GET /Procedure/{id}

Example Request

curl -X GET https://fhirtest.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Procedure/proc-123 \
    -H "Accept: application/fhir+json"

Search

Search for procedures using various criteria.

GET Method

Use GET for simple searches with parameters in the query string.

Production

GET /Procedure?parameter=value

Preview

GET /Procedure?parameter=value

POST Method

Use POST for complex searches with form-encoded parameters.

Production

POST /Procedure/_search

Preview

POST /Procedure/_search

Search Parameters

Patient-based Search:

Parameter	Type	Required	Description	Example
patient	reference	Yes	REQUIRED Patient who received the procedure	patient=Patient/patient-123
date	date	No	Date/time when procedure was performed	date=2023-12-01
performer	reference	No	Healthcare provider who performed the procedure	performer=Practitioner/practitioner-789
status	token	No	Procedure status	status=completed
_revinclude	special	No	Include Provenance resources that reference this procedure	_revinclude=Provenance:target

ID-based Search:

Parameter	Type	Required	Description	Example
date	date	No	Date/time when procedure was performed	date=2023-12-01
performer	reference	No	Healthcare provider who performed the procedure	performer=Practitioner/practitioner-789
status	token	No	Procedure status	status=completed
_revinclude	special	No	Include Provenance resources that reference this procedure	_revinclude=Provenance:target

Common Search Patterns

Find procedures for a patient:

GET /Procedure?patient=Patient/patient-123&status=completed

Search by date range:

GET /Procedure?patient=Patient/patient-123&date=ge2023-01-01&date=le2023-12-31

Find procedures by performer:

GET /Procedure?performer=Practitioner/practitioner-789&_count=10

Include provenance information:

GET /Procedure?patient=Patient/patient-123&_revinclude=Provenance:target

Examples

Request Examples

Production

Search by patient

curl -X POST https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Procedure/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "patient=Patient/patient-123"

Search by patient and date range

curl -X POST https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Procedure/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "patient=Patient/patient-123&date=ge2023-01-01&date=le2023-12-31"

Search by performer

curl -X POST https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Procedure/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "performer=Practitioner/practitioner-789&status=completed"

Preview

Search by patient

curl -X POST https://fhirtest.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Procedure/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "patient=Patient/patient-123"

Search by patient and date range

curl -X POST https://fhirtest.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Procedure/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "patient=Patient/patient-123&date=ge2023-01-01&date=le2023-12-31"

Search by performer

curl -X POST https://fhirtest.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Procedure/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "performer=Practitioner/practitioner-789&status=completed"

Response Examples

Successful Search Response

Procedure Search Bundle

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 2,
  "entry": [
    {
      "resource": {
        "resourceType": "Procedure",
        "id": "proc-123",
        "identifier": [
          {
            "system": "http://example.org/procedure-id",
            "value": "proc-123"
          }
        ],
        "status": "completed",
        "category": {
          "coding": [
            {
              "system": "http://snomed.info/sct",
              "code": "387713003",
              "display": "Surgical procedure"
            }
          ]
        },
        "code": {
          "coding": [
            {
              "system": "http://snomed.info/sct",
              "code": "80146002",
              "display": "Appendectomy"
            }
          ]
        },
        "subject": {
          "reference": "Patient/patient-123"
        },
        "encounter": {
          "reference": "Encounter/encounter-456"
        },
        "performedDateTime": "2023-12-01T10:30:00Z",
        "performer": [
          {
            "actor": {
              "reference": "Practitioner/practitioner-789"
            },
            "function": {
              "coding": [
                {
                  "system": "http://snomed.info/sct",
                  "code": "304292004",
                  "display": "Surgeon"
                }
              ]
            }
          }
        ],
        "reasonCode": [
          {
            "coding": [
              {
                "system": "http://snomed.info/sct",
                "code": "74400008",
                "display": "Appendicitis"
              }
            ]
          }
        ]
      }
    }
  ]
}

Individual Procedure Response

Single Procedure Resource

{
  "resourceType": "Procedure",
  "id": "proc-456",
  "identifier": [
    {
      "system": "http://example.org/procedure-id",
      "value": "proc-456"
    }
  ],
  "status": "completed",
  "category": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "103693007",
        "display": "Diagnostic procedure"
      }
    ]
  },
  "code": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "73761001",
        "display": "Colonoscopy"
      }
    ]
  },
  "subject": {
    "reference": "Patient/patient-123"
  },
  "encounter": {
    "reference": "Encounter/encounter-789"
  },
  "performedDateTime": "2023-11-15T14:00:00Z",
  "performer": [
    {
      "actor": {
        "reference": "Practitioner/practitioner-456"
      },
      "function": {
        "coding": [
          {
            "system": "http://snomed.info/sct",
            "code": "309343006",
            "display": "Physician"
          }
        ]
      }
    }
  ],
  "reasonCode": [
    {
      "coding": [
        {
          "system": "http://snomed.info/sct",
          "code": "268547008",
          "display": "Screening for malignant neoplasm of colon"
        }
      ]
    }
  ],
  "outcome": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "385669000",
        "display": "Successful"
      }
    ]
  }
}

Empty Result Set

No Procedures Found

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 0,
  "entry": []
}

Integration Patterns

Common Workflows

1. Retrieve Patient Procedure History

# Step 1: Search for procedures for a patient
GET /Procedure?patient=Patient/patient-123&status=completed

# Step 2: Get specific procedure details
GET /Procedure/proc-123

# Step 3: Find related encounter information
GET /Encounter/encounter-456

2. Procedure Documentation Review

# Step 1: Find procedures by performer
GET /Procedure?performer=Practitioner/practitioner-789

# Step 2: Filter by date range
GET /Procedure?performer=Practitioner/practitioner-789&date=ge2023-01-01

# Step 3: Include provenance information
GET /Procedure?patient=Patient/patient-123&_revinclude=Provenance:target

Related Resources

• Patient - Individual who received the procedure
• Encounter - Healthcare encounter when procedure was performed
• Practitioner - Healthcare providers who performed the procedure
• Organization - Healthcare organizations where procedures were performed
• Provenance - Source and history tracking for procedure information

Include Parameters

Use _revinclude to fetch related resources in a single request:

# Get procedure with provenance information
GET /Procedure?patient=Patient/patient-123&_revinclude=Provenance:target

# Get procedures with encounter details
GET /Procedure?patient=Patient/patient-123&_include=Procedure:encounter

Error Handling

The Procedure resource follows standard FHIR error handling patterns. For detailed error responses and troubleshooting guidance, see the Common Errors page.

Procedure-Specific Error Scenarios

• 404 Not Found: Procedure ID doesn't exist or has been deleted
• 400 Bad Request: Invalid search parameters or malformed queries
• Empty Results: No procedures match the search criteria

Troubleshooting Tips

• Empty Results: Verify patient exists and has procedures in the specified date range
• Invalid Parameters: Check parameter names match the FHIR specification
• Performance Issues: Use _count parameter to limit result sets and improve response times

Supported Profiles

• HL7 FHIR R4 Procedure
• US Core Procedure