Scenario: Manage the Specimen Lifecycle

Create, search, read, version-read, update, and delete FHIR R4 Specimen resources, with separately authorized permanent-deletion operations.

Authorization

Use an OAuth 2.0 access token issued by OCI Identity Domains with the DDFS resource scopes required for each Specimen interaction. The permanent-deletion operations require their separately documented authorization. Configure the client and obtain tokens by following Create an Integrated Application and DDFS Authentication Reference.

Advertised interactions

The R4 CapabilityStatement advertises create, read, version-read, update, delete, and type-search interactions for Specimen:


POST   /api/fhir/r4/Specimen
GET    /api/fhir/r4/Specimen/{rid}
GET    /api/fhir/r4/Specimen/{rid}/_history/{vid}
PUT    /api/fhir/r4/Specimen/{rid}
DELETE /api/fhir/r4/Specimen/{rid}
GET    /api/fhir/r4/Specimen

Create and update a Specimen

The following abbreviated base-FHIR R4 payload is an illustration. Supply the content required by the profiles and laboratory workflow selected for your application.

(application/fhir+json)
POST {base}/api/fhir/r4/Specimen
Content-Type: application/fhir+json

{
  "resourceType": "Specimen",
  "status": "available",
  "subject": {
    "reference": "Patient/{patient_id}"
  },
  "type": {
    "text": "Blood specimen"
  }
}

For the update request and payload requirements, see PUT /api/fhir/r4/Specimen/{rid}.

Search Specimen

The R4 Specimen search surface advertises patient in addition to _id, _lastUpdated, _profile, _tag, _count, and _total. Search by direct patient reference or with the :identifier modifier:


GET {base}/api/fhir/r4/Specimen?patient=Patient/{patient_id}
GET {base}/api/fhir/r4/Specimen?patient:identifier={system}|{value}

The _lastUpdated parameter accepts the advertised date comparators. A range can use a maximum of two repeated parameters. Do not combine date values with a comma.


GET {base}/api/fhir/r4/Specimen?_lastUpdated=ge2026-01-01T00:00:00Z&_lastUpdated=le2026-01-31T23:59:59Z

Use the advertised _count parameter when requesting a page size.

Purge previously deleted resources by type

The advertised $purgeDeleted operation is type-level:


POST {base}/api/fhir/r4/Specimen/$purgeDeleted
Content-Type: application/fhir+json

Its FHIR Parameters input requires one before value of type dateTime. It optionally accepts one integer limit from 1 through 50.

(application/fhir+json)
{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "before",
      "valueDateTime": "2026-01-01T00:00:00Z"
    },
    {
      "name": "limit",
      "valueInteger": 25
    }
  ]
}

The operation definition requires one OperationOutcome output.

Hard-delete one deleted resource

The advertised $hardDelete operation is instance-level and targets one deleted Specimen:


POST {base}/api/fhir/r4/Specimen/{rid}/$hardDelete