Skip to main content

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 within the Payer System Access API.

Supported Profiles:

Use Cases:

  • Query for specimens collected from patients across the payer network
  • Track specimen collection and processing information for claims processing
  • Link specimens to laboratory results and diagnostic reports
  • Support population health analytics and quality measures
  • Manage specimen chain of custody and provenance

Relationships:

  • Patient: References the individual from whom the specimen was collected
  • DiagnosticReport: Links to laboratory results based on the specimen
  • Coverage: Associated insurance coverage for specimen collection
  • Provenance: Tracks the source and history of specimen information

Resource Schema​

Key Fields:

FieldTypeDescriptionRequired
idstringUnique identifier for the resourceYes
statuscodeSpecimen status (available, unavailable, unsatisfactory, entered-in-error)No
typeCodeableConceptKind of material that forms the specimenNo
subjectReference(Patient)Where the specimen came fromYes
collectionBackboneElementCollection detailsNo
collection.collectedDateTimedateTimeCollection timeNo
collection.collectorReference(Practitioner/PractitionerRole)Who collected the specimenNo
collection.methodCodeableConceptTechnique for collectionNo
collection.bodySiteCodeableConceptAnatomical collection siteNo

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 / SolutionCreateReadUpdateSearch
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.

GET /Specimen?parameter=value

POST Method​

Use POST for complex searches with form-encoded parameters.

POST /Specimen/_search

Search Parameters​

Patient-based Search:

ParameterTypeRequiredDescriptionExample
patientreferenceYesREQUIRED The patient the specimen comes frompatient=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:

ParameterTypeRequiredDescriptionExample

| _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:

Read Specimen by ID
curl -X GET https://fhir.netsmartcloud.com/payer/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/payer/system-access/v2/{tenant-id}/Specimen?_id=1032702" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

Search Examples:

Search by Patient
curl -X GET "https://fhir.netsmartcloud.com/payer/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/payer/system-access/v2/{tenant-id}/Specimen?patient=1137192&_lastUpdated=ge2022-01-01" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"
Search with Includes
curl -X GET "https://fhir.netsmartcloud.com/payer/system-access/v2/{tenant-id}/Specimen?patient=1137192&_include=Specimen:patient" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

Integration Patterns​

Common Workflows​

1. Population Health Analytics

# Step 1: Search for specimens across patient population
GET /Specimen?_lastUpdated=ge2022-01-01&_count=100

# Step 2: Get related diagnostic reports
GET /DiagnosticReport?specimen=Specimen/specimen-123

# Step 3: Analyze coverage patterns
GET /Coverage?patient=Patient/patient-123

2. Claims Processing and Quality Measures

# Step 1: Get specimens for specific patient
GET /Specimen?patient=Patient/patient-123

# Step 2: Check related claims
GET /ExplanationOfBenefit?patient=Patient/patient-123

# Step 3: Review quality measures
GET /Observation?patient=Patient/patient-123&category=survey
  • Patient - Individual from whom the specimen was collected
  • DiagnosticReport - Laboratory results based on the specimen
  • Coverage - Insurance coverage for specimen collection
  • ExplanationOfBenefit - Claims and coverage details
  • Provenance - Source and history tracking

Include Parameters​

Use _include and _revinclude to fetch related resources:

# Get specimen with patient information
GET /Specimen?patient=Patient/patient-123&_include=Specimen:patient

# Get specimen with related provenance
GET /Specimen?_id=specimen-123&_revinclude=Provenance:target

Error Handling​

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

Specimen-Specific Error Scenarios​

  • 404 Not Found: Specimen ID doesn't exist or specimen record is inactive
  • 400 Bad Request: Invalid search parameters or malformed date formats
  • 401 Unauthorized: Invalid or missing authorization token
  • Empty Results: No specimens match the search criteria

Troubleshooting Tips​

  • No Results for Patient Search: Verify patient ID format and existence
  • Date Format Issues: Ensure collection dates are in proper ISO format
  • Authorization Issues: Verify bearer token is valid and has appropriate scopes
  • Performance Issues: Use _count parameter to limit result sets

Supported Profiles​