Provider System Access Specimen

Overview

The Specimen resource represents a sample taken from a biological entity for testing, examination, or analysis. This includes blood samples, tissue samples, urine samples, and other biological materials collected for diagnostic purposes.

Supported Profiles:

• US Core Specimen Profile

Use Cases:

• Query for specimens collected from a specific patient
• Track specimen collection and processing information
• Link specimens to laboratory results and diagnostic reports
• Manage specimen chain of custody and provenance

Relationships:

• Patient: References the individual from whom the specimen was collected
• Provenance: Tracks the source and history of specimen information

Resource Schema

Key Fields:

Field	Type	Description	Required
id	string	Unique identifier for the resource	Yes
status	code	Specimen status (available, unavailable, unsatisfactory, entered-in-error)	No
type	CodeableConcept	Kind of material that forms the specimen	No
subject	Reference(Patient)	Where the specimen came from	Yes
collection	BackboneElement	Collection details	No
collection.collectedDateTime	dateTime	Collection time	No
collection.collector	Reference(Practitioner/PractitionerRole)	Who collected the specimen	No
collection.method	CodeableConcept	Technique for collection	No
collection.bodySite	CodeableConcept	Anatomical collection site	No

JSON Example:

{
    "resourceType": "Specimen",
    "id": "example",
    "meta": {
        "lastUpdated": "2022-08-19T13:58:00.000+00:00"
    },
    "status": "available",
    "type": {
        "coding": [
            {
                "system": "http://snomed.info/sct",
                "code": "119297000",
                "display": "Blood specimen"
            }
        ]
    },
    "subject": {
        "reference": "Patient/example"
    },
    "collection": {
        "collectedDateTime": "2022-08-19T08:30:00.000Z",
        "collector": {
            "reference": "Practitioner/example"
        },
        "method": {
            "coding": [
                {
                    "system": "http://snomed.info/sct",
                    "code": "28520004",
                    "display": "Venipuncture"
                }
            ]
        },
        "bodySite": {
            "coding": [
                {
                    "system": "http://snomed.info/sct",
                    "code": "49852007",
                    "display": "Structure of median cubital vein"
                }
            ]
        }
    }
}

Operations

The Certified API Specimen resource supports the following operations. However, support varies by the targeted CareRecord or solution.

CareRecord / Solution	Create	Read	Update	Search
GEHRIMED	-	Yes	-	Yes
myAvatar	-	Yes	-	Yes
myEvolv	-	Yes	-	Yes
myUnity	-	Yes	-	Yes
TheraOffice	-	Yes	-	Yes

Read: Retrieves a specific Specimen resource by its unique identifier.

• Endpoint: GET /Specimen/{id}

Search: Search for specimens using various criteria.

GET Method

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

Production

GET /Specimen?parameter=value

Preview

GET /Specimen?parameter=value

POST Method

Use POST for complex searches with form-encoded parameters.

Production

POST /Specimen/_search

Preview

POST /Specimen/_search

Search Parameters

Patient-based Search:

Parameter	Type	Required	Description	Example
patient	reference	Yes	REQUIRED The patient the specimen comes from	patient=Patient/patient-123

| _lastUpdated | date | No | Only return resources which were last updated as specified by the given range | _lastUpdated=ge2022-01-01 | | _revinclude | special | No | Include Provenance resources that reference this Specimen | _revinclude=Provenance:target |

ID-based Search:

Parameter	Type	Required	Description	Example

| _lastUpdated | date | No | Only return resources which were last updated as specified by the given range | _lastUpdated=ge2022-01-01 | | _revinclude | special | No | Include Provenance resources that reference this Specimen | _revinclude=Provenance:target |

Common Search Patterns

Find specimens for a patient:

GET /Specimen?patient=Patient/patient-123

Search with date filter:

GET /Specimen?patient=Patient/patient-123&_lastUpdated=ge2022-01-01

Examples

Read Examples:

Production

Read Specimen by ID

curl -X GET https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Specimen/1032702 \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

Search Specimen by ID

curl -X GET "https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Specimen?_id=1032702" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

Preview

Read Specimen by ID

curl -X GET https://fhirtest.netsmartcloud.com/provider/system-access/v2/{tenant}/Specimen/1032702 \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

Search Specimen by ID

curl -X GET "https://fhirtest.netsmartcloud.com/provider/system-access/v2/{tenant}/Specimen?_id=1032702" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

Search Examples:

Production

Search by Patient

curl -X GET "https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Specimen?patient=1137192" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

Search with Last Updated Filter

curl -X GET "https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Specimen?patient=1137192&_lastUpdated=ge2022-01-01" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

Preview

Search by Patient

curl -X GET "https://fhirtest.netsmartcloud.com/provider/system-access/v2/{tenant}/Specimen?patient=1137192" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

Search with Last Updated Filter

curl -X GET "https://fhirtest.netsmartcloud.com/provider/system-access/v2/{tenant}/Specimen?patient=1137192&_lastUpdated=ge2022-01-01" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"